summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/TODO11
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/1.3-local-configuration.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/1.3-recipes.html29
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/build-history-image-information.html80
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/build-history-package-information.html58
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/build-overview.html61
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/building-an-image-using-gpl-components.html23
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/centos-packages.html69
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/checksums.html164
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/debugging.html43
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/detailed-supported-distros.html45
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/enabling-and-disabling-build-history.html62
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/enabling-commercially-licensed-recipes.html85
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/examining-build-history-information.html70
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/faq.html791
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/fedora-packages.html62
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/figures/buildhistory-web.pngbin0 -> 49966 bytes
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/figures/buildhistory.pngbin0 -> 42062 bytes
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/figures/poky-title.pngbin0 -> 11592 bytes
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/future-development-and-limitations.html33
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/handbook.html25
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/index.html327
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/index.xml2
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/intro-getit-dev.html26
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/intro-getit.html35
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/intro-manualoverview.html73
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/intro-requirements.html23
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/intro-welcome.html30
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/intro.html30
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/invalidating-shared-state.html53
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/license-flag-matching.html91
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/licenses.html28
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/logging-with-bash.html47
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/logging-with-python.html45
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/maintaining-build-output-quality.html53
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-bblayers-conf.html27
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-image-features.html26
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-nativesdk.html25
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-proto=-in-src-uri.html32
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-python-function-whitespace.html29
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-removed-recipes.html64
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-sstate-mirrors.html36
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/migration-1.3-task-recipes.html39
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/migration.html31
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/moving-to-the-yocto-project-1.3-release.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/opensuse-packages.html60
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/other-variables-related-to-commercial-licenses.html60
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/overall-architecture.html31
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/recipe-logging-mechanisms.html41
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-commandline.html79
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-dependencies.html34
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-fetchers.html43
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-parsing.html93
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-providers.html63
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-runtask.html86
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake-tasklist.html54
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-bitbake.html48
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-autotools.html52
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-base.html28
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-binconfig.html30
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-debian.html22
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-devshell.html24
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-distutils.html31
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-externalsrc.html72
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-image.html31
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-insane.html105
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-kernel.html36
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-others.html24
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-package.html73
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-packagegroup.html33
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-perl.html31
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-pkgconfig.html27
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-sanity.html25
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-siteinfo.html39
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-src-distribute.html43
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-update-alternatives.html48
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-update-rc.d.html28
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes-useradd.html28
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-classes.html61
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-backfill.html88
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-distro.html68
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-image.html73
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features-machine.html63
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-features.html60
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-images.html137
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-structure.html98
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-variables-glos.html2800
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-config-distro.html40
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-config-local.html42
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-config-machine.html41
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-configuration.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-build.html33
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-dependencies.html33
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-paths.html29
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipe-required.html30
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality-recipes.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ref-varlocality.html41
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/required-packages-for-the-host-development-system.html22
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/resources-bugtracker.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/resources-contributions.html23
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/resources-intro.html23
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/resources-irc.html25
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/resources-links.html42
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/resources-mailinglist.html39
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/resources.html27
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state-cache.html60
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/shared-state.html134
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-basic-top-level.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-conf-bblayers.conf.html23
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-conf-local.conf.html37
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-conf-sanity_info.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-downloads.html23
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-pseudodone.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-sstate-cache.html23
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-buildstats.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-cache.html22
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-deb.html22
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-images.html44
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-ipk.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-licenses.html23
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy-rpm.html22
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-deploy.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-log.html24
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-pkgdata.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-stamps.html24
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-sysroots.html24
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp-work.html52
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build-tmp.html26
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-build.html15
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-bitbake.html40
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-build.html33
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-meta-yocto-bsp.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-meta-yocto.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-meta.html23
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-script.html53
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core-scripts.html28
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-core.html14
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-classes.html30
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-conf-distro.html25
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-conf-machine.html25
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-conf.html27
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-hob.html22
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-bsp.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-connectivity.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-core.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-devtools.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-extended.html23
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-gnome.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-graphics.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-kernel.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-multimedia.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-qt.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-rt.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-sato.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-support.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-recipes-txt.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-site.html23
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta-skeleton.html20
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/structure-meta.html21
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/support.html34
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/technical-details.html50
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/tips-and-tricks.html22
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/ubuntu-packages.html60
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/understanding-what-the-build-history-contains.html25
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/using-build-history-to-gather-image-information-only.html34
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/using-x32-right-now.html70
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html58
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-build.html24
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-bitbake.html66
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-classes.html24
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-configuration.html24
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components-metadata.html29
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-components.html52
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-configuring-LIC_FILES_CHKSUM.html23
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-bitbake.html30
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-buildfile.html24
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-dependencies.html26
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-others.html34
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-taskfailures.html27
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-taskrunning.html68
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging-variables.html22
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-debugging.html26
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-install.html28
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky-specifying-LIC_FILES_CHKSUM.html57
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/usingpoky.html48
-rw-r--r--documentation/ref-manual/eclipse/html/poky-ref-manual/x32.html35
-rw-r--r--documentation/ref-manual/eclipse/poky-ref-manual-toc.xml217
-rw-r--r--documentation/ref-manual/examples/hello-autotools/hello_2.3.bb8
-rw-r--r--documentation/ref-manual/examples/hello-single/files/helloworld.c8
-rw-r--r--documentation/ref-manual/examples/hello-single/hello.bb17
-rw-r--r--documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb14
-rw-r--r--documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb15
-rw-r--r--documentation/ref-manual/faq.xml606
-rw-r--r--documentation/ref-manual/figures/buildhistory-web.pngbin0 -> 49966 bytes
-rw-r--r--documentation/ref-manual/figures/buildhistory.pngbin0 -> 42062 bytes
-rw-r--r--documentation/ref-manual/figures/poky-title.pngbin0 -> 11592 bytes
-rw-r--r--documentation/ref-manual/introduction.xml322
-rw-r--r--documentation/ref-manual/migration.xml235
-rw-r--r--documentation/ref-manual/ref-bitbake.xml419
-rw-r--r--documentation/ref-manual/ref-classes.xml720
-rw-r--r--documentation/ref-manual/ref-features.xml294
-rw-r--r--documentation/ref-manual/ref-images.xml132
-rw-r--r--documentation/ref-manual/ref-manual-customization.xsl6
-rw-r--r--documentation/ref-manual/ref-manual.html5283
-rw-r--r--documentation/ref-manual/ref-manual.pdfbin0 -> 801466 bytes
-rw-r--r--documentation/ref-manual/ref-manual.tgzbin0 -> 199139 bytes
-rw-r--r--documentation/ref-manual/ref-manual.xml125
-rw-r--r--documentation/ref-manual/ref-structure.xml709
-rw-r--r--documentation/ref-manual/ref-style.css979
-rw-r--r--documentation/ref-manual/ref-variables.xml3018
-rw-r--r--documentation/ref-manual/ref-varlocality.xml193
-rw-r--r--documentation/ref-manual/resources.xml114
-rw-r--r--documentation/ref-manual/technical-details.xml1011
-rw-r--r--documentation/ref-manual/usingpoky.xml651
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 @@
1Handbook Todo List:
2
3 * Document adding a new IMAGE_FEATURE to the customising images section
4 * Add instructions about using zaurus/openmoko emulation
5 * Add component overview/block diagrams
6 * Software Deevelopment intro should mention its software development for
7 intended target and could be a different arch etc and thus special case.
8 * Expand insane.bbclass documentation to cover tests
9 * Document remaining classes (see list in ref-classes)
10 * Document formfactor
11
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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>4.1.1. Local Configuration</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="moving-to-the-yocto-project-1.3-release.html" title="4.1. Moving to the Yocto Project 1.3 Release">
9<link rel="prev" href="moving-to-the-yocto-project-1.3-release.html" title="4.1. Moving to the Yocto Project 1.3 Release">
10<link rel="next" href="migration-1.3-sstate-mirrors.html" title="4.1.1.1. SSTATE_MIRRORS">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.1. Local Configuration">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="1.3-local-configuration"></a>4.1.1. Local Configuration</h3></div></div></div>
15<p>
16 Differences include changes for
17 <a class="link" href="ref-variables-glos.html#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a>
18 and <code class="filename">bblayers.conf</code>.
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>4.1.2. Recipes</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="moving-to-the-yocto-project-1.3-release.html" title="4.1. Moving to the Yocto Project 1.3 Release">
9<link rel="prev" href="migration-1.3-bblayers-conf.html" title="4.1.1.2. bblayers.conf">
10<link rel="next" href="migration-1.3-python-function-whitespace.html" title="4.1.2.1. Python Function Whitespace">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2. Recipes">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="1.3-recipes"></a>4.1.2. Recipes</h3></div></div></div>
15<p>
16 Differences include changes for the following:
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<li class="listitem"><p>Python function whitespace</p></li>
20<li class="listitem"><p><code class="filename">proto=</code> in <code class="filename">SRC_URI</code></p></li>
21<li class="listitem"><p><code class="filename">nativesdk</code></p></li>
22<li class="listitem"><p>Task recipes</p></li>
23<li class="listitem"><p><code class="filename">IMAGE_FEATURES</code></p></li>
24<li class="listitem"><p>Removed recipes</p></li>
25</ul></div>
26<p>
27 </p>
28</div></body>
29</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.4.2.2. Build History Image Information</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="understanding-what-the-build-history-contains.html" title="2.4.2. Understanding What the Build History Contains">
9<link rel="prev" href="build-history-package-information.html" title="2.4.2.1. Build History Package Information">
10<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">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.2.2. Build History Image Information">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="build-history-image-information"></a>2.4.2.2. Build History Image Information</h4></div></div></div>
15<p>
16 The files produced for each image are as follows:
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<li class="listitem"><p><span class="emphasis"><em>build-id:</em></span>
20 Human-readable information about the build configuration
21 and metadata source revisions.</p></li>
22<li class="listitem"><p><span class="emphasis"><em>*.dot:</em></span>
23 Dependency graphs for the image that are
24 compatible with <code class="filename">graphviz</code>.
25 </p></li>
26<li class="listitem"><p><span class="emphasis"><em>files-in-image.txt:</em></span>
27 A list of files in the image with permissions,
28 owner, group, size, and symlink information.
29 </p></li>
30<li class="listitem"><p><span class="emphasis"><em>image-info.txt:</em></span>
31 A text file containing name-value pairs with information
32 about the image.
33 See the following listing example for more information.
34 </p></li>
35<li class="listitem"><p><span class="emphasis"><em>installed-package-names.txt:</em></span>
36 A list of installed packages by name only.</p></li>
37<li class="listitem"><p><span class="emphasis"><em>installed-package-sizes.txt:</em></span>
38 A list of installed packages ordered by size.
39 </p></li>
40<li class="listitem"><p><span class="emphasis"><em>installed-packages.txt:</em></span>
41 A list of installed packages with fuill package
42 filenames.</p></li>
43</ul></div>
44<p>
45 </p>
46<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
47<h3 class="title">Note</h3>
48 Installed package information is able to be gathered and
49 produced even if package management is disabled for the final
50 image.
51 </div>
52<p>
53 </p>
54<p>
55 Here is an example of <code class="filename">image-info.txt</code>:
56 </p>
57<pre class="literallayout">
58 DISTRO = poky
59 DISTRO_VERSION = 1.1+snapshot-20120207
60 USER_CLASSES = image-mklibs image-prelink
61 IMAGE_CLASSES = image_types
62 IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \
63 package-management ssh-server-dropbear package-management
64 IMAGE_LINGUAS = en-us en-gb
65 IMAGE_INSTALL = task-core-boot task-base-extended
66 BAD_RECOMMENDATIONS =
67 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ;
68 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
69 IMAGESIZE = 171816
70 </pre>
71<p>
72 Other than <code class="filename">IMAGESIZE</code>, which is the
73 total size of the files in the image in Kbytes, the
74 name-value pairs are variables that may have influenced the
75 content of the image.
76 This information is often useful when you are trying to determine
77 why a change in the package or file listings has occurred.
78 </p>
79</div></body>
80</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.4.2.1. Build History Package Information</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="understanding-what-the-build-history-contains.html" title="2.4.2. Understanding What the Build History Contains">
9<link rel="prev" href="understanding-what-the-build-history-contains.html" title="2.4.2. Understanding What the Build History Contains">
10<link rel="next" href="build-history-image-information.html" title="2.4.2.2. Build History Image Information">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.2.1. Build History Package Information">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="build-history-package-information"></a>2.4.2.1. Build History Package Information</h4></div></div></div>
15<p>
16 The history for each package contains a text file that has
17 name-value pairs with information about the package.
18 For example, <code class="filename">buildhistory/packages/core2-poky-linux/busybox/busybox/latest</code>
19 contains the following:
20 </p>
21<pre class="literallayout">
22 PV = 1.19.3
23 PR = r3
24 RDEPENDS = update-rc.d eglibc (&gt;= 2.13)
25 RRECOMMENDS = busybox-syslog busybox-udhcpc
26 PKGSIZE = 564701
27 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
28 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
29 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
30 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
31 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
32 </pre>
33<p>
34 Most of these name-value pairs corresponds to variables used
35 to produce the package.
36 The exceptions are <code class="filename">FILELIST</code>, which is the
37 actual list of files in the package, and
38 <code class="filename">PKGSIZE</code>, which is the total size of files
39 in the package in bytes.
40 </p>
41<p>
42 There is also a file corresponding to the recipe from which the
43 package came (e.g.
44 <code class="filename">buildhistory/packages/core2-poky-linux/busybox/latest</code>):
45 </p>
46<pre class="literallayout">
47 PV = 1.19.3
48 PR = r3
49 DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \
50 virtual/libc update-rc.d-native
51 PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \
52 busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \
53 busybox-staticdev busybox-locale
54 </pre>
55<p>
56 </p>
57</div></body>
58</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.1.1. Build Overview</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-build.html" title="2.1. Running a Build">
9<link rel="prev" href="usingpoky-build.html" title="2.1. Running a Build">
10<link rel="next" href="building-an-image-using-gpl-components.html" title="2.1.2. Building an Image Using GPL Components">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.1.1. Build Overview">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="build-overview"></a>2.1.1. Build Overview</h3></div></div></div>
15<p>
16 The first thing you need to do is set up the OpenEmbedded build environment by sourcing
17 the <a class="link" href="structure-core-script.html" title="5.1.10. oe-init-build-env">environment setup script</a> as follows:
18 </p>
19<pre class="literallayout">
20 $ source oe-init-build-env [build_dir]
21 </pre>
22<p>
23 </p>
24<p>
25 The <code class="filename">build_dir</code> is optional and specifies the directory the
26 OpenEmbedded build system uses for the build -
27 the <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.
28 If you do not specify a Build Directory it defaults to <code class="filename">build</code>
29 in your current working directory.
30 A common practice is to use a different Build Directory for different targets.
31 For example, <code class="filename">~/build/x86</code> for a <code class="filename">qemux86</code>
32 target, and <code class="filename">~/build/arm</code> for a <code class="filename">qemuarm</code> target.
33 See <a class="link" href="structure-core-script.html" title="5.1.10. oe-init-build-env">oe-init-build-env</a>
34 for more information on this script.
35 </p>
36<p>
37 Once the build environment is set up, you can build a target using:
38 </p>
39<pre class="literallayout">
40 $ bitbake &lt;target&gt;
41 </pre>
42<p>
43 </p>
44<p>
45 The <code class="filename">target</code> is the name of the recipe you want to build.
46 Common targets are the images in <code class="filename">meta/recipes-core/images</code>,
47 <code class="filename">/meta/recipes-sato/images</code>, etc. all found in the
48 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
49 Or, the target can be the name of a recipe for a specific piece of software such as
50 <span class="application">busybox</span>.
51 For more details about the images the OpenEmbedded build system supports, see the
52 "<a class="link" href="ref-images.html" title="Chapter 8. Images">Images</a>" chapter.
53 </p>
54<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
55<h3 class="title">Note</h3>
56 Building an image without GNU General Public License Version 3 (GPLv3) components
57 is only supported for minimal and base images.
58 See the "<a class="link" href="ref-images.html" title="Chapter 8. Images">Images</a>" chapter for more information.
59 </div>
60</div></body>
61</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.1.2. Building an Image Using GPL Components</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-build.html" title="2.1. Running a Build">
9<link rel="prev" href="build-overview.html" title="2.1.1. Build Overview">
10<link rel="next" href="usingpoky-install.html" title="2.2. Installing and Using the Result">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.1.2. Building an Image Using GPL Components">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="building-an-image-using-gpl-components"></a>2.1.2. Building an Image Using GPL Components</h3></div></div></div>
15<p>
16 When building an image using GPL components, you need to maintain your original
17 settings and not switch back and forth applying different versions of the GNU
18 General Public License.
19 If you rebuild using different versions of GPL, dependency errors might occur
20 due to some components not being rebuilt.
21 </p>
22</div></body>
23</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>1.3.2.4. CentOS Packages</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="required-packages-for-the-host-development-system.html" title="1.3.2. Required Packages for the Host Development System">
9<link rel="prev" href="opensuse-packages.html" title="1.3.2.3. OpenSUSE Packages">
10<link rel="next" href="intro-getit.html" title="1.4. Obtaining the Yocto Project">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3.2.4. CentOS Packages">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="centos-packages"></a>1.3.2.4. CentOS Packages</h4></div></div></div>
15<p>
16 The following list shows the required packages by function
17 given a supported CentOS Linux distribution:
18 </p>
19<div class="itemizedlist"><ul class="itemizedlist" type="disc">
20<li class="listitem">
21<p><span class="emphasis"><em>Essentials:</em></span>
22 Packages needed to build an image for a headless
23 system:
24 </p>
25<pre class="literallayout">
26 $ sudo yum -y install gawk make wget tar bzip2 gzip python unzip perl patch \
27 diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath
28 </pre>
29</li>
30<li class="listitem">
31<p><span class="emphasis"><em>Graphical Extras:</em></span>
32 Packages recommended if the host system has graphics support:
33 </p>
34<pre class="literallayout">
35 $ sudo yum -y install SDL-devel xterm
36 </pre>
37</li>
38<li class="listitem">
39<p><span class="emphasis"><em>Documentation:</em></span>
40 Packages needed if you are going to build out the
41 Yocto Project documentation manuals:
42 </p>
43<pre class="literallayout">
44 $ sudo yum -y install make docbook-style-dsssl docbook-style-xsl \
45 docbook-dtds docbook-utils fop libxslt
46 </pre>
47</li>
48<li class="listitem">
49<p><span class="emphasis"><em>ADT Installer Extras:</em></span>
50 Packages needed if you are going to be using the
51 <a class="link" href="../adt-manual/using-the-adt-installer.html" target="_self">Application Development Toolkit (ADT) Installer</a>:
52 </p>
53<pre class="literallayout">
54 $ sudo yum -y install autoconf automake libtool glib2-devel
55 </pre>
56</li>
57</ul></div>
58<p>
59 </p>
60<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
61<h3 class="title">Note</h3>Depending on the CentOS version you are using, other requirements
62 and dependencies might exist.
63 For details, you should look at the CentOS sections on the
64 <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies" target="_self">Poky/GettingStarted/Dependencies</a>
65 wiki page.</div>
66<p>
67 </p>
68</div></body>
69</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.2.2. Checksums (Signatures)</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="shared-state-cache.html" title="3.2. Shared State Cache">
9<link rel="prev" href="overall-architecture.html" title="3.2.1. Overall Architecture">
10<link rel="next" href="shared-state.html" title="3.2.3. Shared State">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.2. Checksums (Signatures)">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="checksums"></a>3.2.2. Checksums (Signatures)</h3></div></div></div>
15<p>
16 The shared state code uses a checksum, which is a unique signature of a task's
17 inputs, to determine if a task needs to be run again.
18 Because it is a change in a task's inputs that triggers a rerun, the process
19 needs to detect all the inputs to a given task.
20 For shell tasks, this turns out to be fairly easy because
21 the build process generates a "run" shell script for each task and
22 it is possible to create a checksum that gives you a good idea of when
23 the task's data changes.
24 </p>
25<p>
26 To complicate the problem, there are things that should not be included in
27 the checksum.
28 First, there is the actual specific build path of a given task -
29 the <code class="filename">WORKDIR</code>.
30 It does not matter if the working directory changes because it should not
31 affect the output for target packages.
32 Also, the build process has the objective of making native/cross packages relocatable.
33 The checksum therefore needs to exclude <code class="filename">WORKDIR</code>.
34 The simplistic approach for excluding the working directory is to set
35 <code class="filename">WORKDIR</code> to some fixed value and create the checksum
36 for the "run" script.
37 </p>
38<p>
39 Another problem results from the "run" scripts containing functions that
40 might or might not get called.
41 The incremental build solution contains code that figures out dependencies
42 between shell functions.
43 This code is used to prune the "run" scripts down to the minimum set,
44 thereby alleviating this problem and making the "run" scripts much more
45 readable as a bonus.
46 </p>
47<p>
48 So far we have solutions for shell scripts.
49 What about python tasks?
50 The same approach applies even though these tasks are more difficult.
51 The process needs to figure out what variables a python function accesses
52 and what functions it calls.
53 Again, the incremental build solution contains code that first figures out
54 the variable and function dependencies, and then creates a checksum for the data
55 used as the input to the task.
56 </p>
57<p>
58 Like the <code class="filename">WORKDIR</code> case, situations exist where dependencies
59 should be ignored.
60 For these cases, you can instruct the build process to ignore a dependency
61 by using a line like the following:
62 </p>
63<pre class="literallayout">
64 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
65 </pre>
66<p>
67 This example ensures that the <code class="filename">PACKAGE_ARCHS</code> variable does not
68 depend on the value of <code class="filename">MACHINE</code>, even if it does reference it.
69 </p>
70<p>
71 Equally, there are cases where we need to add dependencies BitBake is not able to find.
72 You can accomplish this by using a line like the following:
73 </p>
74<pre class="literallayout">
75 PACKAGE_ARCHS[vardeps] = "MACHINE"
76 </pre>
77<p>
78 This example explicitly adds the <code class="filename">MACHINE</code> variable as a
79 dependency for <code class="filename">PACKAGE_ARCHS</code>.
80 </p>
81<p>
82 Consider a case with inline python, for example, where BitBake is not
83 able to figure out dependencies.
84 When running in debug mode (i.e. using <code class="filename">-DDD</code>), BitBake
85 produces output when it discovers something for which it cannot figure out
86 dependencies.
87 The Yocto Project team has currently not managed to cover those dependencies
88 in detail and is aware of the need to fix this situation.
89 </p>
90<p>
91 Thus far, this section has limited discussion to the direct inputs into a task.
92 Information based on direct inputs is referred to as the "basehash" in the
93 code.
94 However, there is still the question of a task's indirect inputs - the
95 things that were already built and present in the Build Directory.
96 The checksum (or signature) for a particular task needs to add the hashes
97 of all the tasks on which the particular task depends.
98 Choosing which dependencies to add is a policy decision.
99 However, the effect is to generate a master checksum that combines the basehash
100 and the hashes of the task's dependencies.
101 </p>
102<p>
103 At the code level, there are a variety of ways both the basehash and the
104 dependent task hashes can be influenced.
105 Within the BitBake configuration file, we can give BitBake some extra information
106 to help it construct the basehash.
107 The following statements effectively result in a list of global variable
108 dependency excludes - variables never included in any checksum:
109 </p>
110<pre class="literallayout">
111 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH"
112 BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS"
113 BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER"
114 BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET"
115 </pre>
116<p>
117 The previous example actually excludes
118 <a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>
119 since it is actually constructed as a path within
120 <a class="link" href="ref-variables-glos.html#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>, which is on
121 the whitelist.
122 </p>
123<p>
124 The rules for deciding which hashes of dependent tasks to include through
125 dependency chains are more complex and are generally accomplished with a
126 python function.
127 The code in <code class="filename">meta/lib/oe/sstatesig.py</code> shows two examples
128 of this and also illustrates how you can insert your own policy into the system
129 if so desired.
130 This file defines the two basic signature generators <code class="filename">OE-Core</code>
131 uses: "OEBasic" and "OEBasicHash".
132 By default, there is a dummy "noop" signature handler enabled in BitBake.
133 This means that behavior is unchanged from previous versions.
134 <code class="filename">OE-Core</code> uses the "OEBasic" signature handler by default
135 through this setting in the <code class="filename">bitbake.conf</code> file:
136 </p>
137<pre class="literallayout">
138 BB_SIGNATURE_HANDLER ?= "OEBasic"
139 </pre>
140<p>
141 The "OEBasicHash" <code class="filename">BB_SIGNATURE_HANDLER</code> is the same as the
142 "OEBasic" version but adds the task hash to the stamp files.
143 This results in any metadata change that changes the task hash, automatically
144 causing the task to be run again.
145 This removes the need to bump <a class="link" href="ref-variables-glos.html#var-PR" title="PR"><code class="filename">PR</code></a>
146 values and changes to metadata automatically ripple across the build.
147 Currently, this behavior is not the default behavior for <code class="filename">OE-Core</code>
148 but is the default in <code class="filename">poky</code>.
149 </p>
150<p>
151 It is also worth noting that the end result of these signature generators is to
152 make some dependency and hash information available to the build.
153 This information includes:
154 </p>
155<pre class="literallayout">
156 BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe
157 BB_BASEHASH_&lt;filename:taskname&gt; - the base hashes for each dependent task
158 BBHASHDEPS_&lt;filename:taskname&gt; - The task dependencies for each task
159 BB_TASKHASH - the hash of the currently running task
160 </pre>
161<p>
162 </p>
163</div></body>
164</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.2.4.1. Debugging</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="tips-and-tricks.html" title="3.2.4. Tips and Tricks">
9<link rel="prev" href="tips-and-tricks.html" title="3.2.4. Tips and Tricks">
10<link rel="next" href="invalidating-shared-state.html" title="3.2.4.2. Invalidating Shared State">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.4.1. Debugging">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="debugging"></a>3.2.4.1. Debugging</h4></div></div></div>
15<p>
16 When things go wrong, debugging needs to be straightforward.
17 Because of this, the Yocto Project team included strong debugging
18 tools:
19 </p>
20<div class="itemizedlist"><ul class="itemizedlist" type="disc">
21<li class="listitem"><p>Whenever a shared state package is written out, so is a
22 corresponding <code class="filename">.siginfo</code> file.
23 This practice results in a pickled python database of all
24 the metadata that went into creating the hash for a given shared state
25 package.</p></li>
26<li class="listitem"><p>If BitBake is run with the <code class="filename">--dump-signatures</code>
27 (or <code class="filename">-S</code>) option, BitBake dumps out
28 <code class="filename">.siginfo</code> files in
29 the stamp directory for every task it would have executed instead of
30 building the specified target package.</p></li>
31<li class="listitem"><p>There is a <code class="filename">bitbake-diffsigs</code> command that
32 can process these <code class="filename">.siginfo</code> files.
33 If one file is specified, it will dump out the dependency
34 information in the file.
35 If two files are specified, it will compare the two files and dump out
36 the differences between the two.
37 This allows the question of "What changed between X and Y?" to be
38 answered easily.</p></li>
39</ul></div>
40<p>
41 </p>
42</div></body>
43</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>1.3.1. Supported Linux Distributions</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="intro-requirements.html" title="1.3. System Requirements">
9<link rel="prev" href="intro-requirements.html" title="1.3. System Requirements">
10<link rel="next" href="required-packages-for-the-host-development-system.html" title="1.3.2. Required Packages for the Host Development System">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3.1. Supported Linux Distributions">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="detailed-supported-distros"></a>1.3.1. Supported Linux Distributions</h3></div></div></div>
15<p>
16 Currently, the Yocto Project is supported on the following distributions:
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<li class="listitem"><p>Ubuntu 10.04.4 LTS</p></li>
20<li class="listitem"><p>Ubuntu 11.10</p></li>
21<li class="listitem"><p>Ubuntu 12.04.1 LTS</p></li>
22<li class="listitem"><p>Ubuntu 12.04.1 LTS</p></li>
23<li class="listitem"><p>Ubuntu 12.10</p></li>
24<li class="listitem"><p>Fedora release 16 (Verne)</p></li>
25<li class="listitem"><p>Fedora release 17 (Beefy Miracle)</p></li>
26<li class="listitem"><p>Fedora release 18 (Spherical Cow)</p></li>
27<li class="listitem"><p>CentOS release 5.6 (Final)</p></li>
28<li class="listitem"><p>CentOS release 5.7 (Final)</p></li>
29<li class="listitem"><p>CentOS release 5.8 (Final)</p></li>
30<li class="listitem"><p>CentOS release 6.3 (Final)</p></li>
31<li class="listitem"><p>Debian GNU/Linux 6.0.6 (squeeze)</p></li>
32<li class="listitem"><p>openSUSE 11.4</p></li>
33<li class="listitem"><p>openSUSE 12.1</p></li>
34<li class="listitem"><p>openSUSE 12.2</p></li>
35</ul></div>
36<p>
37 </p>
38<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
39<h3 class="title">Note</h3>
40 For additional information on distributions that support the
41 Yocto Project, see the
42 <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Distribution_Support" target="_self">Distribution Support</a> wiki page.
43 </div>
44</div></body>
45</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.4.1. Enabling and Disabling Build History</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="maintaining-build-output-quality.html" title="2.4. Maintaining Build Output Quality">
9<link rel="prev" href="maintaining-build-output-quality.html" title="2.4. Maintaining Build Output Quality">
10<link rel="next" href="understanding-what-the-build-history-contains.html" title="2.4.2. Understanding What the Build History Contains">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.1. Enabling and Disabling Build History">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="enabling-and-disabling-build-history"></a>2.4.1. Enabling and Disabling Build History</h3></div></div></div>
15<p>
16 Build history is disabled by default.
17 To enable it, add the following statements to the end of your
18 <code class="filename">conf/local.conf</code> file found in the
19 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>:
20 </p>
21<pre class="literallayout">
22 INHERIT += "buildhistory"
23 BUILDHISTORY_COMMIT = "1"
24 </pre>
25<p>
26 Enabling build history as previously described
27 causes the build process to collect build
28 output information and commit it to a local
29 <a class="link" href="../dev-manual/git.html" target="_self">Git</a> repository.
30 </p>
31<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
32<h3 class="title">Note</h3>
33 Enabling build history increases your build times slightly,
34 particularly for images, and increases the amount of disk
35 space used during the build.
36 </div>
37<p>
38 </p>
39<p>
40 You can disable build history by removing the previous statements
41 from your <code class="filename">conf/local.conf</code> file.
42 However, you should realize that enabling and disabling
43 build history in this manner can change the
44 <code class="filename">do_package</code> task checksums, which if you
45 are using the OEBasicHash signature generator (the default
46 for many current distro configurations including
47 <code class="filename">DISTRO = "poky"</code> and
48 <code class="filename">DISTRO = ""</code>) will result in the packaging
49 tasks being re-run during the subsequent build.
50 </p>
51<p>
52 To disable the build history functionality without causing the
53 packaging tasks to be re-run, add just this statement to your
54 <code class="filename">conf/local.conf</code> file:
55 </p>
56<pre class="literallayout">
57 BUILDHISTORY_FEATURES = ""
58 </pre>
59<p>
60 </p>
61</div></body>
62</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.4.2. Enabling Commercially Licensed Recipes</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="licenses.html" title="3.4. Licenses">
9<link rel="prev" href="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html" title="3.4.1.2. Explanation of Syntax">
10<link rel="next" href="license-flag-matching.html" title="3.4.2.1. License Flag Matching">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4.2. Enabling Commercially Licensed Recipes">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="enabling-commercially-licensed-recipes"></a>3.4.2. Enabling Commercially Licensed Recipes</h3></div></div></div>
15<p>
16 By default, the OpenEmbedded build system disables
17 components that have commercial or other special licensing
18 requirements.
19 Such requirements are defined on a
20 recipe-by-recipe basis through the <code class="filename">LICENSE_FLAGS</code> variable
21 definition in the affected recipe.
22 For instance, the
23 <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code>
24 recipe contains the following statement:
25 </p>
26<pre class="literallayout">
27 LICENSE_FLAGS = "commercial"
28 </pre>
29<p>
30 Here is a slightly more complicated example that contains both an
31 explicit recipe name and version (after variable expansion):
32 </p>
33<pre class="literallayout">
34 LICENSE_FLAGS = "license_${PN}_${PV}"
35 </pre>
36<p>
37 In order for a component restricted by a <code class="filename">LICENSE_FLAGS</code>
38 definition to be enabled and included in an image, it
39 needs to have a matching entry in the global
40 <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, which is a variable
41 typically defined in your <code class="filename">local.conf</code> file.
42 For example, to enable
43 the <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code>
44 package, you could add either the string
45 "commercial_gst-plugins-ugly" or the more general string
46 "commercial" to <code class="filename">LICENSE_FLAGS_WHITELIST</code>.
47 See the
48 "<a class="link" href="license-flag-matching.html" title="3.4.2.1. License Flag Matching">License Flag Matching</a>" section
49 for a full explanation of how <code class="filename">LICENSE_FLAGS</code> matching works.
50 Here is the example:
51 </p>
52<pre class="literallayout">
53 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
54 </pre>
55<p>
56 Likewise, to additionally enable the package built from the recipe containing
57 <code class="filename">LICENSE_FLAGS = "license_${PN}_${PV}"</code>, and assuming
58 that the actual recipe name was <code class="filename">emgd_1.10.bb</code>,
59 the following string would enable that package as well as
60 the original <code class="filename">gst-plugins-ugly</code> package:
61 </p>
62<pre class="literallayout">
63 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
64 </pre>
65<p>
66 As a convenience, you do not need to specify the complete license string
67 in the whitelist for every package.
68 you can use an abbreviated form, which consists
69 of just the first portion or portions of the license string before
70 the initial underscore character or characters.
71 A partial string will match
72 any license that contains the given string as the first
73 portion of its license.
74 For example, the following
75 whitelist string will also match both of the packages
76 previously mentioned as well as any other packages that have
77 licenses starting with "commercial" or "license".
78 </p>
79<pre class="literallayout">
80 LICENSE_FLAGS_WHITELIST = "commercial license"
81 </pre>
82<p>
83 </p>
84</div></body>
85</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.4.2.4. Examining Build History Information</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="understanding-what-the-build-history-contains.html" title="2.4.2. Understanding What the Build History Contains">
9<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">
10<link rel="next" href="technical-details.html" title="Chapter 3. Technical Details">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.2.4. Examining Build History Information">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="examining-build-history-information"></a>2.4.2.4. Examining Build History Information</h4></div></div></div>
15<p>
16 You can examine build history output from the command line or
17 from a web interface.
18 </p>
19<p>
20 To see any changes that have occurred (assuming you have
21 <code class="filename">BUILDHISTORY_COMMIT = "1"</code>), you can simply
22 use any Git command that allows you to view the history of
23 a repository.
24 Here is one method:
25 </p>
26<pre class="literallayout">
27 $ git log -p
28 </pre>
29<p>
30 You need to realize, however, that this method does show
31 changes that are not significant (e.g. a package's size
32 changing by a few bytes).
33 </p>
34<p>
35 A command-line tool called <code class="filename">buildhistory-diff</code>
36 does exist though that queries the Git repository and prints just
37 the differences that might be significant in human-readable form.
38 Here is an example:
39 </p>
40<pre class="literallayout">
41 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
42 Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt):
43 /etc/anotherpkg.conf was added
44 /sbin/anotherpkg was added
45 * (installed-package-names.txt):
46 * anotherpkg was added
47 Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt):
48 anotherpkg was added
49 packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
50 * PR changed from "r0" to "r1"
51 * PV changed from "0.1.10" to "0.1.12"
52 packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
53 * PR changed from "r0" to "r1"
54 * PV changed from "0.1.10" to "0.1.12"
55 </pre>
56<p>
57 </p>
58<p>
59 To see changes to the build history using a web interface, follow
60 the instruction in the <code class="filename">README</code> file here.
61 <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>.
62 </p>
63<p>
64 Here is a sample screenshot of the interface:
65 </p>
66<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>
67<p>
68 </p>
69</div></body>
70</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 12. FAQ</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="ref-varlocality-recipe-build.html" title="11.2.4. Extra Build Information">
10<link rel="next" href="resources.html" title="Chapter 13. Contributing to the Yocto Project">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 12. FAQ">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="faq"></a>Chapter 12. FAQ</h2></div></div></div>
15<div class="qandaset" title="Frequently Asked Questions">
16<a name="idm1966160"></a><dl>
17<dt>12.1. <a href="faq.html#idm1965696">
18 How does Poky differ from OpenEmbedded?
19 </a>
20</dt>
21<dt>12.2. <a href="faq.html#idm1961792">
22 I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
23 Can I still use the Yocto Project?
24 </a>
25</dt>
26<dt>12.3. <a href="faq.html#idm2605168">
27 How can you claim Poky / OpenEmbedded-Core is stable?
28 </a>
29</dt>
30<dt>12.4. <a href="faq.html#idm3232752">
31 How do I get support for my board added to the Yocto Project?
32 </a>
33</dt>
34<dt>12.5. <a href="faq.html#idm3230416">
35 Are there any products built using the OpenEmbedded build system?
36 </a>
37</dt>
38<dt>12.6. <a href="faq.html#idm3227696">
39 What does the OpenEmbedded build system produce as output?
40 </a>
41</dt>
42<dt>12.7. <a href="faq.html#idm5359408">
43 How do I add my package to the Yocto Project?
44 </a>
45</dt>
46<dt>12.8. <a href="faq.html#idm5357680">
47 Do I have to reflash my entire board with a new Yocto Project image when recompiling
48 a package?
49 </a>
50</dt>
51<dt>12.9. <a href="faq.html#idm5354224">
52 What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
53 </a>
54</dt>
55<dt>12.10. <a href="faq.html#idm2088960">
56 I see the error 'chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x'.
57 What is wrong?
58 </a>
59</dt>
60<dt>12.11. <a href="faq.html#idm2085168">
61 How do I make the Yocto Project work in RHEL/CentOS?
62 </a>
63</dt>
64<dt>12.12. <a href="faq.html#idm3829808">
65 I see lots of 404 responses for files on
66 http://www.yoctoproject.org/sources/*. Is something wrong?
67 </a>
68</dt>
69<dt>12.13. <a href="faq.html#idm3827408">
70 I have machine-specific data in a package for one machine only but the package is
71 being marked as machine-specific in all cases, how do I prevent this?
72 </a>
73</dt>
74<dt>12.14. <a href="faq.html#idm5331776">
75 I'm behind a firewall and need to use a proxy server. How do I do that?
76 </a>
77</dt>
78<dt>12.15. <a href="faq.html#idm1524432">
79 What&#8217;s the difference between foo and foo-native?
80 </a>
81</dt>
82<dt>12.16. <a href="faq.html#idm1520336">
83 I'm seeing random build failures. Help?!
84 </a>
85</dt>
86<dt>12.17. <a href="faq.html#idm4636672">
87 What do we need to ship for license compliance?
88 </a>
89</dt>
90<dt>12.18. <a href="faq.html#idm4635216">
91 How do I disable the cursor on my touchscreen device?
92 </a>
93</dt>
94<dt>12.19. <a href="faq.html#idm4631744">
95 How do I make sure connected network interfaces are brought up by default?
96 </a>
97</dt>
98<dt>12.20. <a href="faq.html#idm3888832">
99 How do I create images with more free space?
100 </a>
101</dt>
102<dt>12.21. <a href="faq.html#idm619504">
103 Why don't you support directories with spaces in the pathnames?
104 </a>
105</dt>
106<dt>12.22. <a href="faq.html#idm617456">
107 How do I use an external toolchain?
108 </a>
109</dt>
110<dt>12.23. <a href="faq.html#idm4577168">
111 How does the OpenEmbedded build system obtain source code and will it work behind my
112 firewall or proxy server?
113 </a>
114</dt>
115<dt>12.24. <a href="faq.html#idm3953616">
116 Can I get rid of build output so I can start over?
117 </a>
118</dt>
119</dl>
120<table border="0" width="100%" summary="Q and A Set">
121<col align="left" width="1%">
122<col>
123<tbody>
124<tr class="question" title="12.1.">
125<td align="left" valign="top">
126<a name="idm1965696"></a><a name="idm1965568"></a><p><b>12.1.</b></p>
127</td>
128<td align="left" valign="top"><p>
129 How does Poky differ from <a class="ulink" href="http://www.openembedded.org" target="_self">OpenEmbedded</a>?
130 </p></td>
131</tr>
132<tr class="answer">
133<td align="left" valign="top"></td>
134<td align="left" valign="top"><p>
135 The term "Poky" refers to the specific reference build system that
136 the Yocto Project provides.
137 Poky is based on <a class="link" href="../dev-manual/oe-core.html" target="_self">OE-Core</a>
138 and BitBake.
139 Thus, the generic term used here for the build system is
140 the "OpenEmbedded build system."
141 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
142 changes always being merged to OE-Core or BitBake first before being pulled back
143 into Poky.
144 This practice benefits both projects immediately.
145 For a fuller description of the term "Poky", see the
146 <a class="link" href="../dev-manual/poky.html" target="_self">poky</a> term in the Yocto Project
147 Development Manual.
148 </p></td>
149</tr>
150<tr class="question" title="12.2.">
151<td align="left" valign="top">
152<a name="idm1961792"></a><a name="idm1961664"></a><p><b>12.2.</b></p>
153</td>
154<td align="left" valign="top"><p>
155 I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
156 Can I still use the Yocto Project?
157 </p></td>
158</tr>
159<tr class="answer">
160<td align="left" valign="top"></td>
161<td align="left" valign="top">
162<p>
163 You can use a stand-alone tarball to provide Python 2.6.
164 You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations:
165 </p>
166<div class="itemizedlist"><ul class="itemizedlist" type="disc">
167<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>
168<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>
169</ul></div>
170<p>
171 </p>
172<p>
173 These tarballs are self-contained with all required libraries and should work
174 on most Linux systems.
175 To use the tarballs extract them into the root
176 directory and run the appropriate command:
177 </p>
178<pre class="literallayout">
179 $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH
180 $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH
181 </pre>
182<p>
183 </p>
184<p>
185 Once you run the command, BitBake uses Python 2.6.
186 </p>
187</td>
188</tr>
189<tr class="question" title="12.3.">
190<td align="left" valign="top">
191<a name="idm2605168"></a><a name="idm2605040"></a><p><b>12.3.</b></p>
192</td>
193<td align="left" valign="top"><p>
194 How can you claim Poky / OpenEmbedded-Core is stable?
195 </p></td>
196</tr>
197<tr class="answer">
198<td align="left" valign="top"></td>
199<td align="left" valign="top">
200<p>
201 There are three areas that help with stability;
202 </p>
203<div class="itemizedlist"><ul class="itemizedlist" type="disc">
204<li class="listitem"><p>The Yocto Project team keeps
205 <a class="link" href="../dev-manual/oe-core.html" target="_self">OE-Core</a> small
206 and focused, containing around 830 recipes as opposed to the thousands
207 available in other OpenEmbedded community layers.
208 Keeping it small makes it easy to test and maintain.</p></li>
209<li class="listitem"><p>The Yocto Project team runs manual and automated tests
210 using a small, fixed set of reference hardware as well as emulated
211 targets.</p></li>
212<li class="listitem"><p>The Yocto Project uses an an autobuilder,
213 which provides continuous build and integration tests.</p></li>
214</ul></div>
215<p>
216 </p>
217</td>
218</tr>
219<tr class="question" title="12.4.">
220<td align="left" valign="top">
221<a name="idm3232752"></a><a name="idm3232624"></a><p><b>12.4.</b></p>
222</td>
223<td align="left" valign="top"><p>
224 How do I get support for my board added to the Yocto Project?
225 </p></td>
226</tr>
227<tr class="answer">
228<td align="left" valign="top"></td>
229<td align="left" valign="top">
230<p>
231 Support for an additional board is added by creating a BSP layer for it.
232 For more information on how to create a BSP layer, see the
233 <a class="link" href="../bsp-guide/index.html" target="_self">Yocto Project Board Support Package (BSP) Developer's Guide</a>.
234 </p>
235<p>
236 Usually, if the board is not completely exotic, adding support in
237 the Yocto Project is fairly straightforward.
238 </p>
239</td>
240</tr>
241<tr class="question" title="12.5.">
242<td align="left" valign="top">
243<a name="idm3230416"></a><a name="idm3230288"></a><p><b>12.5.</b></p>
244</td>
245<td align="left" valign="top"><p>
246 Are there any products built using the OpenEmbedded build system?
247 </p></td>
248</tr>
249<tr class="answer">
250<td align="left" valign="top"></td>
251<td align="left" valign="top"><p>
252 The software running on the <a class="ulink" href="http://vernier.com/labquest/" target="_self">Vernier LabQuest</a>
253 is built using the OpenEmbedded build system.
254 See the <a class="ulink" href="http://www.vernier.com/products/interfaces/labq/" target="_self">Vernier LabQuest</a>
255 website for more information.
256 There are a number of pre-production devices using the OpenEmbedded build system
257 and the Yocto Project team
258 announces them as soon as they are released.
259 </p></td>
260</tr>
261<tr class="question" title="12.6.">
262<td align="left" valign="top">
263<a name="idm3227696"></a><a name="idm3227568"></a><p><b>12.6.</b></p>
264</td>
265<td align="left" valign="top"><p>
266 What does the OpenEmbedded build system produce as output?
267 </p></td>
268</tr>
269<tr class="answer">
270<td align="left" valign="top"></td>
271<td align="left" valign="top"><p>
272 Because the same set of recipes can be used to create output of various formats, the
273 output of an OpenEmbedded build depends on how it was started.
274 Usually, the output is a flashable image ready for the target device.
275 </p></td>
276</tr>
277<tr class="question" title="12.7.">
278<td align="left" valign="top">
279<a name="idm5359408"></a><a name="idm5359280"></a><p><b>12.7.</b></p>
280</td>
281<td align="left" valign="top"><p>
282 How do I add my package to the Yocto Project?
283 </p></td>
284</tr>
285<tr class="answer">
286<td align="left" valign="top"></td>
287<td align="left" valign="top"><p>
288 To add a package, you need to create a BitBake recipe.
289 For information on how to add a package, see the section
290 "<a class="link" href="../dev-manual/usingpoky-extend-addpkg.html" target="_self">Adding a Package</a>"
291 in the Yocto Project Development Manual.
292 </p></td>
293</tr>
294<tr class="question" title="12.8.">
295<td align="left" valign="top">
296<a name="idm5357680"></a><a name="idm5357552"></a><p><b>12.8.</b></p>
297</td>
298<td align="left" valign="top"><p>
299 Do I have to reflash my entire board with a new Yocto Project image when recompiling
300 a package?
301 </p></td>
302</tr>
303<tr class="answer">
304<td align="left" valign="top"></td>
305<td align="left" valign="top"><p>
306 The OpenEmbedded build system can build packages in various formats such as
307 <code class="filename">ipk</code> for <code class="filename">opkg</code>,
308 Debian package (<code class="filename">.deb</code>), or RPM.
309 The packages can then be upgraded using the package tools on the device, much like
310 on a desktop distribution such as Ubuntu or Fedora.
311 </p></td>
312</tr>
313<tr class="question" title="12.9.">
314<td align="left" valign="top">
315<a name="idm5354224"></a><a name="idm5354096"></a><p><b>12.9.</b></p>
316</td>
317<td align="left" valign="top"><p>
318 What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
319 </p></td>
320</tr>
321<tr class="answer">
322<td align="left" valign="top"></td>
323<td align="left" valign="top"><p>
324 GNOME Mobile is a subset of the <a class="ulink" href="http://www.gnome.org" target="_self">GNOME</a>
325 platform targeted at mobile and embedded devices.
326 The the main difference between GNOME Mobile and standard GNOME is that
327 desktop-orientated libraries have been removed, along with deprecated libraries,
328 creating a much smaller footprint.
329 </p></td>
330</tr>
331<tr class="question" title="12.10.">
332<td align="left" valign="top">
333<a name="idm2088960"></a><a name="idm2088832"></a><p><b>12.10.</b></p>
334</td>
335<td align="left" valign="top"><p>
336 I see the error '<code class="filename">chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</code>'.
337 What is wrong?
338 </p></td>
339</tr>
340<tr class="answer">
341<td align="left" valign="top"></td>
342<td align="left" valign="top"><p>
343 You are probably running the build on an NTFS filesystem.
344 Use <code class="filename">ext2</code>, <code class="filename">ext3</code>, or <code class="filename">ext4</code> instead.
345 </p></td>
346</tr>
347<tr class="question" title="12.11.">
348<td align="left" valign="top">
349<a name="idm2085168"></a><a name="idm2085040"></a><p><b>12.11.</b></p>
350</td>
351<td align="left" valign="top"><p>
352 How do I make the Yocto Project work in RHEL/CentOS?
353 </p></td>
354</tr>
355<tr class="answer">
356<td align="left" valign="top"></td>
357<td align="left" valign="top">
358<p>
359 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
360 install some required packages.
361 The standard CentOS packages needed are:
362 </p>
363<div class="itemizedlist"><ul class="itemizedlist" type="disc">
364<li class="listitem"><p>"Development tools" (selected during installation)</p></li>
365<li class="listitem"><p><code class="filename">texi2html</code></p></li>
366<li class="listitem"><p><code class="filename">compat-gcc-34</code></p></li>
367</ul></div>
368<p>
369 On top of these, you need the following external packages:
370 </p>
371<div class="itemizedlist"><ul class="itemizedlist" type="disc">
372<li class="listitem"><p><code class="filename">python-sqlite2</code> from
373 <a class="ulink" href="http://dag.wieers.com/rpm/packages/python-sqlite2/" target="_self">DAG repository</a>
374 </p></li>
375<li class="listitem"><p><code class="filename">help2man</code> from
376 <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>
377</ul></div>
378<p>
379 </p>
380<p>
381 Once these packages are installed, the OpenEmbedded build system will be able
382 to build standard images.
383 However, there might be a problem with the QEMU emulator segfaulting.
384 You can either disable the generation of binary locales by setting
385 <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>
386 </code> to "0" or by removing the <code class="filename">linux-2.6-execshield.patch</code>
387 from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
388 </p>
389</td>
390</tr>
391<tr class="question" title="12.12.">
392<td align="left" valign="top">
393<a name="idm3829808"></a><a name="idm3829680"></a><p><b>12.12.</b></p>
394</td>
395<td align="left" valign="top"><p>
396 I see lots of 404 responses for files on
397 <code class="filename">http://www.yoctoproject.org/sources/*</code>. Is something wrong?
398 </p></td>
399</tr>
400<tr class="answer">
401<td align="left" valign="top"></td>
402<td align="left" valign="top"><p>
403 Nothing is wrong.
404 The OpenEmbedded build system checks any configured source mirrors before downloading
405 from the upstream sources.
406 The build system does this searching for both source archives and
407 pre-checked out versions of SCM managed software.
408 These checks help in large installations because it can reduce load on the SCM servers
409 themselves.
410 The address above is one of the default mirrors configured into the
411 build system.
412 Consequently, if an upstream source disappears, the team
413 can place sources there so builds continue to work.
414 </p></td>
415</tr>
416<tr class="question" title="12.13.">
417<td align="left" valign="top">
418<a name="idm3827408"></a><a name="idm3827280"></a><p><b>12.13.</b></p>
419</td>
420<td align="left" valign="top"><p>
421 I have machine-specific data in a package for one machine only but the package is
422 being marked as machine-specific in all cases, how do I prevent this?
423 </p></td>
424</tr>
425<tr class="answer">
426<td align="left" valign="top"></td>
427<td align="left" valign="top"><p>
428 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>
429 </code> = "0" in the <code class="filename">.bb</code> file but make sure the package is
430 manually marked as
431 machine-specific in the case that needs it.
432 The code that handles <code class="filename">SRC_URI_OVERRIDES_PACKAGE_ARCH</code> is in <code class="filename">base.bbclass</code>.
433 </p></td>
434</tr>
435<tr class="question" title="12.14.">
436<td align="left" valign="top">
437<a name="idm5331776"></a><a name="idm5331648"></a><p><b>12.14.</b></p>
438</td>
439<td align="left" valign="top"><p>
440 I'm behind a firewall and need to use a proxy server. How do I do that?
441 </p></td>
442</tr>
443<tr class="answer">
444<td align="left" valign="top"></td>
445<td align="left" valign="top">
446<p>
447 Most source fetching by the OpenEmbedded build system is done by <code class="filename">wget</code>
448 and you therefore need to specify the proxy settings in a
449 <code class="filename">.wgetrc</code> file in your home directory.
450 Example settings in that file would be
451 </p>
452<pre class="literallayout">
453 http_proxy = http://proxy.yoyodyne.com:18023/
454 ftp_proxy = http://proxy.yoyodyne.com:18023/
455 </pre>
456<p>
457 The Yocto Project also includes a <code class="filename">site.conf.sample</code>
458 file that shows how to configure CVS and Git proxy servers
459 if needed.
460 </p>
461</td>
462</tr>
463<tr class="question" title="12.15.">
464<td align="left" valign="top">
465<a name="idm1524432"></a><a name="idm1524304"></a><p><b>12.15.</b></p>
466</td>
467<td align="left" valign="top"><p>
468 What&#8217;s the difference between <code class="filename">foo</code> and <code class="filename">foo-native</code>?
469 </p></td>
470</tr>
471<tr class="answer">
472<td align="left" valign="top"></td>
473<td align="left" valign="top"><p>
474 The <code class="filename">*-native</code> targets are designed to run on the system
475 being used for the build.
476 These are usually tools that are needed to assist the build in some way such as
477 <code class="filename">quilt-native</code>, which is used to apply patches.
478 The non-native version is the one that runs on the target device.
479 </p></td>
480</tr>
481<tr class="question" title="12.16.">
482<td align="left" valign="top">
483<a name="idm1520336"></a><a name="idm1520208"></a><p><b>12.16.</b></p>
484</td>
485<td align="left" valign="top"><p>
486 I'm seeing random build failures. Help?!
487 </p></td>
488</tr>
489<tr class="answer">
490<td align="left" valign="top"></td>
491<td align="left" valign="top"><p>
492 If the same build is failing in totally different and random ways,
493 the most likely explanation is that either the hardware you're running the
494 build on has some problem, or, if you are running the build under virtualisation,
495 the virtualisation probably has bugs.
496 The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and
497 CPU activity and is sensitive to even single bit failures in any of these areas.
498 True random failures have always been traced back to hardware or virtualisation issues.
499 </p></td>
500</tr>
501<tr class="question" title="12.17.">
502<td align="left" valign="top">
503<a name="idm4636672"></a><a name="idm4636544"></a><p><b>12.17.</b></p>
504</td>
505<td align="left" valign="top"><p>
506 What do we need to ship for license compliance?
507 </p></td>
508</tr>
509<tr class="answer">
510<td align="left" valign="top"></td>
511<td align="left" valign="top"><p>
512 This is a difficult question and you need to consult your lawyer for the answer
513 for your specific case.
514 It is worth bearing in mind that for GPL compliance there needs to be enough
515 information shipped to allow someone else to rebuild the same end result
516 you are shipping.
517 This means sharing the source code, any patches applied to it, and also any
518 configuration information about how that package was configured and built.
519 </p></td>
520</tr>
521<tr class="question" title="12.18.">
522<td align="left" valign="top">
523<a name="idm4635216"></a><a name="idm4635088"></a><p><b>12.18.</b></p>
524</td>
525<td align="left" valign="top"><p>
526 How do I disable the cursor on my touchscreen device?
527 </p></td>
528</tr>
529<tr class="answer">
530<td align="left" valign="top"></td>
531<td align="left" valign="top">
532<p>
533 You need to create a form factor file as described in the
534 "<a class="link" href="../bsp-guide/bsp-filelayout-misc-recipes.html" target="_self">Miscellaneous Recipe Files</a>"
535 section and set the <code class="filename">HAVE_TOUCHSCREEN</code> variable equal to one as follows:
536 </p>
537<pre class="literallayout">
538 HAVE_TOUCHSCREEN=1
539 </pre>
540<p>
541 </p>
542</td>
543</tr>
544<tr class="question" title="12.19.">
545<td align="left" valign="top">
546<a name="idm4631744"></a><a name="idm4631616"></a><p><b>12.19.</b></p>
547</td>
548<td align="left" valign="top"><p>
549 How do I make sure connected network interfaces are brought up by default?
550 </p></td>
551</tr>
552<tr class="answer">
553<td align="left" valign="top"></td>
554<td align="left" valign="top">
555<p>
556 The default interfaces file provided by the netbase recipe does not
557 automatically bring up network interfaces.
558 Therefore, you will need to add a BSP-specific netbase that includes an interfaces
559 file.
560 See the "<a class="link" href="../bsp-guide/bsp-filelayout-misc-recipes.html" target="_self">Miscellaneous Recipe Files</a>"
561 section for information on creating these types of miscellaneous recipe files.
562 </p>
563<p>
564 For example, add the following files to your layer:
565 </p>
566<pre class="literallayout">
567 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
568 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
569 </pre>
570<p>
571 </p>
572</td>
573</tr>
574<tr class="question" title="12.20.">
575<td align="left" valign="top">
576<a name="idm3888832"></a><a name="idm3888704"></a><p><b>12.20.</b></p>
577</td>
578<td align="left" valign="top"><p>
579 How do I create images with more free space?
580 </p></td>
581</tr>
582<tr class="answer">
583<td align="left" valign="top"></td>
584<td align="left" valign="top">
585<p>
586 Images are created to be 1.2 times the size of the populated root filesystem.
587 To modify this ratio so that there is more free space available, you need to
588 set the configuration value <code class="filename">IMAGE_OVERHEAD_FACTOR</code>.
589 For example, setting <code class="filename">IMAGE_OVERHEAD_FACTOR</code> to 1.5 sets
590 the image size ratio to one and a half times the size of the populated
591 root filesystem.
592 </p>
593<pre class="literallayout">
594 IMAGE_OVERHEAD_FACTOR = "1.5"
595 </pre>
596<p>
597 </p>
598</td>
599</tr>
600<tr class="question" title="12.21.">
601<td align="left" valign="top">
602<a name="idm619504"></a><a name="idm619376"></a><p><b>12.21.</b></p>
603</td>
604<td align="left" valign="top"><p>
605 Why don't you support directories with spaces in the pathnames?
606 </p></td>
607</tr>
608<tr class="answer">
609<td align="left" valign="top"></td>
610<td align="left" valign="top"><p>
611 The Yocto Project team has tried to do this before but too many of the tools
612 the OpenEmbedded build system depends on such as <code class="filename">autoconf</code>
613 break when they find spaces in pathnames.
614 Until that situation changes, the team will not support spaces in pathnames.
615 </p></td>
616</tr>
617<tr class="question" title="12.22.">
618<td align="left" valign="top">
619<a name="idm617456"></a><a name="idm617328"></a><p><b>12.22.</b></p>
620</td>
621<td align="left" valign="top"><p>
622 How do I use an external toolchain?
623 </p></td>
624</tr>
625<tr class="answer">
626<td align="left" valign="top"></td>
627<td align="left" valign="top">
628<p>
629 The toolchain configuration is very flexible and customizable.
630 It is primarily controlled with the
631 <code class="filename"><a class="link" href="ref-variables-glos.html#var-TCMODE" title="TCMODE">TCMODE</a></code> variable.
632 This variable controls which <code class="filename">tcmode-*.inc</code> file to include
633 from the <code class="filename">meta/conf/distro/include</code> directory within the
634 <a class="link" href="../dev-manual/source-directory.html" target="_self">source directory</a>.
635 </p>
636<p>
637 The default value of <code class="filename">TCMODE</code> is "default"
638 (i.e. <code class="filename">tcmode-default.inc</code>).
639 However, other patterns are accepted.
640 In particular, "external-*" refers to external toolchains of which there are some
641 basic examples included in the OpenEmbedded Core (<code class="filename">meta</code>).
642 You can use your own custom toolchain definition in your own layer
643 (or as defined in the <code class="filename">local.conf</code> file) at the location
644 <code class="filename">conf/distro/include/tcmode-*.inc</code>.
645 </p>
646<p>
647 In addition to the toolchain configuration, you also need a corresponding toolchain recipe file.
648 This recipe file needs to package up any pre-built objects in the toolchain such as
649 <code class="filename">libgcc</code>, <code class="filename">libstdcc++</code>,
650 any locales, and <code class="filename">libc</code>.
651 An example is the <code class="filename">external-sourcery-toolchain.bb</code>, which is located
652 in <code class="filename">meta/recipes-core/meta/</code> within the source directory.
653 </p>
654</td>
655</tr>
656<tr class="question" title="12.23.">
657<td align="left" valign="top">
658<a name="idm4577168"></a><a name="idm5139136"></a><p><b>12.23.</b></p>
659</td>
660<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>
661 How does the OpenEmbedded build system obtain source code and will it work behind my
662 firewall or proxy server?
663 </p></td>
664</tr>
665<tr class="answer">
666<td align="left" valign="top"></td>
667<td align="left" valign="top">
668<p>
669 The way the build system obtains source code is highly configurable.
670 You can setup the build system to get source code in most environments if
671 HTTP transport is available.
672 </p>
673<p>
674 When the build system searches for source code, it first tries the local download directory.
675 If that location fails, Poky tries PREMIRRORS, the upstream source,
676 and then MIRRORS in that order.
677 </p>
678<p>
679 By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS
680 for SCM-based sources,
681 upstreams for normal tarballs, and then falls back to a number of other mirrors
682 including the Yocto Project source mirror if those fail.
683 </p>
684<p>
685 As an example, you could add a specific server for Poky to attempt before any
686 others by adding something like the following to the <code class="filename">local.conf</code>
687 configuration file:
688 </p>
689<pre class="literallayout">
690 PREMIRRORS_prepend = "\
691 git://.*/.* http://www.yoctoproject.org/sources/ \n \
692 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
693 http://.*/.* http://www.yoctoproject.org/sources/ \n \
694 https://.*/.* http://www.yoctoproject.org/sources/ \n"
695 </pre>
696<p>
697 </p>
698<p>
699 These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS
700 requests and direct them to the <code class="filename">http://</code> sources mirror.
701 You can use <code class="filename">file://</code> URLs to point to local directories
702 or network shares as well.
703 </p>
704<p>
705 Aside from the previous technique, these options also exist:
706 </p>
707<pre class="literallayout">
708 BB_NO_NETWORK = "1"
709 </pre>
710<p>
711 This statement tells BitBake to throw an error instead of trying to access the
712 Internet.
713 This technique is useful if you want to ensure code builds only from local sources.
714 </p>
715<p>
716 Here is another technique:
717 </p>
718<pre class="literallayout">
719 BB_FETCH_PREMIRRORONLY = "1"
720 </pre>
721<p>
722 This statement limits Poky to pulling source from the PREMIRRORS only.
723 Again, this technique is useful for reproducing builds.
724 </p>
725<p>
726 Here is another technique:
727 </p>
728<pre class="literallayout">
729 BB_GENERATE_MIRROR_TARBALLS = "1"
730 </pre>
731<p>
732 This statement tells Poky to generate mirror tarballs.
733 This technique is useful if you want to create a mirror server.
734 If not, however, the technique can simply waste time during the build.
735 </p>
736<p>
737 Finally, consider an example where you are behind an HTTP-only firewall.
738 You could make the following changes to the <code class="filename">local.conf</code>
739 configuration file as long as the PREMIRROR server is up to date:
740 </p>
741<pre class="literallayout">
742 PREMIRRORS_prepend = "\
743 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
744 http://.*/.* http://www.yoctoproject.org/sources/ \n \
745 https://.*/.* http://www.yoctoproject.org/sources/ \n"
746 BB_FETCH_PREMIRRORONLY = "1"
747 </pre>
748<p>
749 These changes would cause Poky to successfully fetch source over HTTP and
750 any network accesses to anything other than the PREMIRROR would fail.
751 </p>
752<p>
753 The build system also honors the standard shell environment variables
754 <code class="filename">http_proxy</code>, <code class="filename">ftp_proxy</code>,
755 <code class="filename">https_proxy</code>, and <code class="filename">all_proxy</code>
756 to redirect requests through proxy servers.
757 </p>
758</td>
759</tr>
760<tr class="question" title="12.24.">
761<td align="left" valign="top">
762<a name="idm3953616"></a><a name="idm3685632"></a><p><b>12.24.</b></p>
763</td>
764<td align="left" valign="top"><p>
765 Can I get rid of build output so I can start over?
766 </p></td>
767</tr>
768<tr class="answer">
769<td align="left" valign="top"></td>
770<td align="left" valign="top">
771<p>
772 Yes - you can easily do this.
773 When you use BitBake to build an image, all the build output goes into the
774 directory created when you source the <code class="filename">oe-init-build-env</code>
775 setup file.
776 By default, this <a class="link" href="../dev-manual/build-directory.html" target="_self">build directory</a>
777 is named <code class="filename">build</code> but can be named
778 anything you want.
779 </p>
780<p>
781 Within the build directory is the <code class="filename">tmp</code> directory.
782 To remove all the build output yet preserve any source code or downloaded files
783 from previous builds, simply remove the <code class="filename">tmp</code> directory.
784 </p>
785</td>
786</tr>
787</tbody>
788</table>
789</div>
790</div></body>
791</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>1.3.2.2. Fedora Packages</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="required-packages-for-the-host-development-system.html" title="1.3.2. Required Packages for the Host Development System">
9<link rel="prev" href="ubuntu-packages.html" title="1.3.2.1. Ubuntu">
10<link rel="next" href="opensuse-packages.html" title="1.3.2.3. OpenSUSE Packages">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3.2.2. Fedora Packages">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="fedora-packages"></a>1.3.2.2. Fedora Packages</h4></div></div></div>
15<p>
16 The following list shows the required packages by function
17 given a supported Fedora Linux distribution:
18 </p>
19<div class="itemizedlist"><ul class="itemizedlist" type="disc">
20<li class="listitem">
21<p><span class="emphasis"><em>Essentials:</em></span>
22 Packages needed to build an image for a headless
23 system:
24 </p>
25<pre class="literallayout">
26 $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \
27 diffutils diffstat git cpp gcc gcc-c++ eglibc-devel texinfo chrpath \
28 ccache
29 </pre>
30</li>
31<li class="listitem">
32<p><span class="emphasis"><em>Graphical Extras:</em></span>
33 Packages recommended if the host system has graphics support:
34 </p>
35<pre class="literallayout">
36 $ sudo yum install SDL-devel xterm
37 </pre>
38</li>
39<li class="listitem">
40<p><span class="emphasis"><em>Documentation:</em></span>
41 Packages needed if you are going to build out the
42 Yocto Project documentation manuals:
43 </p>
44<pre class="literallayout">
45 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
46 docbook-dtds docbook-utils fop libxslt
47 </pre>
48</li>
49<li class="listitem">
50<p><span class="emphasis"><em>ADT Installer Extras:</em></span>
51 Packages needed if you are going to be using the
52 <a class="link" href="../adt-manual/using-the-adt-installer.html" target="_self">Application Development Toolkit (ADT) Installer</a>:
53 </p>
54<pre class="literallayout">
55 $ sudo yum install autoconf automake libtool glib2-devel
56 </pre>
57</li>
58</ul></div>
59<p>
60 </p>
61</div></body>
62</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
new file mode 100644
index 0000000000..f6db86c977
--- /dev/null
+++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/figures/buildhistory-web.png
Binary files differ
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
new file mode 100644
index 0000000000..614b8ee2e4
--- /dev/null
+++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/figures/buildhistory.png
Binary files differ
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
new file mode 100644
index 0000000000..2893d84620
--- /dev/null
+++ b/documentation/ref-manual/eclipse/html/poky-ref-manual/figures/poky-title.png
Binary files differ
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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.3.2. Future Development and Limitations</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="x32.html" title="3.3. x32">
9<link rel="prev" href="support.html" title="3.3.1. Support">
10<link rel="next" href="using-x32-right-now.html" title="3.3.3. Using x32 Right Now">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.2. Future Development and Limitations">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="future-development-and-limitations"></a>3.3.2. Future Development and Limitations</h3></div></div></div>
15<p>
16 As of this Yocto Project release, the x32 psABI kernel and library interfaces
17 specifications are not finalized.
18 </p>
19<p>
20 Future Plans for the x32 psABI in the Yocto Project include the following:
21 </p>
22<div class="itemizedlist"><ul class="itemizedlist" type="disc">
23<li class="listitem"><p>Enhance and fix the few remaining recipes so they
24 work with and support x32 toolchains.</p></li>
25<li class="listitem"><p>Enhance RPM Package Manager (RPM) support for x32 binaries.</p></li>
26<li class="listitem"><p>Support larger images.</p></li>
27<li class="listitem"><p>Integrate x32 recipes, toolchain, and kernel changes from
28 <code class="filename">experimental/meta-x32</code> into OE-core.</p></li>
29</ul></div>
30<p>
31 </p>
32</div></body>
33</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.1.3. documentation</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-core.html" title="5.1. Top level core components">
9<link rel="prev" href="structure-core-build.html" title="5.1.2. build/">
10<link rel="next" href="structure-core-meta.html" title="5.1.4. meta/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.3. documentation">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="handbook"></a>5.1.3. <code class="filename">documentation</code>
15</h3></div></div></div>
16<p>
17 This directory holds the source for the Yocto Project documentation
18 as well as templates and tools that allow you to generate PDF and HTML
19 versions of the manuals.
20 Each manual is contained in a sub-folder.
21 For example, the files for this manual reside in
22 <code class="filename">poky-ref-manual</code>.
23 </p>
24</div></body>
25</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>The Yocto Project Reference Manual</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="next" href="intro.html" title="Chapter 1. Introduction">
9</head>
10<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book" title="The Yocto Project Reference Manual">
11<div class="titlepage">
12<div>
13<div><h1 class="title">
14<a name="poky-ref-manual"></a>
15 The Yocto Project Reference Manual
16 </h1></div>
17<div><div class="authorgroup">
18 <div class="author">
19<h3 class="author">
20<span class="firstname">Richard</span> <span class="surname">Purdie</span>
21</h3>
22<div class="affiliation">
23 <span class="orgname">Linux Foundation<br></span>
24 </div>
25<code class="email">&lt;<a class="email" href="mailto:richard.purdie@linuxfoundation.org">richard.purdie@linuxfoundation.org</a>&gt;</code>
26</div>
27
28 </div></div>
29<div><p class="copyright">Copyright © 2010-2013 Linux Foundation</p></div>
30<div><div class="legalnotice" title="Legal Notice">
31<a name="idm3374608"></a>
32 <p>
33 Permission is granted to copy, distribute and/or modify this document under
34 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 &amp; Wales</a> as published by Creative Commons.
35 </p>
36 <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
37<h3 class="title">Note</h3>
38 Due to production processes, there could be differences between the Yocto Project
39 documentation bundled in the release tarball and the
40 <a class="link" href="../poky-ref-manual/index.html" target="_self">Yocto Project Reference Manual</a> on
41 the <a class="ulink" href="http://www.yoctoproject.org" target="_self">Yocto Project</a> website.
42 For the latest version of this manual, see the manual on the website.
43 </div>
44 </div></div>
45<div><div class="revhistory"><table border="1" width="100%" summary="Revision history">
46<tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr>
47 <tr>
48<td align="left">Revision 4.0+git</td>
49<td align="left">24 November 2010</td>
50</tr>
51<tr><td align="left" colspan="2">Released with the Yocto Project 0.9 Release</td></tr>
52 <tr>
53<td align="left">Revision 1.0</td>
54<td align="left">6 April 2011</td>
55</tr>
56<tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr>
57 <tr>
58<td align="left">Revision 1.0.1</td>
59<td align="left">23 May 2011</td>
60</tr>
61<tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr>
62 <tr>
63<td align="left">Revision 1.1</td>
64<td align="left">6 October 2011</td>
65</tr>
66<tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr>
67 <tr>
68<td align="left">Revision 1.2</td>
69<td align="left">April 2012</td>
70</tr>
71<tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr>
72 <tr>
73<td align="left">Revision 1.3</td>
74<td align="left">October 2012</td>
75</tr>
76<tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr>
77 <tr>
78<td align="left">Revision 1.4</td>
79<td align="left">Sometime in 2013</td>
80</tr>
81<tr><td align="left" colspan="2">Released with the Yocto Project 1.4 Release.</td></tr>
82 </table></div></div>
83</div>
84<hr>
85</div>
86<div class="toc">
87<p><b>Table of Contents</b></p>
88<dl>
89<dt><span class="chapter"><a href="intro.html">1. Introduction</a></span></dt>
90<dd><dl>
91<dt><span class="section"><a href="intro-welcome.html">1.1. Introduction</a></span></dt>
92<dt><span class="section"><a href="intro-manualoverview.html">1.2. Documentation Overview</a></span></dt>
93<dt><span class="section"><a href="intro-requirements.html">1.3. System Requirements</a></span></dt>
94<dd><dl>
95<dt><span class="section"><a href="detailed-supported-distros.html">1.3.1. Supported Linux Distributions</a></span></dt>
96<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>
97</dl></dd>
98<dt><span class="section"><a href="intro-getit.html">1.4. Obtaining the Yocto Project</a></span></dt>
99<dt><span class="section"><a href="intro-getit-dev.html">1.5. Development Checkouts</a></span></dt>
100</dl></dd>
101<dt><span class="chapter"><a href="usingpoky.html">2. Using the Yocto Project</a></span></dt>
102<dd><dl>
103<dt><span class="section"><a href="usingpoky-build.html">2.1. Running a Build</a></span></dt>
104<dd><dl>
105<dt><span class="section"><a href="build-overview.html">2.1.1. Build Overview</a></span></dt>
106<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>
107</dl></dd>
108<dt><span class="section"><a href="usingpoky-install.html">2.2. Installing and Using the Result</a></span></dt>
109<dt><span class="section"><a href="usingpoky-debugging.html">2.3. Debugging Build Failures</a></span></dt>
110<dd><dl>
111<dt><span class="section"><a href="usingpoky-debugging-taskfailures.html">2.3.1. Task Failures</a></span></dt>
112<dt><span class="section"><a href="usingpoky-debugging-taskrunning.html">2.3.2. Running Specific Tasks</a></span></dt>
113<dt><span class="section"><a href="usingpoky-debugging-dependencies.html">2.3.3. Dependency Graphs</a></span></dt>
114<dt><span class="section"><a href="usingpoky-debugging-bitbake.html">2.3.4. General BitBake Problems</a></span></dt>
115<dt><span class="section"><a href="usingpoky-debugging-buildfile.html">2.3.5. Building with No Dependencies</a></span></dt>
116<dt><span class="section"><a href="usingpoky-debugging-variables.html">2.3.6. Variables</a></span></dt>
117<dt><span class="section"><a href="recipe-logging-mechanisms.html">2.3.7. Recipe Logging Mechanisms</a></span></dt>
118<dt><span class="section"><a href="usingpoky-debugging-others.html">2.3.8. Other Tips</a></span></dt>
119</dl></dd>
120<dt><span class="section"><a href="maintaining-build-output-quality.html">2.4. Maintaining Build Output Quality</a></span></dt>
121<dd><dl>
122<dt><span class="section"><a href="enabling-and-disabling-build-history.html">2.4.1. Enabling and Disabling Build History</a></span></dt>
123<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>
124</dl></dd>
125</dl></dd>
126<dt><span class="chapter"><a href="technical-details.html">3. Technical Details</a></span></dt>
127<dd><dl>
128<dt><span class="section"><a href="usingpoky-components.html">3.1. Yocto Project Components</a></span></dt>
129<dd><dl>
130<dt><span class="section"><a href="usingpoky-components-bitbake.html">3.1.1. BitBake</a></span></dt>
131<dt><span class="section"><a href="usingpoky-components-metadata.html">3.1.2. Metadata (Recipes)</a></span></dt>
132<dt><span class="section"><a href="usingpoky-components-classes.html">3.1.3. Classes</a></span></dt>
133<dt><span class="section"><a href="usingpoky-components-configuration.html">3.1.4. Configuration</a></span></dt>
134</dl></dd>
135<dt><span class="section"><a href="shared-state-cache.html">3.2. Shared State Cache</a></span></dt>
136<dd><dl>
137<dt><span class="section"><a href="overall-architecture.html">3.2.1. Overall Architecture</a></span></dt>
138<dt><span class="section"><a href="checksums.html">3.2.2. Checksums (Signatures)</a></span></dt>
139<dt><span class="section"><a href="shared-state.html">3.2.3. Shared State</a></span></dt>
140<dt><span class="section"><a href="tips-and-tricks.html">3.2.4. Tips and Tricks</a></span></dt>
141</dl></dd>
142<dt><span class="section"><a href="x32.html">3.3. x32</a></span></dt>
143<dd><dl>
144<dt><span class="section"><a href="support.html">3.3.1. Support</a></span></dt>
145<dt><span class="section"><a href="future-development-and-limitations.html">3.3.2. Future Development and Limitations</a></span></dt>
146<dt><span class="section"><a href="using-x32-right-now.html">3.3.3. Using x32 Right Now</a></span></dt>
147</dl></dd>
148<dt><span class="section"><a href="licenses.html">3.4. Licenses</a></span></dt>
149<dd><dl>
150<dt><span class="section"><a href="usingpoky-configuring-LIC_FILES_CHKSUM.html">3.4.1. Tracking License Changes</a></span></dt>
151<dt><span class="section"><a href="enabling-commercially-licensed-recipes.html">3.4.2. Enabling Commercially Licensed Recipes</a></span></dt>
152</dl></dd>
153</dl></dd>
154<dt><span class="chapter"><a href="migration.html">4. Migrating to a Newer Yocto Project Release</a></span></dt>
155<dd><dl>
156<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>
157<dd><dl>
158<dt><span class="section"><a href="1.3-local-configuration.html">4.1.1. Local Configuration</a></span></dt>
159<dt><span class="section"><a href="1.3-recipes.html">4.1.2. Recipes</a></span></dt>
160</dl></dd>
161</dl></dd>
162<dt><span class="chapter"><a href="ref-structure.html">5. Source Directory Structure</a></span></dt>
163<dd><dl>
164<dt><span class="section"><a href="structure-core.html">5.1. Top level core components</a></span></dt>
165<dd><dl>
166<dt><span class="section"><a href="structure-core-bitbake.html">5.1.1. <code class="filename">bitbake/</code></a></span></dt>
167<dt><span class="section"><a href="structure-core-build.html">5.1.2. <code class="filename">build/</code></a></span></dt>
168<dt><span class="section"><a href="handbook.html">5.1.3. <code class="filename">documentation</code></a></span></dt>
169<dt><span class="section"><a href="structure-core-meta.html">5.1.4. <code class="filename">meta/</code></a></span></dt>
170<dt><span class="section"><a href="structure-core-meta-yocto.html">5.1.5. <code class="filename">meta-yocto/</code></a></span></dt>
171<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>
172<dt><span class="section"><a href="structure-meta-hob.html">5.1.7. <code class="filename">meta-hob/</code></a></span></dt>
173<dt><span class="section"><a href="structure-meta-skeleton.html">5.1.8. <code class="filename">meta-skeleton/</code></a></span></dt>
174<dt><span class="section"><a href="structure-core-scripts.html">5.1.9. <code class="filename">scripts/</code></a></span></dt>
175<dt><span class="section"><a href="structure-core-script.html">5.1.10. <code class="filename">oe-init-build-env</code></a></span></dt>
176<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>
177</dl></dd>
178<dt><span class="section"><a href="structure-build.html">5.2. The Build Directory - <code class="filename">build/</code></a></span></dt>
179<dd><dl>
180<dt><span class="section"><a href="structure-build-pseudodone.html">5.2.1. <code class="filename">build/pseudodone</code></a></span></dt>
181<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>
182<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>
183<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>
184<dt><span class="section"><a href="structure-build-downloads.html">5.2.5. <code class="filename">build/downloads/</code></a></span></dt>
185<dt><span class="section"><a href="structure-build-sstate-cache.html">5.2.6. <code class="filename">build/sstate-cache/</code></a></span></dt>
186<dt><span class="section"><a href="structure-build-tmp.html">5.2.7. <code class="filename">build/tmp/</code></a></span></dt>
187<dt><span class="section"><a href="structure-build-tmp-buildstats.html">5.2.8. <code class="filename">build/tmp/buildstats/</code></a></span></dt>
188<dt><span class="section"><a href="structure-build-tmp-cache.html">5.2.9. <code class="filename">build/tmp/cache/</code></a></span></dt>
189<dt><span class="section"><a href="structure-build-tmp-deploy.html">5.2.10. <code class="filename">build/tmp/deploy/</code></a></span></dt>
190<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>
191<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>
192<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>
193<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>
194<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>
195<dt><span class="section"><a href="structure-build-tmp-sysroots.html">5.2.16. <code class="filename">build/tmp/sysroots/</code></a></span></dt>
196<dt><span class="section"><a href="structure-build-tmp-stamps.html">5.2.17. <code class="filename">build/tmp/stamps/</code></a></span></dt>
197<dt><span class="section"><a href="structure-build-tmp-log.html">5.2.18. <code class="filename">build/tmp/log/</code></a></span></dt>
198<dt><span class="section"><a href="structure-build-tmp-pkgdata.html">5.2.19. <code class="filename">build/tmp/pkgdata/</code></a></span></dt>
199<dt><span class="section"><a href="structure-build-tmp-work.html">5.2.20. <code class="filename">build/tmp/work/</code></a></span></dt>
200</dl></dd>
201<dt><span class="section"><a href="structure-meta.html">5.3. The Metadata - <code class="filename">meta/</code></a></span></dt>
202<dd><dl>
203<dt><span class="section"><a href="structure-meta-classes.html">5.3.1. <code class="filename">meta/classes/</code></a></span></dt>
204<dt><span class="section"><a href="structure-meta-conf.html">5.3.2. <code class="filename">meta/conf/</code></a></span></dt>
205<dt><span class="section"><a href="structure-meta-conf-machine.html">5.3.3. <code class="filename">meta/conf/machine/</code></a></span></dt>
206<dt><span class="section"><a href="structure-meta-conf-distro.html">5.3.4. <code class="filename">meta/conf/distro/</code></a></span></dt>
207<dt><span class="section"><a href="structure-meta-recipes-bsp.html">5.3.5. <code class="filename">meta/recipes-bsp/</code></a></span></dt>
208<dt><span class="section"><a href="structure-meta-recipes-connectivity.html">5.3.6. <code class="filename">meta/recipes-connectivity/</code></a></span></dt>
209<dt><span class="section"><a href="structure-meta-recipes-core.html">5.3.7. <code class="filename">meta/recipes-core/</code></a></span></dt>
210<dt><span class="section"><a href="structure-meta-recipes-devtools.html">5.3.8. <code class="filename">meta/recipes-devtools/</code></a></span></dt>
211<dt><span class="section"><a href="structure-meta-recipes-extended.html">5.3.9. <code class="filename">meta/recipes-extended/</code></a></span></dt>
212<dt><span class="section"><a href="structure-meta-recipes-gnome.html">5.3.10. <code class="filename">meta/recipes-gnome/</code></a></span></dt>
213<dt><span class="section"><a href="structure-meta-recipes-graphics.html">5.3.11. <code class="filename">meta/recipes-graphics/</code></a></span></dt>
214<dt><span class="section"><a href="structure-meta-recipes-kernel.html">5.3.12. <code class="filename">meta/recipes-kernel/</code></a></span></dt>
215<dt><span class="section"><a href="structure-meta-recipes-multimedia.html">5.3.13. <code class="filename">meta/recipes-multimedia/</code></a></span></dt>
216<dt><span class="section"><a href="structure-meta-recipes-qt.html">5.3.14. <code class="filename">meta/recipes-qt/</code></a></span></dt>
217<dt><span class="section"><a href="structure-meta-recipes-rt.html">5.3.15. <code class="filename">meta/recipes-rt/</code></a></span></dt>
218<dt><span class="section"><a href="structure-meta-recipes-sato.html">5.3.16. <code class="filename">meta/recipes-sato/</code></a></span></dt>
219<dt><span class="section"><a href="structure-meta-recipes-support.html">5.3.17. <code class="filename">meta/recipes-support/</code></a></span></dt>
220<dt><span class="section"><a href="structure-meta-site.html">5.3.18. <code class="filename">meta/site/</code></a></span></dt>
221<dt><span class="section"><a href="structure-meta-recipes-txt.html">5.3.19. <code class="filename">meta/recipes.txt</code></a></span></dt>
222</dl></dd>
223</dl></dd>
224<dt><span class="chapter"><a href="ref-bitbake.html">6. BitBake</a></span></dt>
225<dd><dl>
226<dt><span class="section"><a href="ref-bitbake-parsing.html">6.1. Parsing</a></span></dt>
227<dt><span class="section"><a href="ref-bitbake-providers.html">6.2. Preferences and Providers</a></span></dt>
228<dt><span class="section"><a href="ref-bitbake-dependencies.html">6.3. Dependencies</a></span></dt>
229<dt><span class="section"><a href="ref-bitbake-tasklist.html">6.4. The Task List</a></span></dt>
230<dt><span class="section"><a href="ref-bitbake-runtask.html">6.5. Running a Task</a></span></dt>
231<dt><span class="section"><a href="ref-bitbake-commandline.html">6.6. BitBake Command Line</a></span></dt>
232<dt><span class="section"><a href="ref-bitbake-fetchers.html">6.7. Fetchers</a></span></dt>
233</dl></dd>
234<dt><span class="chapter"><a href="ref-classes.html">7. Classes</a></span></dt>
235<dd><dl>
236<dt><span class="section"><a href="ref-classes-base.html">7.1. The base class - <code class="filename">base.bbclass</code></a></span></dt>
237<dt><span class="section"><a href="ref-classes-autotools.html">7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt>
238<dt><span class="section"><a href="ref-classes-update-alternatives.html">7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt>
239<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>
240<dt><span class="section"><a href="ref-classes-binconfig.html">7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt>
241<dt><span class="section"><a href="ref-classes-debian.html">7.6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt>
242<dt><span class="section"><a href="ref-classes-pkgconfig.html">7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt>
243<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>
244<dt><span class="section"><a href="ref-classes-perl.html">7.9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt>
245<dt><span class="section"><a href="ref-classes-distutils.html">7.10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt>
246<dt><span class="section"><a href="ref-classes-devshell.html">7.11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt>
247<dt><span class="section"><a href="ref-classes-packagegroup.html">7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></a></span></dt>
248<dt><span class="section"><a href="ref-classes-package.html">7.13. Packaging - <code class="filename">package*.bbclass</code></a></span></dt>
249<dt><span class="section"><a href="ref-classes-kernel.html">7.14. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt>
250<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>
251<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>
252<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>
253<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>
254<dt><span class="section"><a href="ref-classes-useradd.html">7.19. Adding Users - <code class="filename">useradd.bbclass</code></a></span></dt>
255<dt><span class="section"><a href="ref-classes-externalsrc.html">7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></a></span></dt>
256<dt><span class="section"><a href="ref-classes-others.html">7.21. Other Classes</a></span></dt>
257</dl></dd>
258<dt><span class="chapter"><a href="ref-images.html">8. Images</a></span></dt>
259<dt><span class="chapter"><a href="ref-features.html">9. Reference: Features</a></span></dt>
260<dd><dl>
261<dt><span class="section"><a href="ref-features-distro.html">9.1. Distro</a></span></dt>
262<dt><span class="section"><a href="ref-features-machine.html">9.2. Machine</a></span></dt>
263<dt><span class="section"><a href="ref-features-image.html">9.3. Images</a></span></dt>
264<dt><span class="section"><a href="ref-features-backfill.html">9.4. Feature Backfilling</a></span></dt>
265</dl></dd>
266<dt><span class="chapter"><a href="ref-variables-glos.html">10. Variables Glossary</a></span></dt>
267<dd><dl><dt><span class="glossary"><a href="ref-variables-glos.html#ref-variables-glossary">Glossary</a></span></dt></dl></dd>
268<dt><span class="chapter"><a href="ref-varlocality.html">11. Variable Context</a></span></dt>
269<dd><dl>
270<dt><span class="section"><a href="ref-varlocality-configuration.html">11.1. Configuration</a></span></dt>
271<dd><dl>
272<dt><span class="section"><a href="ref-varlocality-config-distro.html">11.1.1. Distribution (Distro)</a></span></dt>
273<dt><span class="section"><a href="ref-varlocality-config-machine.html">11.1.2. Machine</a></span></dt>
274<dt><span class="section"><a href="ref-varlocality-config-local.html">11.1.3. Local</a></span></dt>
275</dl></dd>
276<dt><span class="section"><a href="ref-varlocality-recipes.html">11.2. Recipes</a></span></dt>
277<dd><dl>
278<dt><span class="section"><a href="ref-varlocality-recipe-required.html">11.2.1. Required</a></span></dt>
279<dt><span class="section"><a href="ref-varlocality-recipe-dependencies.html">11.2.2. Dependencies</a></span></dt>
280<dt><span class="section"><a href="ref-varlocality-recipe-paths.html">11.2.3. Paths</a></span></dt>
281<dt><span class="section"><a href="ref-varlocality-recipe-build.html">11.2.4. Extra Build Information</a></span></dt>
282</dl></dd>
283</dl></dd>
284<dt><span class="chapter"><a href="faq.html">12. FAQ</a></span></dt>
285<dt><span class="chapter"><a href="resources.html">13. Contributing to the Yocto Project</a></span></dt>
286<dd><dl>
287<dt><span class="section"><a href="resources-intro.html">13.1. Introduction</a></span></dt>
288<dt><span class="section"><a href="resources-bugtracker.html">13.2. Tracking Bugs</a></span></dt>
289<dt><span class="section"><a href="resources-mailinglist.html">13.3. Mailing lists</a></span></dt>
290<dt><span class="section"><a href="resources-irc.html">13.4. Internet Relay Chat (IRC)</a></span></dt>
291<dt><span class="section"><a href="resources-links.html">13.5. Links</a></span></dt>
292<dt><span class="section"><a href="resources-contributions.html">13.6. Contributions</a></span></dt>
293</dl></dd>
294</dl>
295</div>
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326</div></body>
327</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 @@
1<?xml version="1.0" encoding="utf-8" standalone="no"?>
2<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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>1.5. Development Checkouts</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="intro.html" title="Chapter 1. Introduction">
9<link rel="prev" href="intro-getit.html" title="1.4. Obtaining the Yocto Project">
10<link rel="next" href="usingpoky.html" title="Chapter 2. Using the Yocto Project">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.5. Development Checkouts">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="intro-getit-dev"></a>1.5. Development Checkouts</h2></div></div></div>
15<p>
16 Development using the Yocto Project requires a local
17 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
18 You can set up the source directory by downloading a Yocto Project release tarball and unpacking it,
19 or by cloning a copy of the upstream
20 <a class="link" href="../dev-manual/poky.html" target="_self">Poky</a> Git repository.
21 For information on both these methods, see the
22 "<a class="link" href="../dev-manual/getting-setup.html" target="_self">Getting Setup</a>"
23 section in the Yocto Project Development Manual.
24 </p>
25</div></body>
26</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>1.4. Obtaining the Yocto Project</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="intro.html" title="Chapter 1. Introduction">
9<link rel="prev" href="centos-packages.html" title="1.3.2.4. CentOS Packages">
10<link rel="next" href="intro-getit-dev.html" title="1.5. Development Checkouts">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.4. Obtaining the Yocto Project">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="intro-getit"></a>1.4. Obtaining the Yocto Project</h2></div></div></div>
15<p>
16 The Yocto Project development team makes the Yocto Project available through a number
17 of methods:
18 </p>
19<div class="itemizedlist"><ul class="itemizedlist" type="disc">
20<li class="listitem"><p><span class="emphasis"><em>Releases:</em></span> Stable, tested releases are available through
21 <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/" target="_self">http://downloads.yoctoproject.org/releases/yocto/</a>.</p></li>
22<li class="listitem"><p><span class="emphasis"><em>Nightly Builds:</em></span> These releases are available at
23 <a class="ulink" href="http://autobuilder.yoctoproject.org/nightly" target="_self">http://autobuilder.yoctoproject.org/nightly</a>.
24 These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and
25 experimental builds.</p></li>
26<li class="listitem"><p><span class="emphasis"><em>Yocto Project Website:</em></span> You can find releases
27 of the Yocto Project and supported BSPs at the
28 <a class="ulink" href="http://www.yoctoproject.org" target="_self">Yocto Project website</a>.
29 Along with these downloads, you can find lots of other information at this site.
30 </p></li>
31</ul></div>
32<p>
33 </p>
34</div></body>
35</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>1.2. Documentation Overview</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="intro.html" title="Chapter 1. Introduction">
9<link rel="prev" href="intro-welcome.html" title="1.1. Introduction">
10<link rel="next" href="intro-requirements.html" title="1.3. System Requirements">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.2. Documentation Overview">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="intro-manualoverview"></a>1.2. Documentation Overview</h2></div></div></div>
15<p>
16 This reference manual consists of the following:
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<li class="listitem"><p><span class="emphasis"><em>
20 <a class="link" href="usingpoky.html" title="Chapter 2. Using the Yocto Project">Using the Yocto Project</a>:</em></span> This chapter
21 provides an overview of the components that make up the Yocto Project
22 followed by information about debugging images created in the Yocto Project.
23 </p></li>
24<li class="listitem"><p><span class="emphasis"><em>
25 <a class="link" href="technical-details.html" title="Chapter 3. Technical Details">Technical Details</a>:</em></span>
26 This chapter describes fundamental Yocto Project components as well as an explanation
27 behind how the Yocto Project uses shared state (sstate) cache to speed build time.
28 </p></li>
29<li class="listitem"><p><span class="emphasis"><em>
30 <a class="link" href="ref-structure.html" title="Chapter 5. Source Directory Structure">Directory Structure</a>:</em></span>
31 This chapter describes the
32 <a class="link" href="../dev-manual/source-directory.html" target="_self">source directory</a> created
33 either by unpacking a released Yocto Project tarball on your host development system,
34 or by cloning the upstream
35 <a class="link" href="../dev-manual/poky.html" target="_self">Poky</a> Git repository.
36 </p></li>
37<li class="listitem"><p><span class="emphasis"><em>
38 <a class="link" href="ref-bitbake.html" title="Chapter 6. BitBake">BitBake</a>:</em></span>
39 This chapter provides an overview of the BitBake tool and its role within
40 the Yocto Project.</p></li>
41<li class="listitem"><p><span class="emphasis"><em>
42 <a class="link" href="ref-classes.html" title="Chapter 7. Classes">Classes</a>:</em></span>
43 This chapter describes the classes used in the Yocto Project.</p></li>
44<li class="listitem"><p><span class="emphasis"><em>
45 <a class="link" href="ref-images.html" title="Chapter 8. Images">Images</a>:</em></span>
46 This chapter describes the standard images that the Yocto Project supports.
47 </p></li>
48<li class="listitem"><p><span class="emphasis"><em>
49 <a class="link" href="ref-features.html" title="Chapter 9. Reference: Features">Features</a>:</em></span>
50 This chapter describes mechanisms for creating distribution, machine, and image
51 features during the build process using the OpenEmbedded build system.</p></li>
52<li class="listitem"><p><span class="emphasis"><em>
53 <a class="link" href="ref-variables-glos.html" title="Chapter 10. Variables Glossary">Variables Glossary</a>:</em></span>
54 This chapter presents most variables used by the OpenEmbedded build system, which
55 using BitBake.
56 Entries describe the function of the variable and how to apply them.
57 </p></li>
58<li class="listitem"><p><span class="emphasis"><em>
59 <a class="link" href="ref-varlocality.html" title="Chapter 11. Variable Context">Variable Context</a>:</em></span>
60 This chapter provides variable locality or context.</p></li>
61<li class="listitem"><p><span class="emphasis"><em>
62 <a class="link" href="faq.html" title="Chapter 12. FAQ">FAQ</a>:</em></span>
63 This chapter provides answers for commonly asked questions in the Yocto Project
64 development environment.</p></li>
65<li class="listitem"><p><span class="emphasis"><em>
66 <a class="link" href="resources.html" title="Chapter 13. Contributing to the Yocto Project">Contributing to the Yocto Project</a>:</em></span>
67 This chapter provides guidance on how you can contribute back to the Yocto
68 Project.</p></li>
69</ul></div>
70<p>
71 </p>
72</div></body>
73</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>1.3. System Requirements</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="intro.html" title="Chapter 1. Introduction">
9<link rel="prev" href="intro-manualoverview.html" title="1.2. Documentation Overview">
10<link rel="next" href="detailed-supported-distros.html" title="1.3.1. Supported Linux Distributions">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3. System Requirements">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="intro-requirements"></a>1.3. System Requirements</h2></div></div></div>
15<p>
16 For general Yocto Project system requirements, see the
17 "<a class="link" href="../yocto-project-qs/yp-resources.html" target="_self">What You Need and How You Get It</a>" section
18 in the Yocto Project Quick Start.
19 The remainder of this section provides details on system requirements
20 not covered in the Yocto Project Quick Start.
21 </p>
22</div></body>
23</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>1.1. Introduction</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="intro.html" title="Chapter 1. Introduction">
9<link rel="prev" href="intro.html" title="Chapter 1. Introduction">
10<link rel="next" href="intro-manualoverview.html" title="1.2. Documentation Overview">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.1. Introduction">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="intro-welcome"></a>1.1. Introduction</h2></div></div></div>
15<p>
16 This manual provides reference information for the current release of the Yocto Project.
17 The Yocto Project is an open-source collaboration project focused on embedded Linux
18 developers.
19 Amongst other things, the Yocto Project uses the OpenEmbedded build system, which
20 is based on the Poky project, to construct complete Linux images.
21 You can find complete introductory and getting started information on the Yocto Project
22 by reading the
23 <a class="link" href="../yocto-project-qs/index.html" target="_self">Yocto Project Quick Start</a>.
24 For task-based information using the Yocto Project, see the
25 <a class="link" href="../dev-manual/index.html" target="_self">Yocto Project Development Manual</a>.
26 You can also find lots of information on the Yocto Project on the
27 <a class="ulink" href="http://www.yoctoproject.org" target="_self">Yocto Project website</a>.
28 </p>
29</div></body>
30</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 1. Introduction</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="index.html" title="The Yocto Project Reference Manual">
10<link rel="next" href="intro-welcome.html" title="1.1. Introduction">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 1. Introduction">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="intro"></a>Chapter 1. Introduction</h2></div></div></div>
15<div class="toc">
16<p><b>Table of Contents</b></p>
17<dl>
18<dt><span class="section"><a href="intro-welcome.html">1.1. Introduction</a></span></dt>
19<dt><span class="section"><a href="intro-manualoverview.html">1.2. Documentation Overview</a></span></dt>
20<dt><span class="section"><a href="intro-requirements.html">1.3. System Requirements</a></span></dt>
21<dd><dl>
22<dt><span class="section"><a href="detailed-supported-distros.html">1.3.1. Supported Linux Distributions</a></span></dt>
23<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>
24</dl></dd>
25<dt><span class="section"><a href="intro-getit.html">1.4. Obtaining the Yocto Project</a></span></dt>
26<dt><span class="section"><a href="intro-getit-dev.html">1.5. Development Checkouts</a></span></dt>
27</dl>
28</div>
29</div></body>
30</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.2.4.2. Invalidating Shared State</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="tips-and-tricks.html" title="3.2.4. Tips and Tricks">
9<link rel="prev" href="debugging.html" title="3.2.4.1. Debugging">
10<link rel="next" href="x32.html" title="3.3. x32">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.4.2. Invalidating Shared State">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="invalidating-shared-state"></a>3.2.4.2. Invalidating Shared State</h4></div></div></div>
15<p>
16 The shared state code uses checksums and shared state
17 cache to avoid unnecessarily rebuilding tasks.
18 As with all schemes, this one has some drawbacks.
19 It is possible that you could make implicit changes that are not factored
20 into the checksum calculation, but do affect a task's output.
21 A good example is perhaps when a tool changes its output.
22 Let's say that the output of <code class="filename">rpmdeps</code> needed to change.
23 The result of the change should be that all the "package", "package_write_rpm",
24 and "package_deploy-rpm" shared state cache items would become invalid.
25 But, because this is a change that is external to the code and therefore implicit,
26 the associated shared state cache items do not become invalidated.
27 In this case, the build process would use the cached items rather than running the
28 task again.
29 Obviously, these types of implicit changes can cause problems.
30 </p>
31<p>
32 To avoid these problems during the build, you need to understand the effects of any
33 change you make.
34 Note that any changes you make directly to a function automatically are factored into
35 the checksum calculation and thus, will invalidate the associated area of sstate cache.
36 You need to be aware of any implicit changes that are not obvious changes to the
37 code and could affect the output of a given task.
38 Once you are aware of such a change, you can take steps to invalidate the cache
39 and force the task to run.
40 The step to take is as simple as changing a function's comments in the source code.
41 For example, to invalidate package shared state files, change the comment statements
42 of <code class="filename">do_package</code> or the comments of one of the functions it calls.
43 The change is purely cosmetic, but it causes the checksum to be recalculated and
44 forces the task to be run again.
45 </p>
46<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
47<h3 class="title">Note</h3>
48 For an example of a commit that makes a cosmetic change to invalidate
49 a shared state, see this
50 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54" target="_self">commit</a>.
51 </div>
52</div></body>
53</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.4.2.1. License Flag Matching</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="enabling-commercially-licensed-recipes.html" title="3.4.2. Enabling Commercially Licensed Recipes">
9<link rel="prev" href="enabling-commercially-licensed-recipes.html" title="3.4.2. Enabling Commercially Licensed Recipes">
10<link rel="next" href="other-variables-related-to-commercial-licenses.html" title="3.4.2.2. Other Variables Related to Commercial Licenses">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4.2.1. License Flag Matching">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="license-flag-matching"></a>3.4.2.1. License Flag Matching</h4></div></div></div>
15<p>
16 The definition of 'matching' in reference to a
17 recipe's <code class="filename">LICENSE_FLAGS</code> setting is simple.
18 However, some things exist that you should know about in order to
19 correctly and effectively use it.
20 </p>
21<p>
22 Before a flag
23 defined by a particular recipe is tested against the
24 contents of the <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, the
25 string <code class="filename">_${PN}</code> (with
26 <a class="link" href="ref-variables-glos.html#var-PN" title="PN"><code class="filename">PN</code></a> expanded of course) is
27 appended to the flag, thus automatically making each
28 <code class="filename">LICENSE_FLAGS</code> value recipe-specific.
29 That string is
30 then matched against the whitelist.
31 So if you specify <code class="filename">LICENSE_FLAGS = "commercial"</code> in recipe
32 "foo" for example, the string <code class="filename">"commercial_foo"</code>
33 would normally be what is specified in the whitelist in order for it to
34 match.
35 </p>
36<p>
37 You can broaden the match by
38 putting any "_"-separated beginning subset of a
39 <code class="filename">LICENSE_FLAGS</code> flag in the whitelist, which will also
40 match.
41 For example, simply specifying "commercial" in
42 the whitelist would match any expanded <code class="filename">LICENSE_FLAGS</code>
43 definition starting with "commercial" such as
44 "commercial_foo" and "commercial_bar", which are the
45 strings that would be automatically generated for
46 hypothetical "foo" and "bar" recipes assuming those
47 recipes had simply specified the following:
48 </p>
49<pre class="literallayout">
50 LICENSE_FLAGS = "commercial"
51 </pre>
52<p>
53 </p>
54<p>
55 Broadening the match allows for a range of specificity for the items
56 in the whitelist, from more general to perfectly
57 specific.
58 So you have the choice of exhaustively
59 enumerating each license flag in the whitelist to
60 allow only those specific recipes into the image, or
61 of using a more general string to pick up anything
62 matching just the first component or components of the specified
63 string.
64 </p>
65<p>
66 This scheme works even if the flag already
67 has <code class="filename">_${PN}</code> appended - the extra <code class="filename">_${PN}</code> is
68 redundant, but does not affect the outcome.
69 For example, a license flag of "commercial_1.2_foo" would
70 turn into "commercial_1.2_foo_foo" and would match
71 both the general "commercial" and the specific
72 "commercial_1.2_foo", as expected.
73 The flag would also match
74 "commercial_1.2_foo_foo" and "commercial_1.2", which
75 does not make much sense regarding use in the whitelist.
76 </p>
77<p>
78 For a versioned string, you could instead specify
79 "commercial_foo_1.2", which would turn into
80 "commercial_foo_1.2_foo".
81 And, as expected, this flag allows
82 you to pick up this package along with
83 anything else "commercial" when you specify "commercial"
84 in the whitelist.
85 Or, the flag allows you to pick up this package along with anything "commercial_foo"
86 regardless of version when you use "commercial_foo" in the whitelist.
87 Finally, you can be completely specific about the package and version and specify
88 "commercial_foo_1.2" package and version.
89 </p>
90</div></body>
91</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.4. Licenses</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="technical-details.html" title="Chapter 3. Technical Details">
9<link rel="prev" href="using-x32-right-now.html" title="3.3.3. Using x32 Right Now">
10<link rel="next" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.4.1. Tracking License Changes">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4. Licenses">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="licenses"></a>3.4. Licenses</h2></div></div></div>
15<p>
16 This section describes the mechanism by which the OpenEmbedded build system
17 tracks changes to licensing text.
18 The section also describes how to enable commercially licensed recipes,
19 which by default are disabled.
20 </p>
21<p>
22 For information that can help you maintain compliance with various open
23 source licensing during the lifecycle of the product, see the
24 "<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
25 in the Yocto Project Development Manual.
26 </p>
27</div></body>
28</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.3.7.2. Logging With Bash</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="recipe-logging-mechanisms.html" title="2.3.7. Recipe Logging Mechanisms">
9<link rel="prev" href="logging-with-python.html" title="2.3.7.1. Logging With Python">
10<link rel="next" href="usingpoky-debugging-others.html" title="2.3.8. Other Tips">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.7.2. Logging With Bash">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="logging-with-bash"></a>2.3.7.2. Logging With Bash</h4></div></div></div>
15<p>
16 When creating recipes using Bash and inserting code that handles build
17 logs you have the same goals - informative with minimal console output.
18 The syntax you use for recipes written in Bash is similar to that of
19 recipes written in Python described in the previous section.
20 </p>
21<p>
22 Following is an example written in Bash.
23 The code logs the progress of the <code class="filename">do_my_function</code> function.
24 </p>
25<pre class="literallayout">
26 do_my_function() {
27 bbdebug 2 "Running do_my_function"
28 if [ exceptional_condition ]; then
29 bbnote "Hit exceptional_condition"
30 fi
31 bbdebug 2 "Got to point xyz"
32 if [ warning_trigger ]; then
33 bbwarn "Detected warning_trigger, this might cause a problem later."
34 fi
35 if [ recoverable_error ]; then
36 bberror "Hit recoverable_error, correcting"
37 fi
38 if [ fatal_error ]; then
39 bbfatal "fatal_error detected"
40 fi
41 bbdebug 2 "Completed do_my_function"
42 }
43 </pre>
44<p>
45 </p>
46</div></body>
47</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.3.7.1. Logging With Python</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="recipe-logging-mechanisms.html" title="2.3.7. Recipe Logging Mechanisms">
9<link rel="prev" href="recipe-logging-mechanisms.html" title="2.3.7. Recipe Logging Mechanisms">
10<link rel="next" href="logging-with-bash.html" title="2.3.7.2. Logging With Bash">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.7.1. Logging With Python">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="logging-with-python"></a>2.3.7.1. Logging With Python</h4></div></div></div>
15<p>
16 When creating recipes using Python and inserting code that handles build logs
17 keep in mind the goal is to have informative logs while keeping the console as
18 "silent" as possible.
19 Also, if you want status messages in the log use the "debug" loglevel.
20 </p>
21<p>
22 Following is an example written in Python.
23 The code handles logging for a function that determines the number of tasks
24 needed to be run:
25 </p>
26<pre class="literallayout">
27 python do_listtasks() {
28 bb.debug(2, "Starting to figure out the task list")
29 if noteworthy_condition:
30 bb.note("There are 47 tasks to run")
31 bb.debug(2, "Got to point xyz")
32 if warning_trigger:
33 bb.warn("Detected warning_trigger, this might be a problem later.")
34 if recoverable_error:
35 bb.error("Hit recoverable_error, you really need to fix this!")
36 if fatal_error:
37 bb.fatal("fatal_error detected, unable to print the task list")
38 bb.plain("The tasks present are abc")
39 bb.debug(2, "Finished figuring out the tasklist")
40 }
41 </pre>
42<p>
43 </p>
44</div></body>
45</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.4. Maintaining Build Output Quality</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky.html" title="Chapter 2. Using the Yocto Project">
9<link rel="prev" href="usingpoky-debugging-others.html" title="2.3.8. Other Tips">
10<link rel="next" href="enabling-and-disabling-build-history.html" title="2.4.1. Enabling and Disabling Build History">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4. Maintaining Build Output Quality">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="maintaining-build-output-quality"></a>2.4. Maintaining Build Output Quality</h2></div></div></div>
15<p>
16 A build's quality can be influenced by many things.
17 For example, if you upgrade a recipe to use a new version of an upstream software
18 package or you experiment with some new configuration options, subtle changes
19 can occur that you might not detect until later.
20 Consider the case where your recipe is using a newer version of an upstream package.
21 In this case, a new version of a piece of software might introduce an optional
22 dependency on another library, which is auto-detected.
23 If that library has already been built when the software is building,
24 then the software will link to the built library and that library will be pulled
25 into your image along with the new software even if you did not want the
26 library.
27 </p>
28<p>
29 The <code class="filename">buildhistory</code> class exists to help you maintain
30 the quality of your build output.
31 You can use the class to highlight unexpected and possibly unwanted
32 changes in the build output.
33 When you enable build history it records information about the contents of
34 each package and image and then commits that information to a local Git
35 repository where you can examine the information.
36 </p>
37<p>
38 The remainder of this section describes the following:
39 </p>
40<div class="itemizedlist"><ul class="itemizedlist" type="disc">
41<li class="listitem"><p>How you can enable and disable
42 build history</p></li>
43<li class="listitem"><p>How to understand what the build history contains
44 </p></li>
45<li class="listitem"><p>How to limit the information used for build history
46 </p></li>
47<li class="listitem"><p>How to examine the build history from both a
48 command-line and web interface</p></li>
49</ul></div>
50<p>
51 </p>
52</div></body>
53</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>4.1.1.2. bblayers.conf</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="1.3-local-configuration.html" title="4.1.1. Local Configuration">
9<link rel="prev" href="migration-1.3-sstate-mirrors.html" title="4.1.1.1. SSTATE_MIRRORS">
10<link rel="next" href="1.3-recipes.html" title="4.1.2. Recipes">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.1.2. bblayers.conf">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="migration-1.3-bblayers-conf"></a>4.1.1.2. bblayers.conf</h4></div></div></div>
15<p>
16 The <code class="filename">meta-yocto</code> layer has been split into
17 two parts: <code class="filename">meta-yocto</code> and
18 <code class="filename">meta-yocto-bsp</code>, corresponding to the
19 Poky reference distro configuration and the reference
20 hardware Board Support Packages (BSPs), respectively.
21 When running BitBake or Hob for the first time after upgrading,
22 your <code class="filename">conf/bblayers.conf</code> file will be
23 updated to handle this change and you will be asked to
24 re-run/restart for the changes to take effect.
25 </p>
26</div></body>
27</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>4.1.2.5. IMAGE_FEATURES</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="1.3-recipes.html" title="4.1.2. Recipes">
9<link rel="prev" href="migration-1.3-task-recipes.html" title="4.1.2.4. Task Recipes">
10<link rel="next" href="migration-1.3-removed-recipes.html" title="4.1.2.6. Removed Recipes">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2.5. IMAGE_FEATURES">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="migration-1.3-image-features"></a>4.1.2.5. IMAGE_FEATURES</h4></div></div></div>
15<p>
16 Image recipes that previously included "apps-console-core"
17 in <a class="link" href="ref-variables-glos.html#var-IMAGE_FEATURES" title="IMAGE_FEATURES"><code class="filename">IMAGE_FEATURES</code></a>
18 should now include "splash" instead to enable the boot-up
19 splash screen.
20 Retaining "apps-console-core" will still include the splash
21 screen generates a warning.
22 The "apps-x11-core" and "apps-x11-games"
23 <code class="filename">IMAGE_FEATURES</code> features have been removed.
24 </p>
25</div></body>
26</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>4.1.2.3. nativesdk</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="1.3-recipes.html" title="4.1.2. Recipes">
9<link rel="prev" href="migration-1.3-proto=-in-src-uri.html" title="4.1.2.2. proto= in SRC_URI">
10<link rel="next" href="migration-1.3-task-recipes.html" title="4.1.2.4. Task Recipes">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2.3. nativesdk">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="migration-1.3-nativesdk"></a>4.1.2.3. nativesdk</h4></div></div></div>
15<p>
16 The suffix <code class="filename">nativesdk</code> is now implemented
17 as a prefix, which simplifies a lot of the packaging code for
18 <code class="filename">nativesdk</code> recipes.
19 All custom <code class="filename">nativesdk</code> recipes and any
20 references need to be updated to use
21 <code class="filename">nativesdk-*</code> instead of
22 <code class="filename">*-nativesdk</code>.
23 </p>
24</div></body>
25</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>4.1.2.2. proto= in SRC_URI</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="1.3-recipes.html" title="4.1.2. Recipes">
9<link rel="prev" href="migration-1.3-python-function-whitespace.html" title="4.1.2.1. Python Function Whitespace">
10<link rel="next" href="migration-1.3-nativesdk.html" title="4.1.2.3. nativesdk">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2.2. proto= in SRC_URI">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="migration-1.3-proto=-in-src-uri"></a>4.1.2.2. proto= in SRC_URI</h4></div></div></div>
15<p>
16 Any use of <code class="filename">proto=</code> in
17 <a class="link" href="ref-variables-glos.html#var-SRC_URI" title="SRC_URI"><code class="filename">SRC_URI</code></a>
18 needs to be changed to <code class="filename">protocol=</code>.
19 In particular, this applies to the following URIs:
20 </p>
21<div class="itemizedlist"><ul class="itemizedlist" type="disc">
22<li class="listitem"><p><code class="filename">svn://</code></p></li>
23<li class="listitem"><p><code class="filename">bzr://</code></p></li>
24<li class="listitem"><p><code class="filename">hg://</code></p></li>
25<li class="listitem"><p><code class="filename">osc://</code></p></li>
26</ul></div>
27<p>
28 Other URIs were already using <code class="filename">protocol=</code>.
29 This change improves consistency.
30 </p>
31</div></body>
32</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>4.1.2.1. Python Function Whitespace</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="1.3-recipes.html" title="4.1.2. Recipes">
9<link rel="prev" href="1.3-recipes.html" title="4.1.2. Recipes">
10<link rel="next" href="migration-1.3-proto=-in-src-uri.html" title="4.1.2.2. proto= in SRC_URI">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2.1. Python Function Whitespace">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="migration-1.3-python-function-whitespace"></a>4.1.2.1. Python Function Whitespace</h4></div></div></div>
15<p>
16 All Python functions must now use four spaces for indentation.
17 Previously, an inconsistent mix of spaces and tabs existed,
18 which made extending these functions using
19 <code class="filename">_append</code> or <code class="filename">_prepend</code>
20 complicated given that Python treats whitespace as
21 syntactically significant.
22 If you are defining or extending any Python functions (e.g.
23 <code class="filename">populate_packages</code>, <code class="filename">do_unpack</code>,
24 <code class="filename">do_patch</code> and so forth) in custom recipes
25 or classes, you need to ensure you are using consistent
26 four-space indentation.
27 </p>
28</div></body>
29</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>4.1.2.6. Removed Recipes</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="1.3-recipes.html" title="4.1.2. Recipes">
9<link rel="prev" href="migration-1.3-image-features.html" title="4.1.2.5. IMAGE_FEATURES">
10<link rel="next" href="ref-structure.html" title="Chapter 5. Source Directory Structure">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2.6. Removed Recipes">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="migration-1.3-removed-recipes"></a>4.1.2.6. Removed Recipes</h4></div></div></div>
15<p>
16 The following recipes have been removed.
17 For most of them, it is unlikely that you would have any
18 references to them in your own metadata.
19 However, you should check your metadata against this list to be sure:
20 </p>
21<div class="itemizedlist"><ul class="itemizedlist" type="disc">
22<li class="listitem"><p><span class="emphasis"><em><code class="filename">libx11-trim</code></em></span>:
23 Replaced by <code class="filename">libx11</code>, which has a negligible
24 size difference with modern Xorg.</p></li>
25<li class="listitem"><p><span class="emphasis"><em><code class="filename">xserver-xorg-lite</code></em></span>:
26 Use <code class="filename">xserver-xorg</code>, which has a negligible
27 size difference when DRI and GLX modules are not installed.</p></li>
28<li class="listitem"><p><span class="emphasis"><em><code class="filename">xserver-kdrive</code></em></span>:
29 Effectively unmaintained for many years.</p></li>
30<li class="listitem"><p><span class="emphasis"><em><code class="filename">mesa-xlib</code></em></span>:
31 No longer serves any purpose.</p></li>
32<li class="listitem"><p><span class="emphasis"><em><code class="filename">galago</code></em></span>:
33 Replaced by telepathy.</p></li>
34<li class="listitem"><p><span class="emphasis"><em><code class="filename">gail</code></em></span>:
35 Functionality was integrated into GTK+ 2.13.</p></li>
36<li class="listitem"><p><span class="emphasis"><em><code class="filename">eggdbus</code></em></span>:
37 No longer needed.</p></li>
38<li class="listitem"><p><span class="emphasis"><em><code class="filename">gcc-*-intermediate</code></em></span>:
39 The build has been restructured to avoid the need for
40 this step.</p></li>
41<li class="listitem"><p><span class="emphasis"><em><code class="filename">libgsmd</code></em></span>:
42 Unmaintained for many years.
43 Functionality now provided by
44 <code class="filename">ofono</code> instead.</p></li>
45<li class="listitem"><p><span class="emphasis"><em>contacts, dates, tasks, eds-tools</em></span>:
46 Largely unmaintained PIM application suite.
47 It has been moved to <code class="filename">meta-gnome</code>
48 in <code class="filename">meta-openembedded</code>.</p></li>
49</ul></div>
50<p>
51 In addition to the previously listed changes, the
52 <code class="filename">meta-demoapps</code> directory has also been removed
53 because the recipes in it were not being maintained and many
54 had become obsolete or broken.
55 Additionally, these recipes were not parsed in the default configuration.
56 Many of these recipes are already provided in an updated and
57 maintained form within OpenEmbedded community layers such as
58 <code class="filename">meta-oe</code> and <code class="filename">meta-gnome</code>.
59 For the remainder, you can now find them in the
60 <code class="filename">meta-extras</code> repository, which is in the
61 Yocto Project source repositories.
62 </p>
63</div></body>
64</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>4.1.1.1. SSTATE_MIRRORS</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="1.3-local-configuration.html" title="4.1.1. Local Configuration">
9<link rel="prev" href="1.3-local-configuration.html" title="4.1.1. Local Configuration">
10<link rel="next" href="migration-1.3-bblayers-conf.html" title="4.1.1.2. bblayers.conf">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.1.1. SSTATE_MIRRORS">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="migration-1.3-sstate-mirrors"></a>4.1.1.1. SSTATE_MIRRORS</h4></div></div></div>
15<p>
16 The shared state cache (sstate-cache) as pointed to by
17 <a class="link" href="ref-variables-glos.html#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a> by default
18 now has two-character subdirectories to prevent there being an issue with too
19 many files in the same directory.
20 Also, native sstate-cache packages will go into a subdirectory named using
21 the distro ID string.
22 If you copy the newly structured sstate-cache to a mirror location
23 (either local or remote) and then point to it in
24 <a class="link" href="ref-variables-glos.html#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a>,
25 you need to append "PATH" to the end of the mirror URL so that
26 the path used by BitBake before the mirror substitution is
27 appended to the path used to access the mirror.
28 Here is an example:
29 </p>
30<pre class="literallayout">
31 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
32 </pre>
33<p>
34 </p>
35</div></body>
36</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>4.1.2.4. Task Recipes</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="1.3-recipes.html" title="4.1.2. Recipes">
9<link rel="prev" href="migration-1.3-nativesdk.html" title="4.1.2.3. nativesdk">
10<link rel="next" href="migration-1.3-image-features.html" title="4.1.2.5. IMAGE_FEATURES">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="4.1.2.4. Task Recipes">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="migration-1.3-task-recipes"></a>4.1.2.4. Task Recipes</h4></div></div></div>
15<p>
16 "Task" recipes are now known as "Package groups" and have
17 been renamed from <code class="filename">task-*.bb</code> to
18 <code class="filename">packagegroup-*.bb</code>.
19 Existing references to the previous <code class="filename">task-*</code>
20 names should work in most cases as there is an automatic
21 upgrade path for most packages.
22 However, you should update references in your own recipes and
23 configurations as they could be removed in future releases.
24 You should also rename any custom <code class="filename">task-*</code>
25 recipes to <code class="filename">packagegroup-*</code>, and change
26 them to inherit <code class="filename">packagegroup</code> instead of
27 <code class="filename">task</code>, as well as taking the opportunity
28 to remove anything now handled by
29 <code class="filename">packagegroup.bbclass</code>, such as providing
30 <code class="filename">-dev</code> and <code class="filename">-dbg</code>
31 packages, setting
32 <a class="link" href="ref-variables-glos.html#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM"><code class="filename">LIC_FILES_CHKSUM</code></a>,
33 and so forth.
34 See the
35 "<a class="link" href="ref-classes-packagegroup.html" title="7.12. Package Groups - packagegroup.bbclass">Package Groups - packagegroup.bbclass</a>"
36 section for further details.
37 </p>
38</div></body>
39</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 4. Migrating to a Newer Yocto Project Release</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="other-variables-related-to-commercial-licenses.html" title="3.4.2.2. Other Variables Related to Commercial Licenses">
10<link rel="next" href="moving-to-the-yocto-project-1.3-release.html" title="4.1. Moving to the Yocto Project 1.3 Release">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 4. Migrating to a Newer Yocto Project Release">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="migration"></a>Chapter 4. Migrating to a Newer Yocto Project Release</h2></div></div></div>
15<div class="toc">
16<p><b>Table of Contents</b></p>
17<dl>
18<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>
19<dd><dl>
20<dt><span class="section"><a href="1.3-local-configuration.html">4.1.1. Local Configuration</a></span></dt>
21<dt><span class="section"><a href="1.3-recipes.html">4.1.2. Recipes</a></span></dt>
22</dl></dd>
23</dl>
24</div>
25<p>
26 This chapter provides information you can use to migrate work to a
27 newer Yocto Project release. You can find the same information in the
28 release notes for a given release.
29 </p>
30</div></body>
31</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>4.1. Moving to the Yocto Project 1.3 Release</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="migration.html" title="Chapter 4. Migrating to a Newer Yocto Project Release">
9<link rel="prev" href="migration.html" title="Chapter 4. Migrating to a Newer Yocto Project Release">
10<link rel="next" href="1.3-local-configuration.html" title="4.1.1. Local Configuration">
11</head>
12<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">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<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>
15<p>
16 This section provides migration information for moving to the
17 Yocto Project 1.3 Release.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>1.3.2.3. OpenSUSE Packages</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="required-packages-for-the-host-development-system.html" title="1.3.2. Required Packages for the Host Development System">
9<link rel="prev" href="fedora-packages.html" title="1.3.2.2. Fedora Packages">
10<link rel="next" href="centos-packages.html" title="1.3.2.4. CentOS Packages">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3.2.3. OpenSUSE Packages">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="opensuse-packages"></a>1.3.2.3. OpenSUSE Packages</h4></div></div></div>
15<p>
16 The following list shows the required packages by function
17 given a supported OpenSUSE Linux distribution:
18 </p>
19<div class="itemizedlist"><ul class="itemizedlist" type="disc">
20<li class="listitem">
21<p><span class="emphasis"><em>Essentials:</em></span>
22 Packages needed to build an image for a headless
23 system:
24 </p>
25<pre class="literallayout">
26 $ sudo zypper install python gcc gcc-c++ git chrpath make wget python-xml \
27 diffstat texinfo python-curses
28 </pre>
29</li>
30<li class="listitem">
31<p><span class="emphasis"><em>Graphical Extras:</em></span>
32 Packages recommended if the host system has graphics support:
33 </p>
34<pre class="literallayout">
35 $ sudo zypper install libSDL-devel xterm
36 </pre>
37</li>
38<li class="listitem">
39<p><span class="emphasis"><em>Documentation:</em></span>
40 Packages needed if you are going to build out the
41 Yocto Project documentation manuals:
42 </p>
43<pre class="literallayout">
44 $ sudo zypper install make fop xsltproc
45 </pre>
46</li>
47<li class="listitem">
48<p><span class="emphasis"><em>ADT Installer Extras:</em></span>
49 Packages needed if you are going to be using the
50 <a class="link" href="../adt-manual/using-the-adt-installer.html" target="_self">Application Development Toolkit (ADT) Installer</a>:
51 </p>
52<pre class="literallayout">
53 $ sudo zypper install autoconf automake libtool glib2-devel
54 </pre>
55</li>
56</ul></div>
57<p>
58 </p>
59</div></body>
60</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.4.2.2. Other Variables Related to Commercial Licenses</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="enabling-commercially-licensed-recipes.html" title="3.4.2. Enabling Commercially Licensed Recipes">
9<link rel="prev" href="license-flag-matching.html" title="3.4.2.1. License Flag Matching">
10<link rel="next" href="migration.html" title="Chapter 4. Migrating to a Newer Yocto Project Release">
11</head>
12<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">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="other-variables-related-to-commercial-licenses"></a>3.4.2.2. Other Variables Related to Commercial Licenses</h4></div></div></div>
15<p>
16 Other helpful variables related to commercial
17 license handling exist and are defined in the
18 <code class="filename">$HOME/poky/meta/conf/distro/include/default-distrovars.inc</code> file:
19 </p>
20<pre class="literallayout">
21 COMMERCIAL_AUDIO_PLUGINS ?= ""
22 COMMERCIAL_VIDEO_PLUGINS ?= ""
23 COMMERCIAL_QT = ""
24 </pre>
25<p>
26 If you want to enable these components, you can do so by making sure you have
27 the following statements in your <code class="filename">local.conf</code> configuration file:
28 </p>
29<pre class="literallayout">
30 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
31 gst-plugins-ugly-mpegaudioparse"
32 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
33 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
34 COMMERCIAL_QT ?= "qmmp"
35 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
36 </pre>
37<p>
38 Of course, you could also create a matching whitelist
39 for those components using the more general "commercial"
40 in the whitelist, but that would also enable all the
41 other packages with <code class="filename">LICENSE_FLAGS</code> containing
42 "commercial", which you may or may not want:
43 </p>
44<pre class="literallayout">
45 LICENSE_FLAGS_WHITELIST = "commercial"
46 </pre>
47<p>
48 </p>
49<p>
50 Specifying audio and video plug-ins as part of the
51 <code class="filename">COMMERCIAL_AUDIO_PLUGINS</code> and
52 <code class="filename">COMMERCIAL_VIDEO_PLUGINS</code> statements
53 or commercial qt components as part of
54 the <code class="filename">COMMERCIAL_QT</code> statement (along
55 with the enabling <code class="filename">LICENSE_FLAGS_WHITELIST</code>) includes the
56 plug-ins or components into built images, thus adding
57 support for media formats or components.
58 </p>
59</div></body>
60</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.2.1. Overall Architecture</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="shared-state-cache.html" title="3.2. Shared State Cache">
9<link rel="prev" href="shared-state-cache.html" title="3.2. Shared State Cache">
10<link rel="next" href="checksums.html" title="3.2.2. Checksums (Signatures)">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.1. Overall Architecture">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="overall-architecture"></a>3.2.1. Overall Architecture</h3></div></div></div>
15<p>
16 When determining what parts of the system need to be built, BitBake
17 uses a per-task basis and does not use a per-recipe basis.
18 You might wonder why using a per-task basis is preferred over a per-recipe basis.
19 To help explain, consider having the IPK packaging backend enabled and then switching to DEB.
20 In this case, <code class="filename">do_install</code> and <code class="filename">do_package</code>
21 output are still valid.
22 However, with a per-recipe approach, the build would not include the
23 <code class="filename">.deb</code> files.
24 Consequently, you would have to invalidate the whole build and rerun it.
25 Rerunning everything is not the best situation.
26 Also in this case, the core must be "taught" much about specific tasks.
27 This methodology does not scale well and does not allow users to easily add new tasks
28 in layers or as external recipes without touching the packaged-staging core.
29 </p>
30</div></body>
31</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.3.7. Recipe Logging Mechanisms</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures">
9<link rel="prev" href="usingpoky-debugging-variables.html" title="2.3.6. Variables">
10<link rel="next" href="logging-with-python.html" title="2.3.7.1. Logging With Python">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.7. Recipe Logging Mechanisms">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="recipe-logging-mechanisms"></a>2.3.7. Recipe Logging Mechanisms</h3></div></div></div>
15<p>
16 Best practices exist while writing recipes that both log build progress and
17 act on build conditions such as warnings and errors.
18 Both Python and Bash language bindings exist for the logging mechanism:
19 </p>
20<div class="itemizedlist"><ul class="itemizedlist" type="disc">
21<li class="listitem"><p><span class="emphasis"><em>Python:</em></span> For Python functions, BitBake
22 supports several loglevels: <code class="filename">bb.fatal</code>,
23 <code class="filename">bb.error</code>, <code class="filename">bb.warn</code>,
24 <code class="filename">bb.note</code>, <code class="filename">bb.plain</code>,
25 and <code class="filename">bb.debug</code>.</p></li>
26<li class="listitem"><p><span class="emphasis"><em>Bash:</em></span> For Bash functions, the same set
27 of loglevels exist and are accessed with a similar syntax:
28 <code class="filename">bbfatal</code>, <code class="filename">bberror</code>,
29 <code class="filename">bbwarn</code>, <code class="filename">bbnote</code>,
30 <code class="filename">bbplain</code>, and <code class="filename">bbdebug</code>.</p></li>
31</ul></div>
32<p>
33 </p>
34<p>
35 For guidance on how logging is handled in both Python and Bash recipes, see the
36 <code class="filename">logging.bbclass</code> file in the
37 <code class="filename">meta/classes</code> folder of the
38 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
39 </p>
40</div></body>
41</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>6.6. BitBake Command Line</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake">
9<link rel="prev" href="ref-bitbake-runtask.html" title="6.5. Running a Task">
10<link rel="next" href="ref-bitbake-fetchers.html" title="6.7. Fetchers">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.6. BitBake Command Line">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-bitbake-commandline"></a>6.6. BitBake Command Line</h2></div></div></div>
15<p>
16 Following is the BitBake help output:
17 </p>
18<pre class="screen">
19$ bitbake --help
20Usage: bitbake [options] [package ...]
21
22Executes the specified task (default is 'build') for a given set of BitBake files.
23It expects that BBFILES is defined, which is a space separated list of files to
24be executed. BBFILES does support wildcards.
25Default BBFILES are the .bb files in the current directory.
26
27Options:
28 --version show program's version number and exit
29 -h, --help show this help message and exit
30 -b BUILDFILE, --buildfile=BUILDFILE
31 execute the task against this .bb file, rather than a
32 package from BBFILES. Does not handle any
33 dependencies.
34 -k, --continue continue as much as possible after an error. While the
35 target that failed, and those that depend on it,
36 cannot be remade, the other dependencies of these
37 targets can be processed all the same.
38 -a, --tryaltconfigs continue with builds by trying to use alternative
39 providers where possible.
40 -f, --force force run of specified cmd, regardless of stamp status
41 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes
42 the specified task for the providee and the packages
43 it depends on, i.e. 'compile' does not implicitly call
44 stage for the dependencies (IOW: use only if you know
45 what you are doing). Depending on the base.bbclass a
46 listtasks tasks is defined and will show available
47 tasks
48 -r PREFILE, --read=PREFILE
49 read the specified file before bitbake.conf
50 -R POSTFILE, --postread=POSTFILE
51 read the specified file after bitbake.conf
52 -v, --verbose output more chit-chat to the terminal
53 -D, --debug Increase the debug level. You can specify this more
54 than once.
55 -n, --dry-run don't execute, just go through the motions
56 -S, --dump-signatures
57 don't execute, just dump out the signature
58 construction information
59 -p, --parse-only quit after parsing the BB files (developers only)
60 -s, --show-versions show current and preferred versions of all packages
61 -e, --environment show the global or per-package environment (this is
62 what used to be bbread)
63 -g, --graphviz emit the dependency trees of the specified packages in
64 the dot syntax
65 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
66 Assume these dependencies don't exist and are already
67 provided (equivalent to ASSUME_PROVIDED). Useful to
68 make dependency graphs more appealing
69 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
70 Show debug logging for the specified logging domains
71 -P, --profile profile the command and print a report
72 -u UI, --ui=UI userinterface to use
73 -t SERVERTYPE, --servertype=SERVERTYPE
74 Choose which server to use, none, process or xmlrpc
75 --revisions-changed Set the exit code depending on whether upstream
76 floating revisions have changed or not
77 </pre>
78</div></body>
79</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>6.3. Dependencies</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake">
9<link rel="prev" href="ref-bitbake-providers.html" title="6.2. Preferences and Providers">
10<link rel="next" href="ref-bitbake-tasklist.html" title="6.4. The Task List">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.3. Dependencies">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-bitbake-dependencies"></a>6.3. Dependencies</h2></div></div></div>
15<p>
16 Each target BitBake builds consists of multiple tasks such as
17 <code class="filename">fetch</code>, <code class="filename">unpack</code>,
18 <code class="filename">patch</code>, <code class="filename">configure</code>,
19 and <code class="filename">compile</code>.
20 For best performance on multi-core systems, BitBake considers each task as an independent
21 entity with its own set of dependencies.
22 </p>
23<p>
24 Dependencies are defined through several variables.
25 You can find information about variables BitBake uses in the BitBake documentation,
26 which is found in the <code class="filename">bitbake/doc/manual</code> directory within the
27 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
28 At a basic level, it is sufficient to know that BitBake uses the
29 <code class="filename"><a class="link" href="ref-variables-glos.html#var-DEPENDS" title="DEPENDS">DEPENDS</a></code> and
30 <code class="filename"><a class="link" href="ref-variables-glos.html#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variables when
31 calculating dependencies.
32 </p>
33</div></body>
34</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>6.7. Fetchers</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake">
9<link rel="prev" href="ref-bitbake-commandline.html" title="6.6. BitBake Command Line">
10<link rel="next" href="ref-classes.html" title="Chapter 7. Classes">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.7. Fetchers">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-bitbake-fetchers"></a>6.7. Fetchers</h2></div></div></div>
15<p>
16 BitBake also contains a set of "fetcher" modules that allow
17 retrieval of source code from various types of sources.
18 For example, BitBake can get source code from a disk with the metadata, from websites,
19 from remote shell accounts or from Source Code Management (SCM) systems
20 like <code class="filename">cvs/subversion/git</code>.
21 </p>
22<p>
23 Fetchers are usually triggered by entries in
24 <code class="filename"><a class="link" href="ref-variables-glos.html#var-SRC_URI" title="SRC_URI">SRC_URI</a></code>.
25 You can find information about the options and formats of entries for specific
26 fetchers in the BitBake manual located in the
27 <code class="filename">bitbake/doc/manual</code> directory of the
28 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
29 </p>
30<p>
31 One useful feature for certain Source Code Manager (SCM) fetchers is the ability to
32 "auto-update" when the upstream SCM changes version.
33 Since this ability requires certain functionality from the SCM, not all
34 systems support it.
35 Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update".
36 This feature works using the <code class="filename"><a class="link" href="ref-variables-glos.html#var-SRCREV" title="SRCREV">SRCREV</a></code>
37 variable.
38 See the
39 "<a class="link" href="../dev-manual/platdev-appdev-srcrev.html" target="_self">Using an External SCM</a>" section
40 in the Yocto Project Development Manual for more information.
41 </p>
42</div></body>
43</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>6.1. Parsing</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake">
9<link rel="prev" href="ref-bitbake.html" title="Chapter 6. BitBake">
10<link rel="next" href="ref-bitbake-providers.html" title="6.2. Preferences and Providers">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.1. Parsing">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-bitbake-parsing"></a>6.1. Parsing</h2></div></div></div>
15<p>
16 BitBake parses configuration files, classes, and <code class="filename">.bb</code> files.
17 </p>
18<p>
19 The first thing BitBake does is look for the <code class="filename">bitbake.conf</code> file.
20 This file resides in the
21 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>
22 within the <code class="filename">meta/conf/</code> directory.
23 BitBake finds it by examining its
24 <a class="link" href="ref-variables-glos.html#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a> environment
25 variable and looking for the <code class="filename">meta/conf/</code>
26 directory.
27 </p>
28<p>
29 The <code class="filename">bitbake.conf</code> file lists other configuration
30 files to include from a <code class="filename">conf/</code>
31 directory below the directories listed in <code class="filename">BBPATH</code>.
32 In general, the most important configuration file from a user's perspective
33 is <code class="filename">local.conf</code>, which contains a user's customized
34 settings for the OpenEmbedded build environment.
35 Other notable configuration files are the distribution
36 configuration file (set by the
37 <code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO" title="DISTRO">DISTRO</a></code> variable)
38 and the machine configuration file
39 (set by the
40 <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE">MACHINE</a></code> variable).
41 The <code class="filename">DISTRO</code> and <code class="filename">MACHINE</code> BitBake environment
42 variables are both usually set in
43 the <code class="filename">local.conf</code> file.
44 Valid distribution
45 configuration files are available in the <code class="filename">meta/conf/distro/</code> directory
46 and valid machine configuration
47 files in the <code class="filename">meta/conf/machine/</code> directory.
48 Within the <code class="filename">meta/conf/machine/include/</code>
49 directory are various <code class="filename">tune-*.inc</code> configuration files that provide common
50 "tuning" settings specific to and shared between particular architectures and machines.
51 </p>
52<p>
53 After the parsing of the configuration files, some standard classes are included.
54 The <code class="filename">base.bbclass</code> file is always included.
55 Other classes that are specified in the configuration using the
56 <code class="filename"><a class="link" href="ref-variables-glos.html#var-INHERIT" title="INHERIT">INHERIT</a></code>
57 variable are also included.
58 Class files are searched for in a <code class="filename">classes</code> subdirectory
59 under the paths in <code class="filename">BBPATH</code> in the same way as
60 configuration files.
61 </p>
62<p>
63 After classes are included, the variable
64 <code class="filename"><a class="link" href="ref-variables-glos.html#var-BBFILES" title="BBFILES">BBFILES</a></code>
65 is set, usually in
66 <code class="filename">local.conf</code>, and defines the list of places to search for
67 <code class="filename">.bb</code> files.
68 By default, the <code class="filename">BBFILES</code> variable specifies the
69 <code class="filename">meta/recipes-*/</code> directory within Poky.
70 Adding extra content to <code class="filename">BBFILES</code> is best achieved through the use of
71 BitBake layers as described in the
72 "<a class="link" href="../dev-manual/understanding-and-creating-layers.html" target="_self">Understanding and
73 Creating Layers</a>" section of the Yocto Project Development Manual.
74 </p>
75<p>
76 BitBake parses each <code class="filename">.bb</code> file in <code class="filename">BBFILES</code> and
77 stores the values of various variables.
78 In summary, for each <code class="filename">.bb</code>
79 file the configuration plus the base class of variables are set, followed
80 by the data in the <code class="filename">.bb</code> file
81 itself, followed by any inherit commands that
82 <code class="filename">.bb</code> file might contain.
83 </p>
84<p>
85 Because parsing <code class="filename">.bb</code> files is a time
86 consuming process, a cache is kept to speed up subsequent parsing.
87 This cache is invalid if the timestamp of the <code class="filename">.bb</code>
88 file itself changes, or if the timestamps of any of the include,
89 configuration or class files the <code class="filename">.bb</code>
90 file depends on changes.
91 </p>
92</div></body>
93</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>6.2. Preferences and Providers</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake">
9<link rel="prev" href="ref-bitbake-parsing.html" title="6.1. Parsing">
10<link rel="next" href="ref-bitbake-dependencies.html" title="6.3. Dependencies">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.2. Preferences and Providers">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-bitbake-providers"></a>6.2. Preferences and Providers</h2></div></div></div>
15<p>
16 Once all the <code class="filename">.bb</code> files have been
17 parsed, BitBake starts to build the target (<code class="filename">core-image-sato</code>
18 in the previous section's example) and looks for providers of that target.
19 Once a provider is selected, BitBake resolves all the dependencies for
20 the target.
21 In the case of <code class="filename">core-image-sato</code>, it would lead to
22 <code class="filename">packagegroup-core-x11-sato</code>,
23 which in turn leads to recipes like <code class="filename">matchbox-terminal</code>,
24 <code class="filename">pcmanfm</code> and <code class="filename">gthumb</code>.
25 These recipes in turn depend on <code class="filename">eglibc</code> and the toolchain.
26 </p>
27<p>
28 Sometimes a target might have multiple providers.
29 A common example is "virtual/kernel", which is provided by each kernel package.
30 Each machine often selects the best kernel provider by using a line similar to the
31 following in the machine configuration file:
32 </p>
33<pre class="literallayout">
34 PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
35 </pre>
36<p>
37 The default <code class="filename"><a class="link" href="ref-variables-glos.html#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">PREFERRED_PROVIDER</a></code>
38 is the provider with the same name as the target.
39 </p>
40<p>
41 Understanding how providers are chosen is made complicated by the fact
42 that multiple versions might exist.
43 BitBake defaults to the highest version of a provider.
44 Version comparisons are made using the same method as Debian.
45 You can use the
46 <code class="filename"><a class="link" href="ref-variables-glos.html#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></code>
47 variable to specify a particular version (usually in the distro configuration).
48 You can influence the order by using the
49 <code class="filename"><a class="link" href="ref-variables-glos.html#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></code>
50 variable.
51 By default, files have a preference of "0".
52 Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "-1" makes the
53 package unlikely to be used unless it is explicitly referenced.
54 Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "1" makes it likely the package is used.
55 <code class="filename">PREFERRED_VERSION</code> overrides any <code class="filename">DEFAULT_PREFERENCE</code> setting.
56 <code class="filename">DEFAULT_PREFERENCE</code> is often used to mark newer and more experimental package
57 versions until they have undergone sufficient testing to be considered stable.
58 </p>
59<p>
60 In summary, BitBake has created a list of providers, which is prioritized, for each target.
61 </p>
62</div></body>
63</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>6.5. Running a Task</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake">
9<link rel="prev" href="ref-bitbake-tasklist.html" title="6.4. The Task List">
10<link rel="next" href="ref-bitbake-commandline.html" title="6.6. BitBake Command Line">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.5. Running a Task">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-bitbake-runtask"></a>6.5. Running a Task</h2></div></div></div>
15<p>
16 Tasks can either be a shell task or a Python task.
17 For shell tasks, BitBake writes a shell script to
18 <code class="filename">${WORKDIR}/temp/run.do_taskname.pid</code> and then executes the script.
19 The generated shell script contains all the exported variables, and the shell functions
20 with all variables expanded.
21 Output from the shell script goes to the file <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>.
22 Looking at the expanded shell functions in the run file and the output in the log files
23 is a useful debugging technique.
24 </p>
25<p>
26 For Python tasks, BitBake executes the task internally and logs information to the
27 controlling terminal.
28 Future versions of BitBake will write the functions to files similar to the way
29 shell tasks are handled.
30 Logging will be handled in way similar to shell tasks as well.
31 </p>
32<p>
33 Once all the tasks have been completed BitBake exits.
34 </p>
35<p>
36 When running a task, BitBake tightly controls the execution environment
37 of the build tasks to make sure unwanted contamination from the build machine
38 cannot influence the build.
39 Consequently, if you do want something to get passed into the build
40 task's environment, you must take a few steps:
41 </p>
42<div class="orderedlist"><ol class="orderedlist" type="1">
43<li class="listitem">
44<p>Tell BitBake to load what you want from the environment
45 into the data store.
46 You can do so through the <code class="filename">BB_ENV_EXTRAWHITE</code>
47 variable.
48 For example, assume you want to prevent the build system from
49 accessing your <code class="filename">$HOME/.ccache</code> directory.
50 The following command tells BitBake to load
51 <code class="filename">CCACHE_DIR</code> from the environment into the data
52 store:
53 </p>
54<pre class="literallayout">
55 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
56 </pre>
57</li>
58<li class="listitem">
59<p>Tell BitBake to export what you have loaded into the
60 environment store to the task environment of every running task.
61 Loading something from the environment into the data store
62 (previous step) only makes it available in the datastore.
63 To export it to the task environment of every running task,
64 use a command similar to the following in your
65 <code class="filename">local.conf</code> or distro configuration file:
66 </p>
67<pre class="literallayout">
68 export CCACHE_DIR
69 </pre>
70</li>
71</ol></div>
72<p>
73 </p>
74<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
75<h3 class="title">Note</h3>
76 A side effect of the previous steps is that BitBake records the variable
77 as a dependency of the build process in things like the shared state
78 checksums.
79 If doing so results in unnecessary rebuilds of tasks, you can whitelist the
80 variable so that the shared state code ignores the dependency when it creates
81 checksums.
82 For information on this process, see the <code class="filename">BB_HASHBASE_WHITELIST</code>
83 example in the "<a class="link" href="checksums.html" title="3.2.2. Checksums (Signatures)">Checksums (Signatures)</a>" section.
84 </div>
85</div></body>
86</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>6.4. The Task List</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-bitbake.html" title="Chapter 6. BitBake">
9<link rel="prev" href="ref-bitbake-dependencies.html" title="6.3. Dependencies">
10<link rel="next" href="ref-bitbake-runtask.html" title="6.5. Running a Task">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="6.4. The Task List">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-bitbake-tasklist"></a>6.4. The Task List</h2></div></div></div>
15<p>
16 Based on the generated list of providers and the dependency information,
17 BitBake can now calculate exactly what tasks it needs to run and in what
18 order it needs to run them.
19 The build now starts with BitBake forking off threads up to the limit set in the
20 <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.
21 BitBake continues to fork threads as long as there are tasks ready to run,
22 those tasks have all their dependencies met, and the thread threshold has not been
23 exceeded.
24 </p>
25<p>
26 It is worth noting that you can greatly speed up the build time by properly setting
27 the <code class="filename">BB_NUMBER_THREADS</code> variable.
28 See the
29 "<a class="link" href="../yocto-project-qs/building-image.html" target="_self">Building an Image</a>"
30 section in the Yocto Project Quick Start for more information.
31 </p>
32<p>
33 As each task completes, a timestamp is written to the directory specified by the
34 <code class="filename"><a class="link" href="ref-variables-glos.html#var-STAMP" title="STAMP">STAMP</a></code> variable (usually
35 <code class="filename">build/tmp/stamps/*/</code>).
36 On subsequent runs, BitBake looks at the <code class="filename">/build/tmp/stamps</code>
37 directory and does not rerun
38 tasks that are already completed unless a timestamp is found to be invalid.
39 Currently, invalid timestamps are only considered on a per
40 <code class="filename">.bb</code> file basis.
41 So, for example, if the configure stamp has a timestamp greater than the
42 compile timestamp for a given target, then the compile task would rerun.
43 Running the compile task again, however, has no effect on other providers
44 that depend on that target.
45 This behavior could change or become configurable in future versions of BitBake.
46 </p>
47<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
48<h3 class="title">Note</h3>
49 Some tasks are marked as "nostamp" tasks.
50 No timestamp file is created when these tasks are run.
51 Consequently, "nostamp" tasks are always rerun.
52 </div>
53</div></body>
54</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 6. BitBake</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="structure-meta-recipes-txt.html" title="5.3.19. meta/recipes.txt">
10<link rel="next" href="ref-bitbake-parsing.html" title="6.1. Parsing">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 6. BitBake">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="ref-bitbake"></a>Chapter 6. BitBake</h2></div></div></div>
15<div class="toc">
16<p><b>Table of Contents</b></p>
17<dl>
18<dt><span class="section"><a href="ref-bitbake-parsing.html">6.1. Parsing</a></span></dt>
19<dt><span class="section"><a href="ref-bitbake-providers.html">6.2. Preferences and Providers</a></span></dt>
20<dt><span class="section"><a href="ref-bitbake-dependencies.html">6.3. Dependencies</a></span></dt>
21<dt><span class="section"><a href="ref-bitbake-tasklist.html">6.4. The Task List</a></span></dt>
22<dt><span class="section"><a href="ref-bitbake-runtask.html">6.5. Running a Task</a></span></dt>
23<dt><span class="section"><a href="ref-bitbake-commandline.html">6.6. BitBake Command Line</a></span></dt>
24<dt><span class="section"><a href="ref-bitbake-fetchers.html">6.7. Fetchers</a></span></dt>
25</dl>
26</div>
27<p>
28 BitBake is a program written in Python that interprets the metadata used by the OpenEmbedded
29 build system.
30 At some point, developers wonder what actually happens when you enter:
31 </p>
32<pre class="literallayout">
33 $ bitbake core-image-sato
34 </pre>
35<p>
36 </p>
37<p>
38 This chapter provides an overview of what happens behind the scenes from BitBake's perspective.
39 </p>
40<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
41<h3 class="title">Note</h3>
42 BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships.
43 As such, it has no real knowledge of what the tasks being executed actually do.
44 BitBake just considers a list of tasks with dependencies and handles metadata
45 that consists of variables in a certain format that get passed to the tasks.
46 </div>
47</div></body>
48</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.2. Autotooled Packages - autotools.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-base.html" title="7.1. The base class - base.bbclass">
10<link rel="next" href="ref-classes-update-alternatives.html" title="7.3. Alternatives - update-alternatives.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.2. Autotooled Packages - autotools.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-autotools"></a>7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code>
15</h2></div></div></div>
16<p>
17 Autotools (<code class="filename">autoconf</code>, <code class="filename">automake</code>,
18 and <code class="filename">libtool</code>) bring standardization.
19 This class defines a set of tasks (configure, compile etc.) that
20 work for all Autotooled packages.
21 It should usually be enough to define a few standard variables
22 and then simply <code class="filename">inherit autotools</code>.
23 This class can also work with software that emulates Autotools.
24 For more information, see the
25 "<a class="link" href="../dev-manual/usingpoky-extend-addpkg-autotools.html" target="_self">Autotooled Package</a>"
26 section in the Yocto Project Development Manual.
27 </p>
28<p>
29 It's useful to have some idea of how the tasks defined by this class work
30 and what they do behind the scenes.
31 </p>
32<div class="itemizedlist"><ul class="itemizedlist" type="disc">
33<li class="listitem"><p><code class="filename">do_configure</code> &#8208; regenerates the
34 configure script (using <code class="filename">autoreconf</code>) and then launches it
35 with a standard set of arguments used during cross-compilation.
36 You can pass additional parameters to <code class="filename">configure</code> through the
37 <code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></code> variable.
38 </p></li>
39<li class="listitem"><p><code class="filename">do_compile</code> &#8208; runs <code class="filename">make</code> with
40 arguments that specify the compiler and linker.
41 You can pass additional arguments through
42 the <code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></code> variable.
43 </p></li>
44<li class="listitem"><p><code class="filename">do_install</code> &#8208; runs <code class="filename">make install</code>
45 and passes a DESTDIR option, which takes its value from the standard
46 <code class="filename"><a class="link" href="ref-variables-glos.html#var-DESTDIR" title="DESTDIR">DESTDIR</a></code> variable.
47 </p></li>
48</ul></div>
49<p>
50 </p>
51</div></body>
52</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.1. The base class - base.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes.html" title="Chapter 7. Classes">
10<link rel="next" href="ref-classes-autotools.html" title="7.2. Autotooled Packages - autotools.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.1. The base class - base.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-base"></a>7.1. The base class - <code class="filename">base.bbclass</code>
15</h2></div></div></div>
16<p>
17 The base class is special in that every <code class="filename">.bb</code>
18 file inherits it automatically.
19 This class contains definitions for standard basic
20 tasks such as fetching, unpacking, configuring (empty by default), compiling
21 (runs any <code class="filename">Makefile</code> present), installing (empty by default) and packaging
22 (empty by default).
23 These classes are often overridden or extended by other classes
24 such as <code class="filename">autotools.bbclass</code> or <code class="filename">package.bbclass</code>.
25 The class also contains some commonly used functions such as <code class="filename">oe_runmake</code>.
26 </p>
27</div></body>
28</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.5. Binary config scripts - binconfig.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-update-rc.d.html" title="7.4. Initscripts - update-rc.d.bbclass">
10<link rel="next" href="ref-classes-debian.html" title="7.6. Debian renaming - debian.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.5. Binary config scripts - binconfig.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-binconfig"></a>7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code>
15</h2></div></div></div>
16<p>
17 Before <code class="filename">pkg-config</code> had become widespread, libraries shipped shell
18 scripts to give information about the libraries and include paths needed
19 to build software (usually named <code class="filename">LIBNAME-config</code>).
20 This class assists any recipe using such scripts.
21 </p>
22<p>
23 During staging, BitBake installs such scripts into the
24 <code class="filename">sysroots/</code> directory.
25 BitBake also changes all paths to point into the <code class="filename">sysroots/</code>
26 directory so all builds that use the script will use the correct
27 directories for the cross compiling layout.
28 </p>
29</div></body>
30</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.6. Debian renaming - debian.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-binconfig.html" title="7.5. Binary config scripts - binconfig.bbclass">
10<link rel="next" href="ref-classes-pkgconfig.html" title="7.7. Pkg-config - pkgconfig.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.6. Debian renaming - debian.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-debian"></a>7.6. Debian renaming - <code class="filename">debian.bbclass</code>
15</h2></div></div></div>
16<p>
17 This class renames packages so that they follow the Debian naming
18 policy (i.e. <code class="filename">eglibc</code> becomes <code class="filename">libc6</code>
19 and <code class="filename">eglibc-devel</code> becomes <code class="filename">libc6-dev</code>.
20 </p>
21</div></body>
22</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.11. Developer Shell - devshell.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-distutils.html" title="7.10. Python extensions - distutils.bbclass">
10<link rel="next" href="ref-classes-packagegroup.html" title="7.12. Package Groups - packagegroup.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.11. Developer Shell - devshell.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-devshell"></a>7.11. Developer Shell - <code class="filename">devshell.bbclass</code>
15</h2></div></div></div>
16<p>
17 This class adds the <code class="filename">devshell</code> task.
18 Distribution policy dictates whether to include this class.
19 See the
20 "<a class="link" href="../dev-manual/platdev-appdev-devshell.html" target="_self">Using a Development Shell</a>" section
21 in the Yocto Project Development Manual for more information about using <code class="filename">devshell</code>.
22 </p>
23</div></body>
24</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.10. Python extensions - distutils.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-perl.html" title="7.9. Perl modules - cpan.bbclass">
10<link rel="next" href="ref-classes-devshell.html" title="7.11. Developer Shell - devshell.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.10. Python extensions - distutils.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-distutils"></a>7.10. Python extensions - <code class="filename">distutils.bbclass</code>
15</h2></div></div></div>
16<p>
17 Recipes for Python extensions are simple.
18 These recipes usually only need to point to the source's archive and then inherit
19 the proper <code class="filename">.bbclass</code> file.
20 Building is split into two methods dependling on which method the module authors used.
21 </p>
22<p>
23 Extensions that use an Autotools-based build system require Autotools and
24 <code class="filename">distutils</code>-based <code class="filename">.bbclasse</code> files in their recipes.
25 </p>
26<p>
27 Extensions that use <code class="filename">distutils</code>-based build systems require
28 <code class="filename">distutils.bbclass</code> in their recipes.
29 </p>
30</div></body>
31</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.20. Using External Source - externalsrc.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-useradd.html" title="7.19. Adding Users - useradd.bbclass">
10<link rel="next" href="ref-classes-others.html" title="7.21. Other Classes">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.20. Using External Source - externalsrc.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-externalsrc"></a>7.20. Using External Source - <code class="filename">externalsrc.bbclass</code>
15</h2></div></div></div>
16<p>
17 You can use this class to build software from source code that is external to the
18 OpenEmbedded build system.
19 In other words, your source code resides in an external tree outside of the Yocto Project.
20 Building software from an external source tree means that the normal fetch, unpack, and
21 patch process is not used.
22 </p>
23<p>
24 To use the class, you need to define the
25 <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.
26 You also need to have your recipe inherit the <code class="filename">externalsrc.bbclass</code> class.
27 </p>
28<p>
29 This class expects the source code to support recipe builds that use the
30 <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
31 which the OpenEmbedded build system places the generated objects built from the recipes.
32 By default, the <code class="filename">B</code> directory is set to the following, which is separate from the
33 Source Directory (<code class="filename">S</code>):
34 </p>
35<pre class="literallayout">
36 ${WORKDIR}/${BPN}-{PV}/
37 </pre>
38<p>
39 See the glossary entries for the
40 <a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>,
41 <a class="link" href="ref-variables-glos.html#var-BPN" title="BPN"><code class="filename">BPN</code></a>,
42 <a class="link" href="ref-variables-glos.html#var-PV" title="PV"><code class="filename">PV</code></a>,
43 <a class="link" href="ref-variables-glos.html#var-S" title="S"><code class="filename">S</code></a>, and
44 <a class="link" href="ref-variables-glos.html#var-B" title="B"><code class="filename">B</code></a> for more information.
45 </p>
46<p>
47 You can build object files in the external tree by setting the
48 <code class="filename">B</code> variable equal to <code class="filename">"${S}"</code>.
49 However, this practice does not work well if you use the source for more than one variant
50 (i.e., "natives" such as <code class="filename">quilt-native</code>,
51 or "crosses" such as <code class="filename">gcc-cross</code>).
52 So, be sure there are no "native", "cross", or "multilib" variants of the recipe.
53 </p>
54<p>
55 If you do want to build different variants of a recipe, you can use the
56 <a class="link" href="ref-variables-glos.html#var-BBCLASSEXTEND" title="BBCLASSEXTEND"><code class="filename">BBCLASSEXTEND</code></a> variable.
57 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
58 recipe's ability to build variants in different working directories.
59 Most autotools-based recipes support separating these directories.
60 The OpenEmbedded build system defaults to using separate directories for <code class="filename">gcc</code>
61 and some kernel recipes.
62 Alternatively, you can make sure that separate recipes exist that each
63 use the <code class="filename">BBCLASSEXTEND</code> variable to build each variant.
64 The separate recipes can inherit a single target recipe.
65 </p>
66<p>
67 For information on how to use this class, see the
68 "<a class="link" href="../dev-manual/building-software-from-an-external-source.html" target="_self">Building
69 Software from an External Source</a>" section in the Yocto Project Development Manual.
70 </p>
71</div></body>
72</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.15. Creating images - image.bbclass and rootfs*.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-kernel.html" title="7.14. Building kernels - kernel.bbclass">
10<link rel="next" href="ref-classes-sanity.html" title="7.16. Host System sanity checks - sanity.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.15. Creating images - image.bbclass and rootfs*.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-image"></a>7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code>
15</h2></div></div></div>
16<p>
17 These classes add support for creating images in several formats.
18 First, the root filesystem is created from packages using
19 one of the <code class="filename">rootfs_*.bbclass</code>
20 files (depending on the package format used) and then the image is created.
21 </p>
22<p>
23 The <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></code>
24 variable controls the types of images to generate.
25 </p>
26<p>
27 The <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></code>
28 variable controls the list of packages to install into the image.
29 </p>
30</div></body>
31</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.17. Generated output quality assurance checks - insane.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-sanity.html" title="7.16. Host System sanity checks - sanity.bbclass">
10<link rel="next" href="ref-classes-siteinfo.html" title="7.18. Autotools configuration data cache - siteinfo.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.17. Generated output quality assurance checks - insane.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-insane"></a>7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code>
15</h2></div></div></div>
16<p>
17 This class adds a step to the package generation process that sanity checks the
18 packages generated by the OpenEmbedded build system.
19 A range of checks are performed that check the build's output
20 for common problems that show up during runtime.
21 Distribution policy usually dictates whether to include this class.
22 </p>
23<p>
24 You can configure the sanity checks so that specific test failures either raise a warning or
25 an error message.
26 Typically, failures for new tests generate a warning.
27 Subsequent failures for the same test would then generate an error message
28 once the metadata is in a known and good condition.
29 You use the <code class="filename">WARN_QA</code> variable to specify tests for which you
30 want to generate a warning message on failure.
31 You use the <code class="filename">ERROR_QA</code> variable to specify tests for which you
32 want to generate an error message on failure.
33 </p>
34<p>
35 The following list shows the tests you can list with the <code class="filename">WARN_QA</code>
36 and <code class="filename">ERROR_QA</code> variables:
37 </p>
38<div class="itemizedlist"><ul class="itemizedlist" type="disc">
39<li class="listitem"><p><span class="emphasis"><em><code class="filename">ldflags:</code></em></span>
40 Ensures that the binaries were linked with the
41 <code class="filename">LDFLAGS</code> options provided by the build system.
42 If this test fails, check that the <code class="filename">LDFLAGS</code> variable
43 is being passed to the linker command.</p></li>
44<li class="listitem"><p><span class="emphasis"><em><code class="filename">useless-rpaths:</code></em></span>
45 Checks for dynamic library load paths (rpaths) in the binaries that
46 by default on a standard system are searched by the linker (e.g.
47 <code class="filename">/lib</code> and <code class="filename">/usr/lib</code>).
48 While these paths will not cause any breakage, they do waste space and
49 are unnecessary.</p></li>
50<li class="listitem"><p><span class="emphasis"><em><code class="filename">rpaths:</code></em></span>
51 Checks for rpaths in the binaries that contain build system paths such
52 as <code class="filename">TMPDIR</code>.
53 If this test fails, bad <code class="filename">-rpath</code> options are being
54 passed to the linker commands and your binaries have potential security
55 issues.</p></li>
56<li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-so:</code></em></span>
57 Checks that the <code class="filename">.so</code> symbolic links are in the
58 <code class="filename">-dev</code> package and not in any of the other packages.
59 In general, these symlinks are only useful for development purposes.
60 Thus, the <code class="filename">-dev</code> package is the correct location for
61 them.
62 Some very rare cases do exist for dynamically loaded modules where
63 these symlinks are needed instead in the main package.
64 </p></li>
65<li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-files:</code></em></span>
66 Checks for <code class="filename">.debug</code> directories in anything but the
67 <code class="filename">-dbg</code> package.
68 The debug files should all be in the <code class="filename">-dbg</code> package.
69 Thus, anything packaged elsewhere is incorrect packaging.</p></li>
70<li class="listitem"><p><span class="emphasis"><em><code class="filename">arch:</code></em></span>
71 Checks the Executable and Linkable Format (ELF) type, bit size and endianness
72 of any binaries to ensure it matches the target architecture.
73 This test fails if any binaries don't match the type since there would be an
74 incompatibility.
75 Sometimes software, like bootloaders, might need to bypass this check.
76 </p></li>
77<li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-deps:</code></em></span>
78 Checks that <code class="filename">-dbg</code> packages only depend on other
79 <code class="filename">-dbg</code> packages and not on any other types of packages,
80 which would cause a packaging bug.</p></li>
81<li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-deps:</code></em></span>
82 Checks that <code class="filename">-dev</code> packages only depend on other
83 <code class="filename">-dev</code> packages and not on any other types of packages,
84 which would be a packaging bug.</p></li>
85<li class="listitem"><p><span class="emphasis"><em><code class="filename">pkgconfig:</code></em></span>
86 Checks <code class="filename">.pc</code> files for any
87 <code class="filename">TMPDIR/WORKDIR</code> paths.
88 Any <code class="filename">.pc</code> file containing these paths is incorrect
89 since <code class="filename">pkg-config</code> itself adds the correct sysroot prefix
90 when the files are accessed.</p></li>
91<li class="listitem"><p><span class="emphasis"><em><code class="filename">la:</code></em></span>
92 Checks <code class="filename">.la</code> files for any <code class="filename">TMPDIR</code>
93 paths.
94 Any <code class="filename">.la</code> file continaing these paths is incorrect since
95 <code class="filename">libtool</code> adds the correct sysroot prefix when using the
96 files automatically itself.</p></li>
97<li class="listitem"><p><span class="emphasis"><em><code class="filename">desktop:</code></em></span>
98 Runs the <code class="filename">desktop-file-validate</code> program against any
99 <code class="filename">.desktop</code> files to validate their contents against
100 the specification for <code class="filename">.desktop</code> files.</p></li>
101</ul></div>
102<p>
103 </p>
104</div></body>
105</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.14. Building kernels - kernel.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-package.html" title="7.13. Packaging - package*.bbclass">
10<link rel="next" href="ref-classes-image.html" title="7.15. Creating images - image.bbclass and rootfs*.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.14. Building kernels - kernel.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-kernel"></a>7.14. Building kernels - <code class="filename">kernel.bbclass</code>
15</h2></div></div></div>
16<p>
17 This class handles building Linux kernels.
18 The class contains code to build all kernel trees.
19 All needed headers are staged into the
20 <code class="filename"><a class="link" href="ref-variables-glos.html#var-STAGING_KERNEL_DIR" title="STAGING_KERNEL_DIR">STAGING_KERNEL_DIR</a></code>
21 directory to allow out-of-tree module builds using <code class="filename">module.bbclass</code>.
22 </p>
23<p>
24 This means that each built kernel module is packaged separately and inter-module
25 dependencies are created by parsing the <code class="filename">modinfo</code> output.
26 If all modules are required, then installing the <code class="filename">kernel-modules</code>
27 package installs all packages with modules and various other kernel packages
28 such as <code class="filename">kernel-vmlinux</code>.
29 </p>
30<p>
31 Various other classes are used by the kernel and module classes internally including
32 <code class="filename">kernel-arch.bbclass</code>, <code class="filename">module_strip.bbclass</code>,
33 <code class="filename">module-base.bbclass</code>, and <code class="filename">linux-kernel-base.bbclass</code>.
34 </p>
35</div></body>
36</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.21. Other Classes</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-externalsrc.html" title="7.20. Using External Source - externalsrc.bbclass">
10<link rel="next" href="ref-images.html" title="Chapter 8. Images">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.21. Other Classes">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-others"></a>7.21. Other Classes</h2></div></div></div>
15<p>
16 Thus far, this chapter has discussed only the most useful and important
17 classes.
18 However, other classes exist within the <code class="filename">meta/classes</code> directory
19 in the <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
20 You can examine the <code class="filename">.bbclass</code> files directly for more
21 information.
22 </p>
23</div></body>
24</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.13. Packaging - package*.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-packagegroup.html" title="7.12. Package Groups - packagegroup.bbclass">
10<link rel="next" href="ref-classes-kernel.html" title="7.14. Building kernels - kernel.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.13. Packaging - package*.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-package"></a>7.13. Packaging - <code class="filename">package*.bbclass</code>
15</h2></div></div></div>
16<p>
17 The packaging classes add support for generating packages from a build's
18 output.
19 The core generic functionality is in <code class="filename">package.bbclass</code>.
20 The code specific to particular package types is contained in various sub-classes such as
21 <code class="filename">package_deb.bbclass</code>, <code class="filename">package_ipk.bbclass</code>,
22 and <code class="filename">package_rpm.bbclass</code>.
23 Most users will want one or more of these classes.
24 </p>
25<p>
26 You can control the list of resulting package formats by using the
27 <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></code>
28 variable defined in the <code class="filename">local.conf</code> configuration file,
29 which is located in the <code class="filename">conf</code> folder of the
30 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
31 When defining the variable, you can specify one or more package types.
32 Since images are generated from packages, a packaging class is
33 needed to enable image generation.
34 The first class listed in this variable is used for image generation.
35 </p>
36<p>
37 The package class you choose can affect build-time performance and has space
38 ramifications.
39 In general, building a package with RPM takes about thirty percent more time as
40 compared to using IPK to build the same or similar package.
41 This comparison takes into account a complete build of the package with all
42 dependencies previously built.
43 The reason for this discrepancy is because the RPM package manager creates and
44 processes more metadata than the IPK package manager.
45 Consequently, you might consider setting <code class="filename">PACKAGE_CLASSES</code>
46 to "package_ipk" if you are building smaller systems.
47 </p>
48<p>
49 Keep in mind, however, that RPM starts to provide more abilities than IPK due to
50 the fact that it processes more metadata.
51 For example, this information includes individual file types, file checksum generation
52 and evaluation on install, sparse file support, conflict detection and resolution
53 for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks.
54 </p>
55<p>
56 Another consideration for packages built using the RPM package manager is space.
57 For smaller systems, the extra space used for the Berkley Database and the amount
58 of metadata can affect your ability to do on-device upgrades.
59 </p>
60<p>
61 You can find additional information on the effects of the package class at these
62 two Yocto Project mailing list links:
63 </p>
64<div class="itemizedlist"><ul class="itemizedlist" type="disc">
65<li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html" target="_self">
66 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</a></p></li>
67<li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html" target="_self">
68 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</a></p></li>
69</ul></div>
70<p>
71 </p>
72</div></body>
73</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.12. Package Groups - packagegroup.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-devshell.html" title="7.11. Developer Shell - devshell.bbclass">
10<link rel="next" href="ref-classes-package.html" title="7.13. Packaging - package*.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.12. Package Groups - packagegroup.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-packagegroup"></a>7.12. Package Groups - <code class="filename">packagegroup.bbclass</code>
15</h2></div></div></div>
16<p>
17 This class sets default values appropriate for package group recipes (such as
18 <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>,
19 <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></code>,
20 <code class="filename"><a class="link" href="ref-variables-glos.html#var-ALLOW_EMPTY" title="ALLOW_EMPTY">ALLOW_EMPTY</a></code>,
21 and so forth.
22 It is highly recommended that all package group recipes inherit this class.
23 </p>
24<p>
25 For information on how to use this class, see the
26 "<a class="link" href="../dev-manual/usingpoky-extend-customimage-customtasks.html" target="_self">Customizing Images Using Custom Package Tasks</a>"
27 section in the Yocto Project Development Manual.
28 </p>
29<p>
30 Previously, this class was named <code class="filename">task.bbclass</code>.
31 </p>
32</div></body>
33</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.9. Perl modules - cpan.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-src-distribute.html" title="7.8. Distribution of sources - src_distribute_local.bbclass">
10<link rel="next" href="ref-classes-distutils.html" title="7.10. Python extensions - distutils.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.9. Perl modules - cpan.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-perl"></a>7.9. Perl modules - <code class="filename">cpan.bbclass</code>
15</h2></div></div></div>
16<p>
17 Recipes for Perl modules are simple.
18 These recipes usually only need to point to the source's archive and then inherit the
19 proper <code class="filename">.bbclass</code> file.
20 Building is split into two methods depending on which method the module authors used.
21 </p>
22<p>
23 Modules that use old <code class="filename">Makefile.PL</code>-based build system require
24 <code class="filename">cpan.bbclass</code> in their recipes.
25 </p>
26<p>
27 Modules that use <code class="filename">Build.PL</code>-based build system require
28 using <code class="filename">cpan_build.bbclass</code> in their recipes.
29 </p>
30</div></body>
31</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.7. Pkg-config - pkgconfig.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-debian.html" title="7.6. Debian renaming - debian.bbclass">
10<link rel="next" href="ref-classes-src-distribute.html" title="7.8. Distribution of sources - src_distribute_local.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.7. Pkg-config - pkgconfig.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-pkgconfig"></a>7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code>
15</h2></div></div></div>
16<p>
17 <code class="filename">pkg-config</code> brought standardization and this class aims to make its
18 integration smooth for all libraries that make use of it.
19 </p>
20<p>
21 During staging, BitBake installs <code class="filename">pkg-config</code> data into the
22 <code class="filename">sysroots/</code> directory.
23 By making use of sysroot functionality within <code class="filename">pkg-config</code>,
24 this class no longer has to manipulate the files.
25 </p>
26</div></body>
27</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.16. Host System sanity checks - sanity.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-image.html" title="7.15. Creating images - image.bbclass and rootfs*.bbclass">
10<link rel="next" href="ref-classes-insane.html" title="7.17. Generated output quality assurance checks - insane.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.16. Host System sanity checks - sanity.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-sanity"></a>7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code>
15</h2></div></div></div>
16<p>
17 This class checks to see if prerequisite software is present so that
18 users can be notified of potential problems that might affect their build.
19 The class also performs basic user configuration checks from
20 the <code class="filename">local.conf</code> configuration file to
21 prevent common mistakes that cause build failures.
22 Distribution policy usually determines whether to include this class.
23 </p>
24</div></body>
25</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.18. Autotools configuration data cache - siteinfo.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-insane.html" title="7.17. Generated output quality assurance checks - insane.bbclass">
10<link rel="next" href="ref-classes-useradd.html" title="7.19. Adding Users - useradd.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.18. Autotools configuration data cache - siteinfo.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-siteinfo"></a>7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code>
15</h2></div></div></div>
16<p>
17 Autotools can require tests that must execute on the target hardware.
18 Since this is not possible in general when cross compiling, site information is
19 used to provide cached test results so these tests can be skipped over but
20 still make the correct values available.
21 The <code class="filename"><a class="link" href="structure-meta-site.html" title="5.3.18. meta/site/">meta/site directory</a></code>
22 contains test results sorted into different categories such as architecture, endianness, and
23 the <code class="filename">libc</code> used.
24 Site information provides a list of files containing data relevant to
25 the current build in the
26 <code class="filename"><a class="link" href="ref-variables-glos.html#var-CONFIG_SITE" title="CONFIG_SITE">CONFIG_SITE</a></code> variable
27 that Autotools automatically picks up.
28 </p>
29<p>
30 The class also provides variables like
31 <code class="filename"><a class="link" href="ref-variables-glos.html#var-SITEINFO_ENDIANNESS" title="SITEINFO_ENDIANNESS">SITEINFO_ENDIANNESS</a></code>
32 and <code class="filename"><a class="link" href="ref-variables-glos.html#var-SITEINFO_BITS" title="SITEINFO_BITS">SITEINFO_BITS</a></code>
33 that can be used elsewhere in the metadata.
34 </p>
35<p>
36 Because this class is included from <code class="filename">base.bbclass</code>, it is always active.
37 </p>
38</div></body>
39</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.8. Distribution of sources - src_distribute_local.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-pkgconfig.html" title="7.7. Pkg-config - pkgconfig.bbclass">
10<link rel="next" href="ref-classes-perl.html" title="7.9. Perl modules - cpan.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.8. Distribution of sources - src_distribute_local.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-src-distribute"></a>7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code>
15</h2></div></div></div>
16<p>
17 Many software licenses require that source files be provided along with the binaries.
18 To simplify this process, two classes were created:
19 <code class="filename">src_distribute.bbclass</code> and
20 <code class="filename">src_distribute_local.bbclass</code>.
21 </p>
22<p>
23 The results of these classes are <code class="filename">tmp/deploy/source/</code>
24 subdirs with sources sorted by
25 <code class="filename"><a class="link" href="ref-variables-glos.html#var-LICENSE" title="LICENSE">LICENSE</a></code> field.
26 If recipes list few licenses (or have entries like "Bitstream Vera"),
27 the source archive is placed in each license directory.
28 </p>
29<p>
30 This class operates using three modes:
31 </p>
32<div class="itemizedlist"><ul class="itemizedlist" type="disc">
33<li class="listitem"><p><span class="emphasis"><em>copy:</em></span> Copies the files to the
34 distribute directory.</p></li>
35<li class="listitem"><p><span class="emphasis"><em>symlink:</em></span> Symlinks the files to the
36 distribute directory.</p></li>
37<li class="listitem"><p><span class="emphasis"><em>move+symlink:</em></span> Moves the files into
38 the distribute directory and then symlinks them back.</p></li>
39</ul></div>
40<p>
41 </p>
42</div></body>
43</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.3. Alternatives - update-alternatives.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-autotools.html" title="7.2. Autotooled Packages - autotools.bbclass">
10<link rel="next" href="ref-classes-update-rc.d.html" title="7.4. Initscripts - update-rc.d.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.3. Alternatives - update-alternatives.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-update-alternatives"></a>7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code>
15</h2></div></div></div>
16<p>
17 Several programs can fulfill the same or similar function and be installed with the same name.
18 For example, the <code class="filename">ar</code> command is available from the
19 <code class="filename">busybox</code>, <code class="filename">binutils</code> and
20 <code class="filename">elfutils</code> packages.
21 The <code class="filename">update-alternatives.bbclass</code> class handles renaming the
22 binaries so that multiple packages can be installed without conflicts.
23 The <code class="filename">ar</code> command still works regardless of which packages are installed
24 or subsequently removed.
25 The class renames the conflicting binary in each package and symlinks the highest
26 priority binary during installation or removal of packages.
27 </p>
28<p>
29 Four variables control this class:
30 </p>
31<div class="itemizedlist"><ul class="itemizedlist" type="disc">
32<li class="listitem"><p><code class="filename">ALTERNATIVE_NAME</code> &#8208; The name of the
33 binary that is replaced (<code class="filename">ar</code> in this example).</p></li>
34<li class="listitem"><p><code class="filename">ALTERNATIVE_LINK</code> &#8208; The path to
35 the resulting binary (<code class="filename">/bin/ar</code> in this example).</p></li>
36<li class="listitem"><p><code class="filename">ALTERNATIVE_PATH</code> &#8208; The path to the
37 real binary (<code class="filename">/usr/bin/ar.binutils</code> in this example).</p></li>
38<li class="listitem"><p><code class="filename">ALTERNATIVE_PRIORITY</code> &#8208; The priority of
39 the binary.
40 The version with the most features should have the highest priority.</p></li>
41</ul></div>
42<p>
43 </p>
44<p>
45 Currently, the OpenEmbedded build system supports only one binary per package.
46 </p>
47</div></body>
48</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.4. Initscripts - update-rc.d.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-update-alternatives.html" title="7.3. Alternatives - update-alternatives.bbclass">
10<link rel="next" href="ref-classes-binconfig.html" title="7.5. Binary config scripts - binconfig.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.4. Initscripts - update-rc.d.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-update-rc.d"></a>7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code>
15</h2></div></div></div>
16<p>
17 This class uses <code class="filename">update-rc.d</code> to safely install an
18 initialization script on behalf of the package.
19 The OpenEmbedded build system takes care of details such as making sure the script is stopped before
20 a package is removed and started when the package is installed.
21 Three variables control this class:
22 <code class="filename"><a class="link" href="ref-variables-glos.html#var-INITSCRIPT_PACKAGES" title="INITSCRIPT_PACKAGES">INITSCRIPT_PACKAGES</a></code>,
23 <code class="filename"><a class="link" href="ref-variables-glos.html#var-INITSCRIPT_NAME" title="INITSCRIPT_NAME">INITSCRIPT_NAME</a></code> and
24 <code class="filename"><a class="link" href="ref-variables-glos.html#var-INITSCRIPT_PARAMS" title="INITSCRIPT_PARAMS">INITSCRIPT_PARAMS</a></code>.
25 See the variable links for details.
26 </p>
27</div></body>
28</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>7.19. Adding Users - useradd.bbclass</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-classes.html" title="Chapter 7. Classes">
9<link rel="prev" href="ref-classes-siteinfo.html" title="7.18. Autotools configuration data cache - siteinfo.bbclass">
10<link rel="next" href="ref-classes-externalsrc.html" title="7.20. Using External Source - externalsrc.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="7.19. Adding Users - useradd.bbclass">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-classes-useradd"></a>7.19. Adding Users - <code class="filename">useradd.bbclass</code>
15</h2></div></div></div>
16<p>
17 If you have packages that install files that are owned by custom users or groups,
18 you can use this class to specify those packages and associate the users and groups
19 with those packages.
20 The <code class="filename">meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</code>
21 recipe in the <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>
22 provides a simple exmample that shows how to add three
23 users and groups to two packages.
24 See the <code class="filename">useradd-example.bb</code> for more information on how to
25 use this class.
26 </p>
27</div></body>
28</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 7. Classes</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="ref-bitbake-fetchers.html" title="6.7. Fetchers">
10<link rel="next" href="ref-classes-base.html" title="7.1. The base class - base.bbclass">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 7. Classes">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="ref-classes"></a>Chapter 7. Classes</h2></div></div></div>
15<div class="toc">
16<p><b>Table of Contents</b></p>
17<dl>
18<dt><span class="section"><a href="ref-classes-base.html">7.1. The base class - <code class="filename">base.bbclass</code></a></span></dt>
19<dt><span class="section"><a href="ref-classes-autotools.html">7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt>
20<dt><span class="section"><a href="ref-classes-update-alternatives.html">7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt>
21<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>
22<dt><span class="section"><a href="ref-classes-binconfig.html">7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt>
23<dt><span class="section"><a href="ref-classes-debian.html">7.6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt>
24<dt><span class="section"><a href="ref-classes-pkgconfig.html">7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt>
25<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>
26<dt><span class="section"><a href="ref-classes-perl.html">7.9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt>
27<dt><span class="section"><a href="ref-classes-distutils.html">7.10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt>
28<dt><span class="section"><a href="ref-classes-devshell.html">7.11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt>
29<dt><span class="section"><a href="ref-classes-packagegroup.html">7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></a></span></dt>
30<dt><span class="section"><a href="ref-classes-package.html">7.13. Packaging - <code class="filename">package*.bbclass</code></a></span></dt>
31<dt><span class="section"><a href="ref-classes-kernel.html">7.14. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt>
32<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>
33<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>
34<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>
35<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>
36<dt><span class="section"><a href="ref-classes-useradd.html">7.19. Adding Users - <code class="filename">useradd.bbclass</code></a></span></dt>
37<dt><span class="section"><a href="ref-classes-externalsrc.html">7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></a></span></dt>
38<dt><span class="section"><a href="ref-classes-others.html">7.21. Other Classes</a></span></dt>
39</dl>
40</div>
41<p>
42 Class files are used to abstract common functionality and share it amongst multiple
43 <code class="filename">.bb</code> files.
44 Any metadata usually found in a <code class="filename">.bb</code> file can also be placed in a class
45 file.
46 Class files are identified by the extension <code class="filename">.bbclass</code> and are usually placed
47 in a <code class="filename">classes/</code> directory beneath the
48 <code class="filename">meta*/</code> directory found in the
49 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
50 Class files can also be pointed to by BUILDDIR (e.g. <code class="filename">build/</code>)in the same way as
51 <code class="filename">.conf</code> files in the <code class="filename">conf</code> directory.
52 Class files are searched for in <a class="link" href="ref-variables-glos.html#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a>
53 using the same method by which <code class="filename">.conf</code> files are searched.
54</p>
55<p>
56 In most cases inheriting the class is enough to enable its features, although
57 for some classes you might need to set variables or override some of the
58 default behaviour.
59</p>
60</div></body>
61</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>9.4. Feature Backfilling</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-features.html" title="Chapter 9. Reference: Features">
9<link rel="prev" href="ref-features-image.html" title="9.3. Images">
10<link rel="next" href="ref-variables-glos.html" title="Chapter 10. Variables Glossary">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="9.4. Feature Backfilling">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-features-backfill"></a>9.4. Feature Backfilling</h2></div></div></div>
15<p>
16 Sometimes it is necessary in the OpenEmbedded build system to extend
17 <a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a>
18 or <a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>
19 to control functionality that was previously enabled and not able
20 to be disabled.
21 For these cases, we need to add an
22 additional feature item to appear in one of these variables,
23 but we do not want to force developers who have existing values
24 of the variables in their configuration to add the new feature
25 in order to retain the same overall level of functionality.
26 Thus, the OpenEmbedded build system has a mechanism to
27 automatically "backfill" these added features into existing
28 distro or machine configurations.
29 You can see the list of features for which this is done by
30 finding the
31 <a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES_BACKFILL" title="DISTRO_FEATURES_BACKFILL"><code class="filename">DISTRO_FEATURES_BACKFILL</code></a>
32 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>
33 variables in the <code class="filename">meta/conf/bitbake.conf</code> file.
34 </p>
35<p>
36 Because such features are backfilled by default into all
37 configurations as described in the previous paragraph, developers
38 who wish to disable the new features need to be able to selectively
39 prevent the backfilling from occurring.
40 They can do this by adding the undesired feature or features to the
41 <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>
42 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>
43 variables for distro features and machine features respectively.
44 </p>
45<p>
46 Here are two examples to help illustrate feature backfilling:
47 </p>
48<div class="itemizedlist"><ul class="itemizedlist" type="disc">
49<li class="listitem"><p><span class="emphasis"><em>The "pulseaudio" distro feature option</em></span>:
50 Previously, PulseAudio support was enabled within the Qt and
51 GStreamer frameworks.
52 Because of this, the feature is backfilled and thus
53 enabled for all distros through the
54 <code class="filename">DISTRO_FEATURES_BACKFILL</code>
55 variable in the <code class="filename">meta/conf/bitbake.conf</code> file.
56 However, your distro needs to disable the feature.
57 You can disable the feature without affecting
58 other existing distro configurations that need PulseAudio support
59 by adding "pulseaudio" to
60 <code class="filename">DISTRO_FEATURES_BACKFILL_CONSIDERED</code>
61 in your distro's <code class="filename">.conf</code> file.
62 Adding the feature to this variable when it also
63 exists in the <code class="filename">DISTRO_FEATURES_BACKFILL</code>
64 variable prevents the build system from adding the feature to
65 your configuration's <code class="filename">DISTRO_FEATURES</code>, effectively disabling
66 the feature for that particular distro.</p></li>
67<li class="listitem"><p><span class="emphasis"><em>The "rtc" machine feature option</em></span>:
68 Previously, real time clock (RTC) support was enabled for all
69 target devices.
70 Because of this, the feature is backfilled and thus enabled
71 for all machines through the <code class="filename">MACHINE_FEATURES_BACKFILL</code>
72 variable in the <code class="filename">meta/conf/bitbake.conf</code> file.
73 However, your target device does not have this capability.
74 You can disable RTC support for your device without
75 affecting other machines that need RTC support
76 by adding the feature to your machine's
77 <code class="filename">MACHINE_FEATURES_BACKFILL_CONSIDERED</code>
78 list in the machine's <code class="filename">.conf</code> file.
79 Adding the feature to this variable when it also
80 exists in the <code class="filename">MACHINE_FEATURES_BACKFILL</code>
81 variable prevents the build system from adding the feature to
82 your configuration's <code class="filename">MACHINE_FEATURES</code>, effectively
83 disabling RTC support for that particular machine.</p></li>
84</ul></div>
85<p>
86 </p>
87</div></body>
88</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>9.1. Distro</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-features.html" title="Chapter 9. Reference: Features">
9<link rel="prev" href="ref-features.html" title="Chapter 9. Reference: Features">
10<link rel="next" href="ref-features-machine.html" title="9.2. Machine">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="9.1. Distro">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-features-distro"></a>9.1. Distro</h2></div></div></div>
15<p>
16 The items below are features you can use with
17 <a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>.
18 Features do not have a one-to-one correspondence to packages, and they can
19 go beyond simply controlling the installation of a package or packages.
20 Sometimes a feature can influence how certain recipes are built.
21 For example, a feature might determine whether a particular configure option
22 is specified within <code class="filename">do_configure</code> for a particular
23 recipe.
24 </p>
25<p>
26 This list only represents features as shipped with the Yocto Project metadata:
27 </p>
28<div class="itemizedlist"><ul class="itemizedlist" type="disc">
29<li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> ALSA support will be included (OSS compatibility
30 kernel modules will be installed if available).</p></li>
31<li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Include bluetooth support (integrated BT only)
32 </p></li>
33<li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Include tools for supporting for devices with internal
34 HDD/Microdrive for storing files (instead of Flash only devices)
35 </p></li>
36<li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Include Irda support
37 </p></li>
38<li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Include keyboard support (e.g. keymaps will be
39 loaded during boot).
40 </p></li>
41<li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Include PCI bus support
42 </p></li>
43<li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Include PCMCIA/CompactFlash support
44 </p></li>
45<li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> USB Gadget Device support (for USB
46 networking/serial/storage)
47 </p></li>
48<li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> USB Host support (allows to connect external
49 keyboard, mouse, storage, network etc)
50 </p></li>
51<li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> WiFi support (integrated only)
52 </p></li>
53<li class="listitem"><p><span class="emphasis"><em>cramfs:</em></span> CramFS support
54 </p></li>
55<li class="listitem"><p><span class="emphasis"><em>ipsec:</em></span> IPSec support
56 </p></li>
57<li class="listitem"><p><span class="emphasis"><em>ipv6:</em></span> IPv6 support
58 </p></li>
59<li class="listitem"><p><span class="emphasis"><em>nfs:</em></span> NFS client support (for mounting NFS exports on
60 device)</p></li>
61<li class="listitem"><p><span class="emphasis"><em>ppp:</em></span> PPP dialup support</p></li>
62<li class="listitem"><p><span class="emphasis"><em>smbfs:</em></span> SMB networks client support (for mounting
63 Samba/Microsoft Windows shares on device)</p></li>
64</ul></div>
65<p>
66 </p>
67</div></body>
68</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>9.3. Images</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-features.html" title="Chapter 9. Reference: Features">
9<link rel="prev" href="ref-features-machine.html" title="9.2. Machine">
10<link rel="next" href="ref-features-backfill.html" title="9.4. Feature Backfilling">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="9.3. Images">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-features-image"></a>9.3. Images</h2></div></div></div>
15<p>
16 The contents of images generated by the OpenEmbedded build system can be controlled by the
17 <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code>
18 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>
19 variables that you typically configure in your image recipes.
20 Through these variables you can add several different
21 predefined packages such as development utilities or packages with debug
22 information needed to investigate application problems or profile applications.
23 </p>
24<p>
25 Current list of
26 <code class="filename">IMAGE_FEATURES</code> contains the following:
27 </p>
28<div class="itemizedlist"><ul class="itemizedlist" type="disc">
29<li class="listitem"><p><span class="emphasis"><em>splash:</em></span> Enables showing a splash screen during boot.
30 By default, this screen is provided by <code class="filename">psplash</code>, which does
31 allow customization.
32 If you prefer to use an alternative splash screen package, you can do so by
33 setting the <code class="filename">SPLASH</code> variable
34 to a different package name (or names) within the image recipe or at the distro
35 configuration level.</p></li>
36<li class="listitem"><p><span class="emphasis"><em>ssh-server-dropbear:</em></span> Installs the Dropbear minimal
37 SSH server.
38 </p></li>
39<li class="listitem"><p><span class="emphasis"><em>ssh-server-openssh:</em></span> Installs the OpenSSH SSH server,
40 which is more full-featured than Dropbear.
41 Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server
42 are present in <code class="filename">IMAGE_FEATURES</code>, then OpenSSH will take
43 precedence and Dropbear will not be installed.</p></li>
44<li class="listitem"><p><span class="emphasis"><em>x11:</em></span> Installs the X server</p></li>
45<li class="listitem"><p><span class="emphasis"><em>x11-base:</em></span> Installs the X server with a
46 minimal environment.</p></li>
47<li class="listitem"><p><span class="emphasis"><em>x11-sato:</em></span> Installs the OpenedHand Sato environment.
48 </p></li>
49<li class="listitem"><p><span class="emphasis"><em>tools-sdk:</em></span> Installs a full SDK that runs on the device.
50 </p></li>
51<li class="listitem"><p><span class="emphasis"><em>tools-debug:</em></span> Installs debugging tools such as
52 <code class="filename">strace</code> and <code class="filename">gdb</code>.
53 </p></li>
54<li class="listitem"><p><span class="emphasis"><em>tools-profile:</em></span> Installs profiling tools such as
55 <code class="filename">oprofile</code>, <code class="filename">exmap</code>, and
56 <code class="filename">LTTng</code>.</p></li>
57<li class="listitem"><p><span class="emphasis"><em>tools-testapps:</em></span> Installs device testing tools (e.g.
58 touchscreen debugging).</p></li>
59<li class="listitem"><p><span class="emphasis"><em>nfs-server:</em></span> Installs an NFS server.</p></li>
60<li class="listitem"><p><span class="emphasis"><em>dev-pkgs:</em></span> Installs development packages (headers and
61 extra library links) for all packages installed in a given image.</p></li>
62<li class="listitem"><p><span class="emphasis"><em>staticdev-pkgs:</em></span> Installs static development
63 packages (i.e. static libraries containing <code class="filename">*.a</code> files) for all
64 packages installed in a given image.</p></li>
65<li class="listitem"><p><span class="emphasis"><em>dbg-pkgs:</em></span> Installs debug symbol packages for all packages
66 installed in a given image.</p></li>
67<li class="listitem"><p><span class="emphasis"><em>doc-pkgs:</em></span> Installs documentation packages for all packages
68 installed in a given image.</p></li>
69</ul></div>
70<p>
71 </p>
72</div></body>
73</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>9.2. Machine</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-features.html" title="Chapter 9. Reference: Features">
9<link rel="prev" href="ref-features-distro.html" title="9.1. Distro">
10<link rel="next" href="ref-features-image.html" title="9.3. Images">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="9.2. Machine">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-features-machine"></a>9.2. Machine</h2></div></div></div>
15<p>
16 The items below are features you can use with
17 <a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a>.
18 Features do not have a one-to-one correspondence to packages, and they can
19 go beyond simply controlling the installation of a package or packages.
20 Sometimes a feature can influence how certain recipes are built.
21 For example, a feature might determine whether a particular configure option
22 is specified within <code class="filename">do_configure</code> for a particular
23 recipe.
24 </p>
25<p>
26 This feature list only represents features as shipped with the Yocto Project metadata:
27 </p>
28<div class="itemizedlist"><ul class="itemizedlist" type="disc">
29<li class="listitem"><p><span class="emphasis"><em>acpi:</em></span> Hardware has ACPI (x86/x86_64 only)
30 </p></li>
31<li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> Hardware has ALSA audio drivers
32 </p></li>
33<li class="listitem"><p><span class="emphasis"><em>apm:</em></span> Hardware uses APM (or APM emulation)
34 </p></li>
35<li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Hardware has integrated BT
36 </p></li>
37<li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Hardware HDD or Microdrive
38 </p></li>
39<li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Hardware has Irda support
40 </p></li>
41<li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Hardware has a keyboard
42 </p></li>
43<li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Hardware has a PCI bus
44 </p></li>
45<li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Hardware has PCMCIA or CompactFlash sockets
46 </p></li>
47<li class="listitem"><p><span class="emphasis"><em>screen:</em></span> Hardware has a screen
48 </p></li>
49<li class="listitem"><p><span class="emphasis"><em>serial:</em></span> Hardware has serial support (usually RS232)
50 </p></li>
51<li class="listitem"><p><span class="emphasis"><em>touchscreen:</em></span> Hardware has a touchscreen
52 </p></li>
53<li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> Hardware is USB gadget device capable
54 </p></li>
55<li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> Hardware is USB Host capable
56 </p></li>
57<li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> Hardware has integrated WiFi
58 </p></li>
59</ul></div>
60<p>
61 </p>
62</div></body>
63</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 9. Reference: Features</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="ref-images.html" title="Chapter 8. Images">
10<link rel="next" href="ref-features-distro.html" title="9.1. Distro">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 9. Reference: Features">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="ref-features"></a>Chapter 9. Reference: Features</h2></div></div></div>
15<div class="toc">
16<p><b>Table of Contents</b></p>
17<dl>
18<dt><span class="section"><a href="ref-features-distro.html">9.1. Distro</a></span></dt>
19<dt><span class="section"><a href="ref-features-machine.html">9.2. Machine</a></span></dt>
20<dt><span class="section"><a href="ref-features-image.html">9.3. Images</a></span></dt>
21<dt><span class="section"><a href="ref-features-backfill.html">9.4. Feature Backfilling</a></span></dt>
22</dl>
23</div>
24<p>
25 Features provide a mechanism for working out which packages
26 should be included in the generated images.
27 Distributions can select which features they want to support through the
28 <code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>
29 variable, which is set in the <code class="filename">poky.conf</code> distribution configuration file.
30 Machine features are set in the
31 <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>
32 variable, which is set in the machine configuration file and
33 specifies the hardware features for a given machine.
34 </p>
35<p>
36 These two variables combine to work out which kernel modules,
37 utilities, and other packages to include.
38 A given distribution can support a selected subset of features so some machine features might not
39 be included if the distribution itself does not support them.
40 </p>
41<p>
42 One method you can use to determine which recipes are checking to see if a
43 particular feature is contained or not is to <code class="filename">grep</code> through
44 the metadata for the feature.
45 Here is an example that discovers the recipes whose build is potentially
46 changed based on a given feature:
47 </p>
48<pre class="literallayout">
49 $ cd $HOME/poky
50 $ git grep 'contains.*MACHINE_FEATURES.*&lt;feature&gt;'
51 </pre>
52<p>
53 </p>
54<p>
55 This chapter provides a reference of shipped machine and distro features
56 you can include as part of the image, a reference on image types you can
57 build, and a reference on feature backfilling.
58 </p>
59</div></body>
60</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 8. Images</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="ref-classes-others.html" title="7.21. Other Classes">
10<link rel="next" href="ref-features.html" title="Chapter 9. Reference: Features">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 8. Images">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="ref-images"></a>Chapter 8. Images</h2></div></div></div>
15<p>
16 The OpenEmbedded build process supports several types of images to satisfy different needs.
17 When you issue the <code class="filename">bitbake</code> command you provide a &#8220;top-level&#8221; recipe
18 that essentially begins the build for the type of image you want.
19 </p>
20<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
21<h3 class="title">Note</h3>
22 Building an image without GNU General Public License Version 3 (GPLv3) components
23 is only supported for minimal and base images.
24 Furthermore, if you are going to build an image using non-GPLv3 components,
25 you must make the following changes in the <code class="filename">local.conf</code> file
26 before using the BitBake command to build the minimal or base image:
27 <pre class="literallayout">
28 1. Comment out the EXTRA_IMAGE_FEATURES line
29 2. Set INCOMPATIBLE_LICENSE = "GPLv3"
30 </pre>
31</div>
32<p>
33 From within the <code class="filename">poky</code> Git repository, use the following command to list
34 the supported images:
35 </p>
36<pre class="literallayout">
37 $ ls meta*/recipes*/images/*.bb
38 </pre>
39<p>
40 These recipes reside in the <code class="filename">meta/recipes-core/images</code>,
41 <code class="filename">meta/recipes-extended/images</code>,
42 <code class="filename">meta/recipes-graphics/images</code>, and
43 <code class="filename">meta/recipes-sato/images</code> directories
44 within the <a class="link" href="../dev-manual/source-directory.html" target="_self">source directory</a>.
45 Although the recipe names are somewhat explanatory, here is a list that describes them:
46 </p>
47<div class="itemizedlist"><ul class="itemizedlist" type="disc">
48<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-base</code>:</em></span>
49 A console-only image that fully supports the target device hardware.</p></li>
50<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal</code>:</em></span>
51 A small image just capable of allowing a device to boot.</p></li>
52<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-dev</code>:</em></span>
53 A <code class="filename">core-image-minimal</code> image suitable for development work
54 using the host.
55 The image includes headers and libraries you can use in a host development
56 environment.
57 </p></li>
58<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-initramfs</code>:</em></span>
59 A <code class="filename">core-image-minimal</code> image that has the Minimal RAM-based
60 Initial Root Filesystem (<code class="filename">initramfs</code>) as part of the kernel,
61 which allows the system to find the first &#8220;init&#8221; program more efficiently.
62 </p></li>
63<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-mtdutils</code>:</em></span>
64 A <code class="filename">core-image-minimal</code> image that has support
65 for the Minimal MTD Utilities, which let the user interact with the
66 MTD subsystem in the kernel to perform operations on flash devices.
67 </p></li>
68<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-x11</code>:</em></span>
69 A very basic X11 image with a terminal.
70 </p></li>
71<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-basic</code>:</em></span>
72 A console-only image with more full-featured Linux system
73 functionality installed.</p></li>
74<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb</code>:</em></span>
75 An image that conforms to the Linux Standard Base (LSB) specification.</p></li>
76<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-dev</code>:</em></span>
77 A <code class="filename">core-image-lsb</code> image that is suitable for development work
78 using the host.
79 The image includes headers and libraries you can use in a host development
80 environment.
81 </p></li>
82<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-sdk</code>:</em></span>
83 A <code class="filename">core-image-lsb</code> that includes everything in meta-toolchain
84 but also includes development headers and libraries to form a complete standalone SDK.
85 This image is suitable for development using the target.</p></li>
86<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-clutter</code>:</em></span>
87 An image with support for the Open GL-based toolkit Clutter, which enables development of
88 rich and animated graphical user interfaces.</p></li>
89<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato</code>:</em></span>
90 An image with Sato support, a mobile environment and visual style that works well
91 with mobile devices.
92 The image supports X11 with a Sato theme and applications such as
93 a terminal, editor, file manager, media player, and so forth.</p></li>
94<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-dev</code>:</em></span>
95 A <code class="filename">core-image-sato</code> image suitable for development
96 using the host.
97 The image includes libraries needed to build applications on the device itself,
98 testing and profiling tools, and debug symbols.
99 This image was formerly <code class="filename">core-image-sdk</code>.</p></li>
100<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-sdk</code>:</em></span>
101 A <code class="filename">core-image-sato</code> image that includes everything in meta-toolchain.
102 The image also includes development headers and libraries to form a complete standalone SDK
103 and is suitable for development using the target.</p></li>
104<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt</code>:</em></span>
105 A <code class="filename">core-image-minimal</code> image plus a real-time test suite and
106 tools appropriate for real-time use.</p></li>
107<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt-sdk</code>:</em></span>
108 A <code class="filename">core-image-rt</code> image that includes everything in
109 <code class="filename">meta-toolchain</code>.
110 The image also includes development headers and libraries to form a complete
111 stand-alone SDK and is suitable for development using the target.</p></li>
112<li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-gtk-directfb</code>:</em></span>
113 An image that uses <code class="filename">gtk+</code> over <code class="filename">directfb</code>
114 instead of X11.
115 In order to build, this image requires specific distro configuration that enables
116 <code class="filename">gtk</code> over <code class="filename">directfb</code>.</p></li>
117<li class="listitem"><p><span class="emphasis"><em><code class="filename">build-appliance-image</code>:</em></span>
118 An image you can boot and run using either the
119 <a class="ulink" href="http://www.vmware.com/products/player/overview.html" target="_self">VMware Player</a>
120 or <a class="ulink" href="http://www.vmware.com/products/workstation/overview.html" target="_self">VMware Workstation</a>.
121 For more information on this image, see the
122 <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_self">Build Appliance</a> page on
123 the Yocto Project website.</p></li>
124</ul></div>
125<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;">
126<h3 class="title">Tip</h3>
127 From the Yocto Project release 1.1 onwards, <code class="filename">-live</code> and
128 <code class="filename">-directdisk</code> images have been replaced by a "live"
129 option in <code class="filename">IMAGE_FSTYPES</code> that will work with any image to produce an
130 image file that can be
131 copied directly to a CD or USB device and run as is.
132 To build a live image, simply add
133 "live" to <code class="filename">IMAGE_FSTYPES</code> within the <code class="filename">local.conf</code>
134 file or wherever appropriate and then build the desired image as normal.
135 </div>
136</div></body>
137</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 5. Source Directory Structure</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="migration-1.3-removed-recipes.html" title="4.1.2.6. Removed Recipes">
10<link rel="next" href="structure-core.html" title="5.1. Top level core components">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 5. Source Directory Structure">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="ref-structure"></a>Chapter 5. Source Directory Structure</h2></div></div></div>
15<div class="toc">
16<p><b>Table of Contents</b></p>
17<dl>
18<dt><span class="section"><a href="structure-core.html">5.1. Top level core components</a></span></dt>
19<dd><dl>
20<dt><span class="section"><a href="structure-core-bitbake.html">5.1.1. <code class="filename">bitbake/</code></a></span></dt>
21<dt><span class="section"><a href="structure-core-build.html">5.1.2. <code class="filename">build/</code></a></span></dt>
22<dt><span class="section"><a href="handbook.html">5.1.3. <code class="filename">documentation</code></a></span></dt>
23<dt><span class="section"><a href="structure-core-meta.html">5.1.4. <code class="filename">meta/</code></a></span></dt>
24<dt><span class="section"><a href="structure-core-meta-yocto.html">5.1.5. <code class="filename">meta-yocto/</code></a></span></dt>
25<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>
26<dt><span class="section"><a href="structure-meta-hob.html">5.1.7. <code class="filename">meta-hob/</code></a></span></dt>
27<dt><span class="section"><a href="structure-meta-skeleton.html">5.1.8. <code class="filename">meta-skeleton/</code></a></span></dt>
28<dt><span class="section"><a href="structure-core-scripts.html">5.1.9. <code class="filename">scripts/</code></a></span></dt>
29<dt><span class="section"><a href="structure-core-script.html">5.1.10. <code class="filename">oe-init-build-env</code></a></span></dt>
30<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>
31</dl></dd>
32<dt><span class="section"><a href="structure-build.html">5.2. The Build Directory - <code class="filename">build/</code></a></span></dt>
33<dd><dl>
34<dt><span class="section"><a href="structure-build-pseudodone.html">5.2.1. <code class="filename">build/pseudodone</code></a></span></dt>
35<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>
36<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>
37<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>
38<dt><span class="section"><a href="structure-build-downloads.html">5.2.5. <code class="filename">build/downloads/</code></a></span></dt>
39<dt><span class="section"><a href="structure-build-sstate-cache.html">5.2.6. <code class="filename">build/sstate-cache/</code></a></span></dt>
40<dt><span class="section"><a href="structure-build-tmp.html">5.2.7. <code class="filename">build/tmp/</code></a></span></dt>
41<dt><span class="section"><a href="structure-build-tmp-buildstats.html">5.2.8. <code class="filename">build/tmp/buildstats/</code></a></span></dt>
42<dt><span class="section"><a href="structure-build-tmp-cache.html">5.2.9. <code class="filename">build/tmp/cache/</code></a></span></dt>
43<dt><span class="section"><a href="structure-build-tmp-deploy.html">5.2.10. <code class="filename">build/tmp/deploy/</code></a></span></dt>
44<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>
45<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>
46<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>
47<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>
48<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>
49<dt><span class="section"><a href="structure-build-tmp-sysroots.html">5.2.16. <code class="filename">build/tmp/sysroots/</code></a></span></dt>
50<dt><span class="section"><a href="structure-build-tmp-stamps.html">5.2.17. <code class="filename">build/tmp/stamps/</code></a></span></dt>
51<dt><span class="section"><a href="structure-build-tmp-log.html">5.2.18. <code class="filename">build/tmp/log/</code></a></span></dt>
52<dt><span class="section"><a href="structure-build-tmp-pkgdata.html">5.2.19. <code class="filename">build/tmp/pkgdata/</code></a></span></dt>
53<dt><span class="section"><a href="structure-build-tmp-work.html">5.2.20. <code class="filename">build/tmp/work/</code></a></span></dt>
54</dl></dd>
55<dt><span class="section"><a href="structure-meta.html">5.3. The Metadata - <code class="filename">meta/</code></a></span></dt>
56<dd><dl>
57<dt><span class="section"><a href="structure-meta-classes.html">5.3.1. <code class="filename">meta/classes/</code></a></span></dt>
58<dt><span class="section"><a href="structure-meta-conf.html">5.3.2. <code class="filename">meta/conf/</code></a></span></dt>
59<dt><span class="section"><a href="structure-meta-conf-machine.html">5.3.3. <code class="filename">meta/conf/machine/</code></a></span></dt>
60<dt><span class="section"><a href="structure-meta-conf-distro.html">5.3.4. <code class="filename">meta/conf/distro/</code></a></span></dt>
61<dt><span class="section"><a href="structure-meta-recipes-bsp.html">5.3.5. <code class="filename">meta/recipes-bsp/</code></a></span></dt>
62<dt><span class="section"><a href="structure-meta-recipes-connectivity.html">5.3.6. <code class="filename">meta/recipes-connectivity/</code></a></span></dt>
63<dt><span class="section"><a href="structure-meta-recipes-core.html">5.3.7. <code class="filename">meta/recipes-core/</code></a></span></dt>
64<dt><span class="section"><a href="structure-meta-recipes-devtools.html">5.3.8. <code class="filename">meta/recipes-devtools/</code></a></span></dt>
65<dt><span class="section"><a href="structure-meta-recipes-extended.html">5.3.9. <code class="filename">meta/recipes-extended/</code></a></span></dt>
66<dt><span class="section"><a href="structure-meta-recipes-gnome.html">5.3.10. <code class="filename">meta/recipes-gnome/</code></a></span></dt>
67<dt><span class="section"><a href="structure-meta-recipes-graphics.html">5.3.11. <code class="filename">meta/recipes-graphics/</code></a></span></dt>
68<dt><span class="section"><a href="structure-meta-recipes-kernel.html">5.3.12. <code class="filename">meta/recipes-kernel/</code></a></span></dt>
69<dt><span class="section"><a href="structure-meta-recipes-multimedia.html">5.3.13. <code class="filename">meta/recipes-multimedia/</code></a></span></dt>
70<dt><span class="section"><a href="structure-meta-recipes-qt.html">5.3.14. <code class="filename">meta/recipes-qt/</code></a></span></dt>
71<dt><span class="section"><a href="structure-meta-recipes-rt.html">5.3.15. <code class="filename">meta/recipes-rt/</code></a></span></dt>
72<dt><span class="section"><a href="structure-meta-recipes-sato.html">5.3.16. <code class="filename">meta/recipes-sato/</code></a></span></dt>
73<dt><span class="section"><a href="structure-meta-recipes-support.html">5.3.17. <code class="filename">meta/recipes-support/</code></a></span></dt>
74<dt><span class="section"><a href="structure-meta-site.html">5.3.18. <code class="filename">meta/site/</code></a></span></dt>
75<dt><span class="section"><a href="structure-meta-recipes-txt.html">5.3.19. <code class="filename">meta/recipes.txt</code></a></span></dt>
76</dl></dd>
77</dl>
78</div>
79<p>
80 The <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a> consists of several components.
81 Understanding them and knowing where they are located is key to using the Yocto Project well.
82 This chapter describes the Source Directory and gives information about the various
83 files and directories.
84</p>
85<p>
86 For information on how to establish a local Source Directory on your development system, see the
87 "<a class="link" href="../dev-manual/getting-setup.html" target="_self">Getting Set Up</a>"
88 section in the Yocto Project Development Manual.
89</p>
90<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
91<h3 class="title">Note</h3>
92 The OpenEmbedded build system does not support file or directory names that
93 contain spaces.
94 Be sure that the Source Directory you use does not contain these types
95 of names.
96</div>
97</div></body>
98</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 10. Variables Glossary</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="ref-features-backfill.html" title="9.4. Feature Backfilling">
10<link rel="next" href="ref-varlocality.html" title="Chapter 11. Variable Context">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 10. Variables Glossary">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="ref-variables-glos"></a>Chapter 10. Variables Glossary</h2></div></div></div>
15<div class="toc">
16<p><b>Table of Contents</b></p>
17<dl><dt><span class="glossary"><a href="ref-variables-glos.html#ref-variables-glossary">Glossary</a></span></dt></dl>
18</div>
19<p>
20 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
21 of their function and contents.
22</p>
23<div class="glossary" title="Glossary">
24<div class="titlepage"><div><div><h2 class="title">
25<a name="ref-variables-glossary"></a>Glossary</h2></div></div></div>
26<p>
27 <a class="link" href="ref-variables-glos.html#var-ALLOW_EMPTY" title="ALLOW_EMPTY">A</a>
28 <a class="link" href="ref-variables-glos.html#var-B" title="B">B</a>
29 <a class="link" href="ref-variables-glos.html#var-CFLAGS" title="CFLAGS">C</a>
30 <a class="link" href="ref-variables-glos.html#var-D" title="D">D</a>
31 <a class="link" href="ref-variables-glos.html#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">E</a>
32 <a class="link" href="ref-variables-glos.html#var-FILES" title="FILES">F</a>
33
34 <a class="link" href="ref-variables-glos.html#var-HOMEPAGE" title="HOMEPAGE">H</a>
35 <a class="link" href="ref-variables-glos.html#var-IMAGE_FEATURES" title="IMAGE_FEATURES">I</a>
36
37 <a class="link" href="ref-variables-glos.html#var-KBRANCH" title="KBRANCH">K</a>
38 <a class="link" href="ref-variables-glos.html#var-LAYERDIR" title="LAYERDIR">L</a>
39 <a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE">M</a>
40
41 <a class="link" href="ref-variables-glos.html#var-OE_TERMINAL" title="OE_TERMINAL">O</a>
42 <a class="link" href="ref-variables-glos.html#var-P" title="P">P</a>
43
44 <a class="link" href="ref-variables-glos.html#var-RCONFLICTS" title="RCONFLICTS">R</a>
45 <a class="link" href="ref-variables-glos.html#var-S" title="S">S</a>
46 <a class="link" href="ref-variables-glos.html#var-T" title="T">T</a>
47
48
49 <a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR">W</a>
50
51
52
53 </p>
54<div class="glossdiv" title="A">
55<h3 class="title">A</h3>
56<dl>
57<dt>
58<a name="var-ALLOW_EMPTY"></a>ALLOW_EMPTY</dt>
59<dd>
60<p>
61 Specifies if an output package should still be produced if it is empty.
62 By default, BitBake does not produce empty packages.
63 This default behavior can cause issues when there is an
64 <a class="link" href="ref-variables-glos.html#var-RDEPENDS" title="RDEPENDS"><code class="filename">RDEPENDS</code></a> or
65 some other runtime hard-requirement on the existence of the package.
66 </p>
67<p>
68 Like all package-controlling variables, you must always use them in
69 conjunction with a package name override.
70 Here is an example:
71 </p>
72<pre class="literallayout">
73 ALLOW_EMPTY_${PN} = "1"
74 </pre>
75<p>
76 </p>
77</dd>
78<dt>
79<a name="var-AUTHOR"></a>AUTHOR</dt>
80<dd><p>The email address used to contact the original author or authors in
81 order to send patches, forward bugs, etc.</p></dd>
82<dt>
83<a name="var-AUTOREV"></a>AUTOREV</dt>
84<dd>
85<p>When <code class="filename"><a class="link" href="ref-variables-glos.html#var-SRCREV" title="SRCREV">SRCREV</a></code>
86 is set to the value of this variable, it specifies that the latest
87 source revision in the repository should be used. Here is an example:
88 </p>
89<pre class="literallayout">
90 SRCREV = "${AUTOREV}"
91 </pre>
92<p>
93 </p>
94</dd>
95</dl>
96</div>
97<div class="glossdiv" title="B">
98<h3 class="title">B</h3>
99<dl>
100<dt>
101<a name="var-B"></a>B</dt>
102<dd>
103<p>
104 The <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.
105 The OpenEmbedded build system places generated objects into the Build Directory
106 during a recipe's build process.
107 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>
108 directory:
109 </p>
110<pre class="literallayout">
111 B = ${WORKDIR}/${BPN}-{PV}/
112 </pre>
113<p>
114 You can separate the (<code class="filename">S</code>) directory and the directory pointed to
115 by the <code class="filename">B</code> variable.
116 Most autotools-based recipes support separating these directories.
117 The build system defaults to using separate directories for <code class="filename">gcc</code>
118 and some kernel recipes.
119 </p>
120</dd>
121<dt>
122<a name="var-BAD_RECOMMENDATIONS"></a>BAD_RECOMMENDATIONS</dt>
123<dd><p>
124 A list of packages not to install despite being recommended by a recipe.
125 Support for this variable exists only when using the
126 <code class="filename">ipk</code> packaging backend.
127 </p></dd>
128<dt>
129<a name="var-BB_DISKMON_DIRS"></a>BB_DISKMON_DIRS</dt>
130<dd>
131<p>
132 Monitors disk space and available inodes during the build
133 and allows you to control the build based on these
134 parameters.
135 </p>
136<p>
137 Disk space monitoring is disabled by default.
138 To enable monitoring, add the <code class="filename">BB_DISKMON_DIRS</code>
139 variable to your <code class="filename">conf/local.conf</code> file found in the
140 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.
141 Use the following form:
142 </p>
143<pre class="literallayout">
144 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
145
146 where:
147
148 &lt;action&gt; is:
149 ABORT: Immediately abort the build when
150 a threshold is broken.
151 STOPTASKS: Stop the build after the currently
152 executing tasks have finished when
153 a threshold is broken.
154 WARN: Issue a warning but continue the
155 build when a threshold is broken.
156 Subsequent warnings are issued as
157 defined by the
158 <a class="link" href="ref-variables-glos.html#var-BB_DISKMON_WARNINTERVAL" title="BB_DISKMON_WARNINTERVAL">BB_DISKMON_WARNINTERVAL</a> variable,
159 which must be defined in the
160 conf/local.conf file.
161
162 &lt;dir&gt; is:
163 Any directory you choose. You can specify one or
164 more directories to monitor by separating the
165 groupings with a space. If two directories are
166 on the same device, only the first directory
167 is monitored.
168
169 &lt;threshold&gt; is:
170 Either the minimum available disk space,
171 the minimum number of free inodes, or
172 both. You must specify at least one. To
173 omit one or the other, simply omit the value.
174 Specify the threshold using G, M, K for Gbytes,
175 Mbytes, and Kbytes, respectively. If you do
176 not specify G, M, or K, Kbytes is assumed by
177 default. Do not use GB, MB, or KB.
178 </pre>
179<p>
180 </p>
181<p>
182 Here are some examples:
183 </p>
184<pre class="literallayout">
185 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
186 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
187 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
188 </pre>
189<p>
190 The first example works only if you also provide
191 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
192 in the <code class="filename">conf/local.conf</code>.
193 This example causes the build system to immediately
194 abort when either the disk space in <code class="filename">${TMPDIR}</code> drops
195 below 1 Gbyte or the available free inodes drops below
196 100 Kbytes.
197 Because two directories are provided with the variable, the
198 build system also issue a
199 warning when the disk space in the
200 <code class="filename">${SSTATE_DIR}</code> directory drops
201 below 1 Gbyte or the number of free inodes drops
202 below 100 Kbytes.
203 Subsequent warnings are issued during intervals as
204 defined by the <code class="filename">BB_DISKMON_WARNINTERVAL</code>
205 variable.
206 </p>
207<p>
208 The second example stops the build after all currently
209 executing tasks complete when the minimum disk space
210 in the <code class="filename">${TMPDIR}</code> directory drops
211 below 1 Gbyte.
212 No disk monitoring occurs for the free inodes in this case.
213 </p>
214<p>
215 The final example immediately aborts the build when the
216 number of free inodes in the <code class="filename">${TMPDIR}</code> directory
217 drops below 100 Kbytes.
218 No disk space monitoring for the directory itself occurs
219 in this case.
220 </p>
221</dd>
222<dt>
223<a name="var-BB_DISKMON_WARNINTERVAL"></a>BB_DISKMON_WARNINTERVAL</dt>
224<dd>
225<p>
226 Defines the disk space and free inode warning intervals.
227 To set these intervals, define the variable in your
228 <code class="filename">conf/local.conf</code> file in the
229 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.
230 </p>
231<p>
232 If you are going to use the
233 <code class="filename">BB_DISKMON_WARNINTERVAL</code> variable, you must
234 also use the
235 <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
236 and define its action as "WARN".
237 During the build, subsequent warnings are issued each time
238 disk space or number of free inodes further reduces by
239 the respective interval.
240 </p>
241<p>
242 If you do not provide a <code class="filename">BB_DISKMON_WARNINTERVAL</code>
243 variable and you do use <code class="filename">BB_DISKMON_DIRS</code> with
244 the "WARN" action, the disk monitoring interval defaults to
245 the following:
246 </p>
247<pre class="literallayout">
248 BB_DISKMON_WARNINTERVAL = "50M,5K"
249 </pre>
250<p>
251 </p>
252<p>
253 When specifying the variable in your configuration file,
254 use the following form:
255 </p>
256<pre class="literallayout">
257 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
258
259 where:
260
261 &lt;disk_space_interval&gt; is:
262 An interval of memory expressed in either
263 G, M, or K for Gbytes, Mbytes, or Kbytes,
264 respectively. You cannot use GB, MB, or KB.
265
266 &lt;disk_inode_interval&gt; is:
267 An interval of free inodes expressed in either
268 G, M, or K for Gbytes, Mbytes, or Kbytes,
269 respectively. You cannot use GB, MB, or KB.
270 </pre>
271<p>
272 </p>
273<p>
274 Here is an example:
275 </p>
276<pre class="literallayout">
277 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
278 BB_DISKMON_WARNINTERVAL = "50M,5K"
279 </pre>
280<p>
281 These variables cause the OpenEmbedded build system to
282 issue subsequent warnings each time the available
283 disk space further reduces by 50 Mbytes or the number
284 of free inodes further reduces by 5 Kbytes in the
285 <code class="filename">${SSTATE_DIR}</code> directory.
286 Subsequent warnings based on the interval occur each time
287 a respective interval is reached beyond the intial warning
288 (i.e. 1 Gbytes and 100 Kbytes).
289 </p>
290</dd>
291<dt>
292<a name="var-BBCLASSEXTEND"></a>BBCLASSEXTEND</dt>
293<dd>
294<p>
295 Allows you to extend a recipe so that it builds variants of the software.
296 Common variants for recipes exist such as "natives" like <code class="filename">quilt-native</code>,
297 which is a copy of quilt built to run on the build system;
298 "crosses" such as <code class="filename">gcc-cross</code>,
299 which is a compiler built to run on the build machine but produces binaries
300 that run on the target <a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a>;
301 "nativesdk", which targets the SDK machine instead of <code class="filename">MACHINE</code>;
302 and "mulitlibs" in the form "<code class="filename">multilib:&lt;multilib_name&gt;</code>".
303 </p>
304<p>
305 To build a different variant of the recipe with a minimal amount of code, it usually
306 is as simple as adding the following to your recipe:
307 </p>
308<pre class="literallayout">
309 BBCLASSEXTEND =+ "native nativesdk"
310 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
311 </pre>
312<p>
313 </p>
314</dd>
315<dt>
316<a name="var-BBMASK"></a>BBMASK</dt>
317<dd>
318<p>Prevents BitBake from processing recipes and recipe append files.
319 You can use the <code class="filename">BBMASK</code> variable to "hide"
320 these <code class="filename">.bb</code> and <code class="filename">.bbappend</code> files.
321 BitBake ignores any recipe or recipe append files that match the expression.
322 It is as if BitBake does not see them at all.
323 Consequently, matching files are not parsed or otherwise used by
324 BitBake.</p>
325<p>The value you provide is passed to python's regular expression compiler.
326 For complete syntax information, see python's documentation at
327 <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>.
328 The expression is compared against the full paths to the files.
329 For example, the following uses a complete regular expression to tell
330 BitBake to ignore all recipe and recipe append files in the
331 <code class="filename">.*/meta-ti/recipes-misc/</code> directory:
332 </p>
333<pre class="literallayout">
334 BBMASK = ".*/meta-ti/recipes-misc/"
335 </pre>
336<p>Use the <code class="filename">BBMASK</code> variable from within the
337 <code class="filename">conf/local.conf</code> file found
338 in the <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.</p>
339</dd>
340<dt>
341<a name="var-BB_NUMBER_THREADS"></a>BB_NUMBER_THREADS</dt>
342<dd><p>The maximum number of tasks BitBake should run in parallel at any one time.
343 If your host development system supports multiple cores a good rule of thumb
344 is to set this variable to twice the number of cores.</p></dd>
345<dt>
346<a name="var-BBFILE_COLLECTIONS"></a>BBFILE_COLLECTIONS</dt>
347<dd><p>Lists the names of configured layers.
348 These names are used to find the other <code class="filename">BBFILE_*</code>
349 variables.
350 Typically, each layer will append its name to this variable in its
351 <code class="filename">conf/layer.conf</code> file.
352 </p></dd>
353<dt>
354<a name="var-BBFILE_PATTERN"></a>BBFILE_PATTERN</dt>
355<dd><p>Variable that expands to match files from <code class="filename">BBFILES</code> in a particular layer.
356 This variable is used in the <code class="filename">conf/layer.conf</code> file and must
357 be suffixed with the name of the specific layer (e.g.
358 <code class="filename">BBFILE_PATTERN_emenlow</code>).</p></dd>
359<dt>
360<a name="var-BBFILE_PRIORITY"></a>BBFILE_PRIORITY</dt>
361<dd>
362<p>Assigns the priority for recipe files in each layer.</p>
363<p>This variable is useful in situations where the same recipe appears in
364 more than one layer.
365 Setting this variable allows you to prioritize a
366 layer against other layers that contain the same recipe - effectively
367 letting you control the precedence for the multiple layers.
368 The precedence established through this variable stands regardless of a
369 recipe's version (<code class="filename">PV</code> variable).
370 For example, a layer that has a recipe with a higher <code class="filename">PV</code> value but for
371 which the <code class="filename">BBFILE_PRIORITY</code> is set to have a lower precedence still has a
372 lower precedence.</p>
373<p>A larger value for the <code class="filename">BBFILE_PRIORITY</code> variable results in a higher
374 precedence.
375 For example, the value 6 has a higher precedence than the value 5.
376 If not specified, the <code class="filename">BBFILE_PRIORITY</code> variable is set based on layer
377 dependencies (see the
378 <code class="filename"><a class="link" href="ref-variables-glos.html#var-LAYERDEPENDS" title="LAYERDEPENDS">LAYERDEPENDS</a></code> variable for
379 more information.
380 The default priority, if unspecified
381 for a layer with no dependencies, is the lowest defined priority + 1
382 (or 1 if no priorities are defined).</p>
383<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;">
384<h3 class="title">Tip</h3>
385 You can use the command <code class="filename">bitbake-layers show_layers</code> to list
386 all configured layers along with their priorities.
387 </div>
388</dd>
389<dt>
390<a name="var-BBFILES"></a>BBFILES</dt>
391<dd><p>List of recipe files used by BitBake to build software</p></dd>
392<dt>
393<a name="var-BBPATH"></a>BBPATH</dt>
394<dd><p>Used by BitBake to locate <code class="filename">.bbclass</code> and configuration files.
395 This variable is analogous to the <code class="filename">PATH</code> variable.</p></dd>
396<dt>
397<a name="var-BBINCLUDELOGS"></a>BBINCLUDELOGS</dt>
398<dd><p>Variable that controls how BitBake displays logs on build failure.</p></dd>
399<dt>
400<a name="var-BBLAYERS"></a>BBLAYERS</dt>
401<dd>
402<p>Lists the layers to enable during the build.
403 This variable is defined in the <code class="filename">bblayers.conf</code> configuration
404 file in the <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.
405 Here is an example:
406 </p>
407<pre class="literallayout">
408 BBLAYERS = " \
409 /home/scottrif/poky/meta \
410 /home/scottrif/poky/meta-yocto \
411 /home/scottrif/poky/meta-yocto-bsp \
412 /home/scottrif/poky/meta-mykernel \
413 "
414 </pre>
415<p>
416 This example enables four layers, one of which is a custom, user-defined layer
417 named <code class="filename">meta-mykernel</code>.
418 </p>
419</dd>
420<dt>
421<a name="var-BP"></a>BP</dt>
422<dd>
423<p>The base recipe name and version but without any special
424 recipe name suffix (i.e. <code class="filename">-native</code>, <code class="filename">lib64-</code>,
425 and so forth).
426 <code class="filename">BP</code> is comprised of the following:
427 </p>
428<pre class="literallayout">
429 ${BPN}-${PV}
430 </pre>
431</dd>
432<dt>
433<a name="var-BPN"></a>BPN</dt>
434<dd><p>The bare name of the recipe.
435 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
436 but removes common suffixes such as "-native" and "-cross" as well
437 as removes common prefixes such as multilib's "lib64-" and "lib32-".
438 The exact list of suffixes removed is specified by the
439 <a class="link" href="ref-variables-glos.html#var-SPECIAL_PKGSUFFIX" title="SPECIAL_PKGSUFFIX"><code class="filename">SPECIAL_PKGSUFFIX</code></a> variable.
440 The exact list of prefixes removed is specified by the
441 <a class="link" href="ref-variables-glos.html#var-MLPREFIX" title="MLPREFIX"><code class="filename">MLPREFIX</code></a> variable.
442 Prefixes are removed for multilib and nativesdk cases.</p></dd>
443</dl>
444</div>
445<div class="glossdiv" title="C">
446<h3 class="title">C</h3>
447<dl>
448<dt>
449<a name="var-CFLAGS"></a>CFLAGS</dt>
450<dd><p>
451 Flags passed to C compiler for the target system.
452 This variable evaluates to the same as
453 <code class="filename"><a class="link" href="ref-variables-glos.html#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>.
454 </p></dd>
455<dt>
456<a name="var-COMBINED_FEATURES"></a>COMBINED_FEATURES</dt>
457<dd><p>A set of features common between
458 <a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a>
459 and <a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>.
460 See the glossary descriptions for these variables for more information.</p></dd>
461<dt>
462<a name="var-COMPATIBLE_MACHINE"></a>COMPATIBLE_MACHINE</dt>
463<dd><p>A regular expression which evaluates to match the machines the recipe
464 works with.
465 It stops recipes being run on machines for which they are not compatible.
466 This is particularly useful with kernels.
467 It also helps to increase parsing speed as further parsing of the recipe is skipped
468 if it is found the current machine is not compatible.</p></dd>
469<dt>
470<a name="var-CONFFILES"></a>CONFFILES</dt>
471<dd>
472<p>
473 Identifies editable or configurable files that are part of a package.
474 If the Package Management System (PMS) is being used to update
475 packages on the target system, it is possible that
476 configuration files you have changed after the original installation
477 and that you now want to remain unchanged are overwritten.
478 In other words, editable files might exist in the package that you do not
479 want reset as part of the package update process.
480 You can use the <code class="filename">CONFFILES</code> variable to list the files in the
481 package that you wish to prevent the PMS from overwriting during this update process.
482 </p>
483<p>
484 To use the <code class="filename">CONFFILES</code> variable, provide a package name
485 override that identifies the resulting package.
486 Then, provide a space-separated list of files.
487 Here is an example:
488 </p>
489<pre class="literallayout">
490 CONFFILES_${PN} += "${sysconfdir}/file1 \
491 ${sysconfdir}/file2 ${sysconfdir}/file3"
492 </pre>
493<p>
494 </p>
495<p>
496 A relationship exists between the <code class="filename">CONFFILES</code> and
497 <code class="filename"><a class="link" href="ref-variables-glos.html#var-FILES" title="FILES">FILES</a></code> variables.
498 The files listed within <code class="filename">CONFFILES</code> must be a subset of
499 the files listed within <code class="filename">FILES</code>.
500 Because the configuration files you provide with <code class="filename">CONFFILES</code>
501 are simply being identified so that the PMS will not overwrite them,
502 it makes sense that
503 the files must already be included as part of the package through the
504 <code class="filename">FILES</code> variable.
505 </p>
506<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
507<h3 class="title">Note</h3>
508 When specifying paths as part of the <code class="filename">CONFFILES</code> variable,
509 it is good practice to use appropriate path variables.
510 For example, <code class="filename">${sysconfdir}</code> rather than
511 <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather
512 than <code class="filename">/usr/bin</code>.
513 You can find a list of these variables at the top of the
514 <code class="filename">/meta/conf/bitbake.conf</code> file in the
515 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
516 </div>
517</dd>
518<dt>
519<a name="var-CONFIG_SITE"></a>CONFIG_SITE</dt>
520<dd><p>
521 A list of files that contains <code class="filename">autoconf</code> test results relevant
522 to the current build.
523 This variable is used by the Autotools utilities when running
524 <code class="filename">configure</code>.
525 </p></dd>
526<dt>
527<a name="var-CORE_IMAGE_EXTRA_INSTALL"></a>CORE_IMAGE_EXTRA_INSTALL</dt>
528<dd>
529<p>
530 Specifies the list of packages to be added to the image.
531 This variable should only be set in the <code class="filename">local.conf</code>
532 configuration file found in the
533 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.
534 </p>
535<p>
536 This variable replaces <code class="filename">POKY_EXTRA_INSTALL</code>, which is no longer supported.
537 </p>
538</dd>
539</dl>
540</div>
541<div class="glossdiv" title="D">
542<h3 class="title">D</h3>
543<dl>
544<dt>
545<a name="var-D"></a>D</dt>
546<dd><p>The destination directory.</p></dd>
547<dt>
548<a name="var-DEBUG_BUILD"></a>DEBUG_BUILD</dt>
549<dd><p>
550 Specifies to build packages with debugging information.
551 This influences the value of the
552 <code class="filename"><a class="link" href="ref-variables-glos.html#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION</a></code>
553 variable.
554 </p></dd>
555<dt>
556<a name="var-DEBUG_OPTIMIZATION"></a>DEBUG_OPTIMIZATION</dt>
557<dd><p>
558 The options to pass in
559 <code class="filename"><a class="link" href="ref-variables-glos.html#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>
560 and <code class="filename"><a class="link" href="ref-variables-glos.html#var-CFLAGS" title="CFLAGS">CFLAGS</a></code> when compiling
561 a system for debugging.
562 This variable defaults to "-O -fno-omit-frame-pointer -g".
563 </p></dd>
564<dt>
565<a name="var-DEFAULT_PREFERENCE"></a>DEFAULT_PREFERENCE</dt>
566<dd><p>Specifies the priority of recipes.</p></dd>
567<dt>
568<a name="var-DEPENDS"></a>DEPENDS</dt>
569<dd><p>
570 Lists a recipe's build-time dependencies
571 (i.e. other recipe files).
572 The system ensures that all the dependencies listed
573 have been built and have their contents in the appropriate
574 sysroots before the recipe's configure task is executed.
575 </p></dd>
576<dt>
577<a name="var-DESCRIPTION"></a>DESCRIPTION</dt>
578<dd><p>The package description used by package managers.
579 If not set, <code class="filename">DESCRIPTION</code> takes
580 the value of the
581 <a class="link" href="ref-variables-glos.html#var-SUMMARY" title="SUMMARY"><code class="filename">SUMMARY</code></a>
582 variable.
583 </p></dd>
584<dt>
585<a name="var-DESTDIR"></a>DESTDIR</dt>
586<dd><p>the destination directory.</p></dd>
587<dt>
588<a name="var-DISTRO"></a>DISTRO</dt>
589<dd>
590<p>
591 The short name of the distribution.
592 This variable corresponds to a file with the
593 extension <code class="filename">.conf</code>
594 located in a <code class="filename">conf/distro</code> directory
595 within the metadata that contains the distribution configuration.
596 The
597 value must not contain spaces, and is typically all lower-case.
598 </p>
599<p>
600 If the variable is blank, a set of default configuration
601 will be used, which is specified
602 within <code class="filename">meta/conf/distro/defaultsetup.conf</code>.
603 </p>
604</dd>
605<dt>
606<a name="var-DISTRO_EXTRA_RDEPENDS"></a>DISTRO_EXTRA_RDEPENDS</dt>
607<dd><p>
608 Specifies a list of distro-specific packages to add to all images.
609 This variable takes affect through
610 <code class="filename">packagegroup-base</code> so the
611 variable only really applies to the more full-featured
612 images that include <code class="filename">packagegroup-base</code>.
613 You can use this variable to keep distro policy out of
614 generic images.
615 As with all other distro variables, you set this variable
616 in the distro <code class="filename">.conf</code> file.
617 </p></dd>
618<dt>
619<a name="var-DISTRO_EXTRA_RRECOMMENDS"></a>DISTRO_EXTRA_RRECOMMENDS</dt>
620<dd><p>
621 Specifies a list of distro-specific packages to add to all images
622 if the packages exist.
623 The packages might not exist or be empty (e.g. kernel modules).
624 The list of packages are automatically installed but can be
625 removed by the user.
626 </p></dd>
627<dt>
628<a name="var-DISTRO_FEATURES"></a>DISTRO_FEATURES</dt>
629<dd><p>The features enabled for the distribution.
630 For a list of features supported by the Yocto Project as shipped,
631 see the "<a class="link" href="ref-features-distro.html" title="9.1. Distro">Distro</a>"
632 section.
633 </p></dd>
634<dt>
635<a name="var-DISTRO_FEATURES_BACKFILL"></a>DISTRO_FEATURES_BACKFILL</dt>
636<dd>
637<p>Features to be added to
638 <code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>
639 if not also present in
640 <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>.
641 </p>
642<p>
643 This variable is set in the <code class="filename">meta/conf/bitbake.conf</code> file.
644 It is not intended to be user-configurable.
645 It is best to just reference the variable to see which distro features are
646 being backfilled for all distro configurations.
647 See the <a class="link" href="ref-features-backfill.html" title="9.4. Feature Backfilling">Feature backfilling</a> section for
648 more information.
649 </p>
650</dd>
651<dt>
652<a name="var-DISTRO_FEATURES_BACKFILL_CONSIDERED"></a>DISTRO_FEATURES_BACKFILL_CONSIDERED</dt>
653<dd><p>Features from
654 <code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES_BACKFILL" title="DISTRO_FEATURES_BACKFILL">DISTRO_FEATURES_BACKFILL</a></code>
655 that should not backfilled (i.e. added to
656 <code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>)
657 during the build.
658 See the "<a class="link" href="ref-features-backfill.html" title="9.4. Feature Backfilling">Feature Backfilling</a>" section for
659 more information.
660 </p></dd>
661<dt>
662<a name="var-DISTRO_NAME"></a>DISTRO_NAME</dt>
663<dd><p>The long name of the distribution.</p></dd>
664<dt>
665<a name="var-DISTRO_PN_ALIAS"></a>DISTRO_PN_ALIAS</dt>
666<dd>
667<p>Alias names used for the recipe in various Linux distributions.</p>
668<p>See the
669 "<a class="link" href="../dev-manual/usingpoky-configuring-DISTRO_PN_ALIAS.html" target="_self">Handling
670 a Package Name Alias</a>" section in the Yocto Project Development
671 Manual for more information.</p>
672</dd>
673<dt>
674<a name="var-DISTRO_VERSION"></a>DISTRO_VERSION</dt>
675<dd><p>the version of the distribution.</p></dd>
676<dt>
677<a name="var-DL_DIR"></a>DL_DIR</dt>
678<dd>
679<p>
680 The central download directory used by the build process to store downloads.
681 You can set this directory by defining the <code class="filename">DL_DIR</code>
682 variable in the <code class="filename">/conf/local.conf</code> file.
683 This directory is self-maintaining and you should not have
684 to touch it.
685 By default, the directory is <code class="filename">downloads</code> in the
686 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.
687 </p>
688<pre class="literallayout">
689 #DL_DIR ?= "${TOPDIR}/downloads"
690 </pre>
691<p>
692 To specify a different download directory, simply uncomment the line
693 and provide your directory.
694 </p>
695<p>
696 During a first build, the system downloads many different source code
697 tarballs from various upstream projects.
698 Downloading can take a while, particularly if your network
699 connection is slow.
700 Tarballs are all stored in the directory defined by
701 <code class="filename">DL_DIR</code> and the build system looks there first
702 to find source tarballs.
703 </p>
704<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
705<h3 class="title">Note</h3>
706 When wiping and rebuilding, you can preserve this directory to speed
707 up this part of subsequent builds.
708 </div>
709<p>
710 </p>
711<p>
712 You can safely share this directory between multiple builds on the
713 same development machine.
714 For additional information on how the build process gets source files
715 when working behind a firewall or proxy server, see the
716 "<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>"
717 chapter.
718 </p>
719</dd>
720</dl>
721</div>
722<div class="glossdiv" title="E">
723<h3 class="title">E</h3>
724<dl>
725<dt>
726<a name="var-ENABLE_BINARY_LOCALE_GENERATION"></a>ENABLE_BINARY_LOCALE_GENERATION</dt>
727<dd>
728<p></p>
729<p>Variable that controls which locales for <code class="filename">eglibc</code> are
730 to be generated during the build (useful if the target device has 64Mbytes
731 of RAM or less).</p>
732</dd>
733<dt>
734<a name="var-EXTENDPE"></a>EXTENDPE</dt>
735<dd>
736<p>
737 Used with file and pathnames to create a prefix for a recipe's
738 version based on the recipe's
739 <a class="link" href="ref-variables-glos.html#var-PE" title="PE"><code class="filename">PE</code></a> value.
740 If <code class="filename">PE</code> is set and greater than zero for a recipe,
741 <code class="filename">EXTENDPE</code> becomes that value (e.g if
742 <code class="filename">PE</code> is equal to "1" then <code class="filename">EXTENDPE</code>
743 becomes "1_").
744 If a recipe's <code class="filename">PE</code> is not set (the default) or is equal to
745 zero, <code class="filename">EXTENDPE</code> becomes "".</p>
746<p>See the <a class="link" href="ref-variables-glos.html#var-STAMP" title="STAMP"><code class="filename">STAMP</code></a>
747 variable for an example.
748 </p>
749</dd>
750<dt>
751<a name="var-EXTRA_IMAGE_FEATURES"></a>EXTRA_IMAGE_FEATURES</dt>
752<dd>
753<p>Allows extra packages to be added to the generated images.
754 You set this variable in the <code class="filename">local.conf</code>
755 configuration file.
756 Note that some image features are also added using the
757 <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code>
758 variable generally configured in image recipes.
759 You can use this variable to add more features in addition to those.
760 Here are some examples of features you can add:</p>
761<pre class="literallayout">
762"dbg-pkgs" - Adds -dbg packages for all installed packages
763 including symbol information for debugging and
764 profiling.
765
766"dev-pkgs" - Adds -dev packages for all installed packages.
767 This is useful if you want to develop against
768 the libraries in the image.
769
770"tools-sdk" - Adds development tools such as gcc, make,
771 pkgconfig and so forth.
772
773"tools-debug" - Adds debugging tools such as gdb and
774 strace.
775
776"tools-profile" - Adds profiling tools such as oprofile,
777 exmap, lttng and valgrind (x86 only).
778
779"tools-testapps" - Adds useful testing tools such as
780 ts_print, aplay, arecord and so
781 forth.
782
783"debug-tweaks" - Makes an image suitable for development.
784 For example, ssh root access has a blank
785 password. You should remove this feature
786 before you produce a production image.
787 </pre>
788<p>There are other valid features too, see the
789 <a class="link" href="ref-features-image.html" title="9.3. Images">Images</a>
790 section for more details.</p>
791</dd>
792<dt>
793<a name="var-EXTRA_IMAGEDEPENDS"></a>EXTRA_IMAGEDEPENDS</dt>
794<dd>
795<p>A list of recipes to be built that do not provide packages to be installed in
796 the root filesystem.
797 </p>
798<p>Sometimes a recipe is required to build the final image but is not
799 needed in the root filesystem.
800 You can use the <code class="filename">EXTRA_IMAGEDEPENDS</code> variable to
801 list these recipes and thus, specify the dependencies.
802 A typical example is a required bootloader in a machine configuration.
803 </p>
804<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
805<h3 class="title">Note</h3>
806 To add packages to the root filesystem, see the various
807 <code class="filename">*DEPENDS</code> and <code class="filename">*RECOMMENDS</code>
808 variables.
809 </div>
810</dd>
811<dt>
812<a name="var-EXTRA_OECMAKE"></a>EXTRA_OECMAKE</dt>
813<dd><p>Additional <code class="filename">cmake</code> options.</p></dd>
814<dt>
815<a name="var-EXTRA_OECONF"></a>EXTRA_OECONF</dt>
816<dd><p>Additional <code class="filename">configure</code> script options.</p></dd>
817<dt>
818<a name="var-EXTRA_OEMAKE"></a>EXTRA_OEMAKE</dt>
819<dd><p>Additional GNU <code class="filename">make</code> options.</p></dd>
820</dl>
821</div>
822<div class="glossdiv" title="F">
823<h3 class="title">F</h3>
824<dl>
825<dt>
826<a name="var-FILES"></a>FILES</dt>
827<dd>
828<p>
829 The list of directories or files that are placed in packages.
830 </p>
831<p>
832 To use the <code class="filename">FILES</code> variable, provide a package name
833 override that identifies the resulting package.
834 Then, provide a space-separated list of files or paths that identifies the
835 files you want included as part of the resulting package.
836 Here is an example:
837 </p>
838<pre class="literallayout">
839 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
840 </pre>
841<p>
842 </p>
843<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
844<h3 class="title">Note</h3>
845 When specifying paths as part of the <code class="filename">FILES</code> variable,
846 it is good practice to use appropriate path variables.
847 For example, <code class="filename">${sysconfdir}</code> rather than
848 <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather
849 than <code class="filename">/usr/bin</code>.
850 You can find a list of these variables at the top of the
851 <code class="filename">/meta/conf/bitbake.conf</code> file in the
852 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
853 </div>
854<p>
855 If some of the files you provide with the <code class="filename">FILES</code> variable
856 are editable and you know they should not be
857 overwritten during the package update process by the Package Management
858 System (PMS), you can identify these files so that the PMS will not
859 overwrite them.
860 See the <code class="filename"><a class="link" href="ref-variables-glos.html#var-CONFFILES" title="CONFFILES">CONFFILES</a></code>
861 variable for information on how to identify these files to the PMS.
862 </p>
863</dd>
864<dt>
865<a name="var-FILESEXTRAPATHS"></a>FILESEXTRAPATHS</dt>
866<dd>
867<p>
868 Extends the search path the OpenEmbedded build system uses when
869 looking for files and patches as it processes recipes.
870 The directories BitBake uses when it processes recipes is defined by the
871 <a class="link" href="ref-variables-glos.html#var-FILESPATH" title="FILESPATH"><code class="filename">FILESPATH</code></a> variable.
872 You can add directories to the search path by defining the
873 <code class="filename">FILESEXTRAPATHS</code> variable.
874 </p>
875<p>
876 To add paths to the search order, provide a list of directories and separate
877 each path using a colon character as follows:
878 </p>
879<pre class="literallayout">
880 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
881 </pre>
882<p>
883 Typically, you want your directories search first.
884 To make sure that happens, use <code class="filename">_prepend</code> and
885 the immediate expansion (<code class="filename">:=</code>) operator as shown in the
886 previous example.
887 Finally, to maintain the integrity of the <code class="filename">FILESPATH</code> variable,
888 you must include the appropriate beginning or ending (as needed) colon character.
889 </p>
890<p>
891 The <code class="filename">FILESEXTRAPATHS</code> variable is intended for use in
892 <code class="filename">.bbappend</code> files to include any additional files provided in that layer.
893 You typically accomplish this with the following:
894 </p>
895<pre class="literallayout">
896 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
897 </pre>
898<p>
899 </p>
900</dd>
901<dt>
902<a name="var-FILESPATH"></a>FILESPATH</dt>
903<dd>
904<p>
905 The default set of directories the OpenEmbedded build system uses
906 when searching for patches and files.
907 During the build process, BitBake searches each directory in
908 <code class="filename">FILESPATH</code> in the specified order when looking for
909 files and patches specified by each <code class="filename">file://</code> URI in a recipe.
910 </p>
911<p>
912 The default value for the <code class="filename">FILESPATH</code> variable is defined
913 in the <code class="filename">base.bbclass</code> class found in
914 <code class="filename">meta/classes</code> in the
915 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>:
916 </p>
917<pre class="literallayout">
918FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
919 "${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \
920 "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \
921 "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}"
922 </pre>
923<p>
924 Do not hand-edit the <code class="filename">FILESPATH</code> variable.
925 If you want to extend the set of pathnames that BitBake uses when searching for
926 files and patches, use the
927 <a class="link" href="ref-variables-glos.html#var-FILESEXTRAPATHS" title="FILESEXTRAPATHS"><code class="filename">FILESEXTRAPATHS</code></a> variable.
928 </p>
929</dd>
930<dt>
931<a name="var-FILESYSTEM_PERMS_TABLES"></a>FILESYSTEM_PERMS_TABLES</dt>
932<dd>
933<p>Allows you to define your own file permissions settings table as part of
934 your configuration for the packaging process.
935 For example, suppose you need a consistent set of custom permissions for
936 a set of groups and users across an entire work project.
937 It is best to do this in the packages themselves but this is not always
938 possible.
939 </p>
940<p>
941 By default, the OpenEmbedded build system uses the <code class="filename">fs-perms.txt</code>, which
942 is located in the <code class="filename">meta/files</code> folder in the
943 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
944 If you create your own file permissions setting table, you should place it in your
945 layer or the distros layer.
946 </p>
947<p>
948 You define the <code class="filename">FILESYSTEM_PERMS_TABLES</code> variable in the
949 <code class="filename">conf/local.conf</code> file, which is found in the
950 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>, to
951 point to your custom <code class="filename">fs-perms.txt</code>.
952 You can specify more than a single file permissions setting table.
953 The paths you specify to these files must be defined within the
954 <code class="filename">BBPATH</code> variable.
955 </p>
956<p>
957 For guidance on how to create your own file permissions settings table file,
958 examine the existing <code class="filename">fs-perms.txt</code>.
959 </p>
960</dd>
961<dt>
962<a name="var-FULL_OPTIMIZATION"></a>FULL_OPTIMIZATION</dt>
963<dd><p>
964 The options to pass in
965 <code class="filename"><a class="link" href="ref-variables-glos.html#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>
966 and <code class="filename"><a class="link" href="ref-variables-glos.html#var-CFLAGS" title="CFLAGS">CFLAGS</a></code>
967 when compiling an optimized system.
968 This variable defaults to
969 "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
970 </p></dd>
971</dl>
972</div>
973<div class="glossdiv" title="H">
974<h3 class="title">H</h3>
975<dl>
976<dt>
977<a name="var-HOMEPAGE"></a>HOMEPAGE</dt>
978<dd><p>Website where more information about the software the recipe is building
979 can be found.</p></dd>
980</dl>
981</div>
982<div class="glossdiv" title="I">
983<h3 class="title">I</h3>
984<dl>
985<dt>
986<a name="var-IMAGE_FEATURES"></a>IMAGE_FEATURES</dt>
987<dd><p>The list of features to include in an image.
988 Typically, you configure this variable in an image recipe.
989 Note that you can also add extra features to the image by using the
990 <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.
991 See the "<a class="link" href="ref-features-image.html" title="9.3. Images">Images</a>" section for the
992 full list of features that can be included in images built by the
993 OpenEmbedded build system.</p></dd>
994<dt>
995<a name="var-IMAGE_FSTYPES"></a>IMAGE_FSTYPES</dt>
996<dd><p>Formats of root filesystem images that you want to have created.</p></dd>
997<dt>
998<a name="var-IMAGE_INSTALL"></a>IMAGE_INSTALL</dt>
999<dd>
1000<p>
1001 Specifies the packages to install into an image.
1002 The <code class="filename">IMAGE_INSTALL</code> variable is a mechanism for an image
1003 recipe and you should use it with care to avoid ordering issues.
1004 </p>
1005<p>
1006 Image recipes set <code class="filename">IMAGE_INSTALL</code> to specify the
1007 packages to install into an image through <code class="filename">image.bbclass</code>.
1008 Additionally, "helper" classes exist, such as <code class="filename">core-image.bbclass</code>,
1009 that can take
1010 <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> lists
1011 and turn these into auto-generated entries in
1012 <code class="filename">IMAGE_INSTALL</code> in addition to its default contents.
1013 </p>
1014<p>
1015 Using <code class="filename">IMAGE_INSTALL</code> with the <code class="filename">+=</code>
1016 operator from the <code class="filename">/conf/local.conf</code> file or from within
1017 an image recipe is not recommended as it can cause ordering issues.
1018 Since <code class="filename">core-image.bbclass</code> sets <code class="filename">IMAGE_INSTALL</code>
1019 to a default value using the <code class="filename">?=</code> operator, using a
1020 <code class="filename">+=</code> operation against <code class="filename">IMAGE_INSTALL</code>
1021 will result in unexpected behavior when used in
1022 <code class="filename">/conf/local.conf</code>.
1023 Furthermore, the same operation from with an image recipe may or may not
1024 succeed depending on the specific situation.
1025 In both these cases, the behavior is contrary to how most users expect
1026 the <code class="filename">+=</code> operator to work.
1027 </p>
1028<p>
1029 When you use this variable, it is best to use it as follows:
1030 </p>
1031<pre class="literallayout">
1032 IMAGE_INSTALL_append = " package-name"
1033 </pre>
1034<p>
1035 Be sure to include the space between the quotation character and the start of the
1036 package name.
1037 </p>
1038</dd>
1039<dt>
1040<a name="var-IMAGE_OVERHEAD_FACTOR"></a>IMAGE_OVERHEAD_FACTOR</dt>
1041<dd>
1042<p>
1043 Defines a multiplier that the build system applies to the initial image
1044 size for cases when the multiplier times the returned disk usage value
1045 for the image is greater than the sum of
1046 <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code>
1047 and
1048 <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>.
1049 The result of the multiplier applied to the initial image size creates
1050 free disk space in the image as overhead.
1051 By default, the build process uses a multiplier of 1.3 for this variable.
1052 This default value results in 30% free disk space added to the image when this
1053 method is used to determine the final generated image size.
1054 You should be aware that post install scripts and the package management
1055 system uses disk space inside this overhead area.
1056 Consequently, the multiplier does not produce an image with
1057 all the theoretical free disk space.
1058 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>
1059 for information on how the build system determines the overall image size.
1060 </p>
1061<p>
1062 The default 30% free disk space typically gives the image enough room to boot
1063 and allows for basic post installs while still leaving a small amount of
1064 free disk space.
1065 If 30% free space is inadequate, you can increase the default value.
1066 For example, the following setting gives you 50% free space added to the image:
1067 </p>
1068<pre class="literallayout">
1069 IMAGE_OVERHEAD_FACTOR = "1.5"
1070 </pre>
1071<p>
1072 </p>
1073<p>
1074 Alternatively, you can ensure a specific amount of free disk space is added
1075 to the image by using
1076 <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>
1077 the variable.
1078 </p>
1079</dd>
1080<dt>
1081<a name="var-IMAGE_ROOTFS_EXTRA_SPACE"></a>IMAGE_ROOTFS_EXTRA_SPACE</dt>
1082<dd>
1083<p>
1084 Defines additional free disk space created in the image in Kbytes.
1085 By default, this variable is set to "0".
1086 This free disk space is added to the image after the build system determines
1087 the image size as described in
1088 <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code>.
1089 </p>
1090<p>
1091 This variable is particularly useful when you want to ensure that a
1092 specific amount of free disk space is available on a device after an image
1093 is installed and running.
1094 For example, to be sure 5 Gbytes of free disk space is available, set the
1095 variable as follows:
1096 </p>
1097<pre class="literallayout">
1098 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
1099 </pre>
1100<p>
1101 </p>
1102</dd>
1103<dt>
1104<a name="var-IMAGE_ROOTFS_SIZE"></a>IMAGE_ROOTFS_SIZE</dt>
1105<dd>
1106<p>
1107 Defines the size in Kbytes for the generated image.
1108 The OpenEmbedded build system determines the final size for the generated
1109 image using an algorithm that takes into account the initial disk space used
1110 for the generated image, a requested size for the image, and requested
1111 additional free disk space to be added to the image.
1112 Programatically, the build system determines the final size of the
1113 generated image as follows:
1114 </p>
1115<pre class="literallayout">
1116 if (image-du * overhead) &lt; rootfs-size:
1117 internal-rootfs-size = rootfs-size + xspace
1118 else:
1119 internal-rootfs-size = (image-du * overhead) + xspace
1120
1121 where:
1122
1123 image-du = Returned value of the du command on
1124 the image.
1125
1126 overhead = IMAGE_OVERHEAD_FACTOR
1127
1128 rootfs-size = IMAGE_ROOTFS_SIZE
1129
1130 internal-rootfs-size = Initial root filesystem
1131 size before any modifications.
1132
1133 xspace = IMAGE_ROOTFS_EXTRA_SPACE
1134 </pre>
1135<p>
1136
1137 </p>
1138</dd>
1139<dt>
1140<a name="var-INC_PR"></a>INC_PR</dt>
1141<dd>
1142<p>Helps define the recipe revision for recipes that share
1143 a common <code class="filename">include</code> file.
1144 You can think of this variable as part of the recipe revision
1145 as set from within an include file.</p>
1146<p>Suppose, for example, you have a set of recipes that
1147 are used across several projects.
1148 And, within each of those recipes the revision
1149 (its <code class="filename">PR</code> value) is set accordingly.
1150 In this case, when the revision of those recipes changes
1151 the burden is on you to find all those recipes and
1152 be sure that they get changed to reflect the updated
1153 version of the recipe.
1154 In this scenario, it can get complicated when recipes
1155 used in many places and that provide common functionality
1156 are upgraded to a new revision.</p>
1157<p>A more efficient way of dealing with this situation is
1158 to set the <code class="filename">INC_PR</code> variable inside
1159 the <code class="filename">include</code> files that the recipes
1160 share and then expand the <code class="filename">INC_PR</code>
1161 variable within the recipes to help
1162 define the recipe revision.
1163 </p>
1164<p>
1165 The following provides an example that shows how to use
1166 the <code class="filename">INC_PR</code> variable
1167 given a common <code class="filename">include</code> file that
1168 defines the variable.
1169 Once the variable is defined in the
1170 <code class="filename">include</code> file, you can use the
1171 variable to set the <code class="filename">PR</code> values in
1172 each recipe.
1173 You will notice that when you set a recipe's
1174 <code class="filename">PR</code> you can provide more granular
1175 revisioning by appending values to the
1176 <code class="filename">INC_PR</code> variable:
1177 </p>
1178<pre class="literallayout">
1179recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
1180recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
1181recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
1182recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1183 </pre>
1184<p>
1185 The first line of the example establishes the baseline
1186 revision to be used for all recipes that use the
1187 <code class="filename">include</code> file.
1188 The remaining lines in the example are from individual
1189 recipes and show how the <code class="filename">PR</code> value
1190 is set.</p>
1191</dd>
1192<dt>
1193<a name="var-INHIBIT_PACKAGE_STRIP"></a>INHIBIT_PACKAGE_STRIP</dt>
1194<dd><p>
1195 Causes the build to not strip binaries in resulting packages.
1196 </p></dd>
1197<dt>
1198<a name="var-INHERIT"></a>INHERIT</dt>
1199<dd><p>
1200 Causes the named class to be inherited at
1201 this point during parsing.
1202 The variable is only valid in configuration files.
1203 </p></dd>
1204<dt>
1205<a name="var-INITSCRIPT_PACKAGES"></a>INITSCRIPT_PACKAGES</dt>
1206<dd>
1207<p>
1208 A list of the packages that contain initscripts.
1209 If multiple packages are specified, you need to append the package name
1210 to the other <code class="filename">INITSCRIPT_*</code> as an override.</p>
1211<p>
1212 This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>.
1213 The variable is optional and defaults to the <code class="filename">PN</code> variable.
1214 </p>
1215</dd>
1216<dt>
1217<a name="var-INITSCRIPT_NAME"></a>INITSCRIPT_NAME</dt>
1218<dd>
1219<p>
1220 The filename of the initscript (as installed to <code class="filename">${etcdir}/init.d)</code>.
1221 </p>
1222<p>
1223 This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>.
1224 The variable is Mandatory.
1225 </p>
1226</dd>
1227<dt>
1228<a name="var-INITSCRIPT_PARAMS"></a>INITSCRIPT_PARAMS</dt>
1229<dd>
1230<p>
1231 Specifies the options to pass to <code class="filename">update-rc.d</code>.
1232 An example is <code class="filename">start 99 5 2 . stop 20 0 1 6 .</code>, which gives the script a
1233 runlevel of 99, starts the script in initlevels 2 and 5, and
1234 stops the script in levels 0, 1 and 6.
1235 </p>
1236<p>
1237 The variable is mandatory and is used in recipes when using
1238 <code class="filename">update-rc.d.bbclass</code>.
1239 </p>
1240</dd>
1241</dl>
1242</div>
1243<div class="glossdiv" title="K">
1244<h3 class="title">K</h3>
1245<dl>
1246<dt>
1247<a name="var-KBRANCH"></a>KBRANCH</dt>
1248<dd>
1249<p>
1250 A regular expression used by the build process to explicitly identify the kernel
1251 branch that is validated, patched and configured during a build.
1252 The <code class="filename">KBRANCH</code> variable is optional.
1253 You can use it to trigger checks to ensure the exact kernel branch you want is
1254 being used by the build process.
1255 </p>
1256<p>
1257 Values for this variable are set in the kernel's recipe file and the kernel's
1258 append file.
1259 For example, if you are using the Yocto Project kernel that is based on the
1260 Linux 3.4 kernel, the kernel recipe file is the
1261 <code class="filename">meta/recipes-kernel/linux/linux-yocto_3.4.bb</code> file.
1262 Following is the default value for <code class="filename">KBRANCH</code> and the default
1263 override for the architectures the Yocto Project supports:
1264 </p>
1265<pre class="literallayout">
1266 KBRANCH_DEFAULT = "standard/base"
1267 KBRANCH = "${KBRANCH_DEFAULT}"
1268 </pre>
1269<p>
1270 This branch exists in the <code class="filename">linux-yocto-3.4</code> kernel Git
1271 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>.
1272 </p>
1273<p>
1274 This variable is also used from the kernel's append file to identify the kernel
1275 branch specific to a particular machine or target hardware.
1276 The kernel's append file is located in the BSP layer for a given machine.
1277 For example, the kernel append file for the Crown Bay BSP is in the
1278 <code class="filename">meta-intel</code> Git repository and is named
1279 <code class="filename">meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</code>.
1280 Here are the related statements from the append file:
1281 </p>
1282<pre class="literallayout">
1283 COMPATIBLE_MACHINE_crownbay = "crownbay"
1284 KMACHINE_crownbay = "crownbay"
1285 KBRANCH_crownbay = "standard/crownbay"
1286
1287 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
1288 KMACHINE_crownbay-noemgd = "crownbay"
1289 KBRANCH_crownbay-noemgd = "standard/crownbay"
1290 </pre>
1291<p>
1292 The <code class="filename">KBRANCH_*</code> statements identify the kernel branch to
1293 use when building for the Crown Bay BSP.
1294 In this case there are two identical statements: one for each type of
1295 Crown Bay machine.
1296 </p>
1297</dd>
1298<dt>
1299<a name="var-KERNEL_FEATURES"></a>KERNEL_FEATURES</dt>
1300<dd>
1301<p>Includes additional metadata from the Yocto Project kernel Git repository.
1302 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
1303 metadata is provided through
1304 the <code class="filename">KMACHINE</code> and <code class="filename">KBRANCH</code> variables.
1305 You can use the <code class="filename">KERNEL_FEATURES</code> variable to further
1306 add metadata for all BSPs.</p>
1307<p>The metadata you add through this variable includes config fragments and
1308 features descriptions,
1309 which usually includes patches as well as config fragments.
1310 You typically override the <code class="filename">KERNEL_FEATURES</code> variable
1311 for a specific machine.
1312 In this way, you can provide validated, but optional, sets of kernel
1313 configurations and features.</p>
1314<p>For example, the following adds <code class="filename">netfilter</code> to all
1315 the Yocto Project kernels and adds sound support to the <code class="filename">qemux86</code>
1316 machine:
1317 </p>
1318<pre class="literallayout">
1319 # Add netfilter to all linux-yocto kernels
1320 KERNEL_FEATURES="features/netfilter"
1321
1322 # Add sound support to the qemux86 machine
1323 KERNEL_FEATURES_append_qemux86=" cfg/sound"
1324 </pre>
1325</dd>
1326<dt>
1327<a name="var-KERNEL_IMAGETYPE"></a>KERNEL_IMAGETYPE</dt>
1328<dd><p>The type of kernel to build for a device, usually set by the
1329 machine configuration files and defaults to "zImage".
1330 This variable is used
1331 when building the kernel and is passed to <code class="filename">make</code> as the target to
1332 build.</p></dd>
1333<dt>
1334<a name="var-KMACHINE"></a>KMACHINE</dt>
1335<dd>
1336<p>
1337 The machine as known by the kernel.
1338 Sometimes the machine name used by the kernel does not match the machine name
1339 used by the OpenEmbedded build system.
1340 For example, the machine name that the OpenEmbedded build system understands as
1341 <code class="filename">qemuarm</code> goes by a different name in the Linux Yocto kernel.
1342 The kernel understands that machine as <code class="filename">arm_versatile926ejs</code>.
1343 For cases like these, the <code class="filename">KMACHINE</code> variable maps the
1344 kernel machine name to the OpenEmbedded build system machine name.
1345 </p>
1346<p>
1347 Kernel machine names are initially defined in the
1348 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_self">Yocto Linux Kernel</a> in
1349 the <code class="filename">meta</code> branch.
1350 From the <code class="filename">meta</code> branch, look in
1351 the <code class="filename">meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</code> file.
1352 For example, from the <code class="filename">meta</code> branch in the
1353 <code class="filename">linux-yocto-3.0</code> kernel, the
1354 <code class="filename">meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</code> file
1355 has the following:
1356 </p>
1357<pre class="literallayout">
1358 define KMACHINE cedartrail
1359 define KTYPE standard
1360 define KARCH i386
1361
1362 include ktypes/standard
1363 branch cedartrail
1364
1365 include cedartrail.scc
1366 </pre>
1367<p>
1368 You can see that the kernel understands the machine name for the Cedar Trail BSP as
1369 <code class="filename">cedartrail</code>.
1370 </p>
1371<p>
1372 If you look in the Cedar Trail BSP layer in the <code class="filename">meta-intel</code> source
1373 repository at <code class="filename">meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</code>,
1374 you will find the following statements among others:
1375 </p>
1376<pre class="literallayout">
1377 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
1378 KMACHINE_cedartrail = "cedartrail"
1379 KBRANCH_cedartrail = "yocto/standard/cedartrail"
1380 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
1381 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
1382
1383 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
1384 KMACHINE_cedartrail-nopvr = "cedartrail"
1385 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
1386 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
1387 </pre>
1388<p>
1389 The <code class="filename">KMACHINE</code> statements in the kernel's append file make sure that
1390 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
1391 names.
1392 </p>
1393<p>
1394 This append file uses two <code class="filename">KMACHINE</code> statements.
1395 The first is not really necessary but does ensure that the machine known to the
1396 OpenEmbedded build system as <code class="filename">cedartrail</code> maps to the machine
1397 in the kernel also known as <code class="filename">cedartrail</code>:
1398 </p>
1399<pre class="literallayout">
1400 KMACHINE_cedartrail = "cedartrail"
1401 </pre>
1402<p>
1403 </p>
1404<p>
1405 The second statement is a good example of why the <code class="filename">KMACHINE</code> variable
1406 is needed.
1407 In this example, the OpenEmbedded build system uses the <code class="filename">cedartrail-nopvr</code>
1408 machine name to refer to the Cedar Trail BSP that does not support the propriatory
1409 PowerVR driver.
1410 The kernel, however, uses the machine name <code class="filename">cedartrail</code>.
1411 Thus, the append file must map the <code class="filename">cedartrail-nopvr</code> machine name to
1412 the kernel's <code class="filename">cedartrail</code> name:
1413 </p>
1414<pre class="literallayout">
1415 KMACHINE_cedartrail-nopvr = "cedartrail"
1416 </pre>
1417<p>
1418 </p>
1419<p>
1420 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
1421 Project kernel machine names and the OpenEmbedded machine names.
1422 Be sure to use the <code class="filename">KMACHINE</code> if you create a BSP and the machine
1423 name you use is different than that used in the kernel.
1424 </p>
1425</dd>
1426</dl>
1427</div>
1428<div class="glossdiv" title="L">
1429<h3 class="title">L</h3>
1430<dl>
1431<dt>
1432<a name="var-LAYERDEPENDS"></a>LAYERDEPENDS</dt>
1433<dd><p>Lists the layers that this recipe depends upon, separated by spaces.
1434 Optionally, you can specify a specific layer version for a dependency
1435 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
1436 to be compared against <code class="filename">LAYERVERSION_anotherlayer</code> in this case).
1437 An error will be produced if any dependency is missing or
1438 the version numbers do not match exactly (if specified).
1439 This variable is used in the <code class="filename">conf/layer.conf</code> file
1440 and must be suffixed with the name of the specific layer (e.g.
1441 <code class="filename">LAYERDEPENDS_mylayer</code>).</p></dd>
1442<dt>
1443<a name="var-LAYERDIR"></a>LAYERDIR</dt>
1444<dd><p>When used inside the <code class="filename">layer.conf</code> configuration
1445 file, this variable provides the path of the current layer.
1446 This variable requires immediate expansion
1447 (see the BitBake manual) as lazy expansion can result in
1448 the expansion happening in the wrong directory and therefore
1449 giving the wrong value.</p></dd>
1450<dt>
1451<a name="var-LAYERVERSION"></a>LAYERVERSION</dt>
1452<dd><p>Optionally specifies the version of a layer as a single number.
1453 You can use this within <code class="filename">LAYERDEPENDS</code> for another layer in order to
1454 depend on a specific version of the layer.
1455 This variable is used in the <code class="filename">conf/layer.conf</code> file
1456 and must be suffixed with the name of the specific layer (e.g.
1457 <code class="filename">LAYERVERSION_mylayer</code>).</p></dd>
1458<dt>
1459<a name="var-LIC_FILES_CHKSUM"></a>LIC_FILES_CHKSUM</dt>
1460<dd>
1461<p>Checksums of the license text in the recipe source code.</p>
1462<p>This variable tracks changes in license text of the source
1463 code files.
1464 If the license text is changed, it will trigger a build
1465 failure, which gives the developer an opportunity to review any
1466 license change.</p>
1467<p>
1468 This variable must be defined for all recipes (unless <code class="filename">LICENSE</code>
1469 is set to "CLOSED")</p>
1470<p>For more information, see the
1471 <a class="link" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.4.1. Tracking License Changes">
1472 Tracking License Changes</a> section</p>
1473</dd>
1474<dt>
1475<a name="var-LICENSE"></a>LICENSE</dt>
1476<dd>
1477<p>
1478 The list of source licenses for the recipe.
1479 Follow these rules:
1480 </p>
1481<div class="itemizedlist"><ul class="itemizedlist" type="disc">
1482<li class="listitem"><p>Do not use spaces within individual
1483 license names.</p></li>
1484<li class="listitem"><p>Separate license names using
1485 | (pipe) when there is a choice between licenses.
1486 </p></li>
1487<li class="listitem"><p>Separate license names using
1488 &amp; (ampersand) when multiple licenses exist
1489 that cover different parts of the source.
1490 </p></li>
1491<li class="listitem"><p>You can use spaces between license
1492 names.</p></li>
1493</ul></div>
1494<p>
1495 </p>
1496<p>
1497 Here are some examples:
1498 </p>
1499<pre class="literallayout">
1500 LICENSE = "LGPLv2.1 | GPLv3"
1501 LICENSE = "MPL-1 &amp; LGPLv2.1"
1502 LICENSE = "GPLv2+"
1503 </pre>
1504<p>
1505 The first example is from the recipes for Qt, which the user
1506 may choose to distribute under either the LGPL version
1507 2.1 or GPL version 3.
1508 The second example is from Cairo where two licenses cover
1509 different parts of the source code.
1510 The final example is from <code class="filename">sysstat</code>,
1511 which presents a single license.
1512 </p>
1513</dd>
1514<dt>
1515<a name="var-LICENSE_PATH"></a>LICENSE_PATH</dt>
1516<dd>
1517<p>Path to additional licenses used during the build.
1518 By default, the OpenEmbedded build system uses <code class="filename">COMMON_LICENSE_DIR</code>
1519 to define the directory that holds common license text used during the build.
1520 The <code class="filename">LICENSE_PATH</code> variable allows you to extend that
1521 location to other areas that have additional licenses:
1522 </p>
1523<pre class="literallayout">
1524 LICENSE_PATH += "/path/to/additional/common/licenses"
1525 </pre>
1526</dd>
1527</dl>
1528</div>
1529<div class="glossdiv" title="M">
1530<h3 class="title">M</h3>
1531<dl>
1532<dt>
1533<a name="var-MACHINE"></a>MACHINE</dt>
1534<dd>
1535<p>
1536 Specifies the target device for which the image is built.
1537 You define <code class="filename">MACHINE</code> in the
1538 <code class="filename">local.conf</code> file found in the
1539 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.
1540 By default, <code class="filename">MACHINE</code> is set to
1541 "qemux86", which is an x86-based architecture machine to
1542 be emulated using QEMU:
1543 </p>
1544<pre class="literallayout">
1545 MACHINE ?= "qemux86"
1546 </pre>
1547<p>
1548 The variable corresponds to a machine configuration file of the
1549 same name, through which machine-specific configurations are set.
1550 Thus, when <code class="filename">MACHINE</code> is set to "qemux86" there
1551 exists the corresponding <code class="filename">qemux86.conf</code> machine
1552 configuration file, which can be found in the
1553 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>
1554 in <code class="filename">meta/conf/machine</code>.
1555 </p>
1556<p>
1557 The list of machines supported by the Yocto Project as
1558 shipped include the following:
1559 </p>
1560<pre class="literallayout">
1561 MACHINE ?= "qemuarm"
1562 MACHINE ?= "qemumips"
1563 MACHINE ?= "qemuppc"
1564 MACHINE ?= "qemux86"
1565 MACHINE ?= "qemux86-64"
1566 MACHINE ?= "atom-pc"
1567 MACHINE ?= "beagleboard"
1568 MACHINE ?= "mpc8315e-rdb"
1569 MACHINE ?= "routerstationpro"
1570 </pre>
1571<p>
1572 The last four are Yocto Project reference hardware boards, which
1573 are provided in the <code class="filename">meta-yocto-bsp</code> layer.
1574 </p>
1575<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
1576<h3 class="title">Note</h3>Adding additional Board Support Package (BSP) layers
1577 to your configuration adds new possible settings for
1578 <code class="filename">MACHINE</code>.
1579 </div>
1580<p>
1581 </p>
1582</dd>
1583<dt>
1584<a name="var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS"></a>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</dt>
1585<dd>
1586<p></p>
1587<p>
1588 A list of required machine-specific packages to install as part of
1589 the image being built.
1590 The build process depends on these packages being present.
1591 Furthermore, because this is a "machine essential" variable, the list of
1592 packages are essential for the machine to boot.
1593 The impact of this variable affects images based on
1594 <code class="filename">packagegroup-core-boot</code>,
1595 including the <code class="filename">core-image-minimal</code> image.
1596 </p>
1597<p>
1598 This variable is similar to the
1599 <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>
1600 variable with the exception that the image being built has a build
1601 dependency on the variable's list of packages.
1602 In other words, the image will not build if a file in this list is not found.
1603 </p>
1604<p>
1605 As an example, suppose the machine for which you are building requires
1606 <code class="filename">example-init</code> to be run during boot to initialize the hardware.
1607 In this case, you would use the following in the machine's
1608 <code class="filename">.conf</code> configuration file:
1609 </p>
1610<pre class="literallayout">
1611 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
1612 </pre>
1613<p>
1614 </p>
1615</dd>
1616<dt>
1617<a name="var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS"></a>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</dt>
1618<dd>
1619<p></p>
1620<p>
1621 A list of recommended machine-specific packages to install as part of
1622 the image being built.
1623 The build process does not depend on these packages being present.
1624 However, because this is a "machine essential" variable, the list of
1625 packages are essential for the machine to boot.
1626 The impact of this variable affects images based on
1627 <code class="filename">packagegroup-core-boot</code>,
1628 including the <code class="filename">core-image-minimal</code> image.
1629 </p>
1630<p>
1631 This variable is similar to the
1632 <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>
1633 variable with the exception that the image being built does not have a build
1634 dependency on the variable's list of packages.
1635 In other words, the image will still build if a package in this list is not found.
1636 Typically, this variable is used to handle essential kernel modules, whose
1637 functionality may be selected to be built into the kernel rather than as a module,
1638 in which case a package will not be produced.
1639 </p>
1640<p>
1641 Consider an example where you have a custom kernel where a specific touchscreen
1642 driver is required for the machine to be usable.
1643 However, the driver can be built as a module or
1644 into the kernel depending on the kernel configuration.
1645 If the driver is built as a module, you want it to be installed.
1646 But, when the driver is built into the kernel, you still want the
1647 build to succeed.
1648 This variable sets up a "recommends" relationship so that in the latter case,
1649 the build will not fail due to the missing package.
1650 To accomplish this, assuming the package for the module was called
1651 <code class="filename">kernel-module-ab123</code>, you would use the
1652 following in the machine's <code class="filename">.conf</code> configuration
1653 file:
1654 </p>
1655<pre class="literallayout">
1656 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
1657 </pre>
1658<p>
1659 </p>
1660<p>
1661 Some examples of these machine essentials are flash, screen, keyboard, mouse,
1662 or touchscreen drivers (depending on the machine).
1663 </p>
1664</dd>
1665<dt>
1666<a name="var-MACHINE_EXTRA_RDEPENDS"></a>MACHINE_EXTRA_RDEPENDS</dt>
1667<dd>
1668<p>
1669 A list of machine-specific packages to install as part of the
1670 image being built that are not essential for the machine to boot.
1671 However, the build process for more fully-featured images
1672 depends on the packages being present.
1673 </p>
1674<p>
1675 This variable affects all images based on
1676 <code class="filename">packagegroup-base</code>, which does not include the
1677 <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code>
1678 images.
1679 </p>
1680<p>
1681 The variable is similar to the
1682 <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS</a></code>
1683 variable with the exception that the image being built has a build
1684 dependency on the variable's list of packages.
1685 In other words, the image will not build if a file in this list is not found.
1686 </p>
1687<p>
1688 An example is a machine that has WiFi capability but is not essential
1689 For the machine to boot the image.
1690 However, if you are building a more fully-featured image, you want to enable
1691 the WiFi.
1692 The package containing the firmware for the WiFi hardware is always
1693 expected to exist, so it is acceptable for the build process to depend upon
1694 finding the package.
1695 In this case, assuming the package for the firmware was called
1696 <code class="filename">wifidriver-firmware</code>, you would use the following in the
1697 <code class="filename">.conf</code> file for the machine:
1698 </p>
1699<pre class="literallayout">
1700 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
1701 </pre>
1702<p>
1703 </p>
1704</dd>
1705<dt>
1706<a name="var-MACHINE_EXTRA_RRECOMMENDS"></a>MACHINE_EXTRA_RRECOMMENDS</dt>
1707<dd>
1708<p></p>
1709<p>
1710 A list of machine-specific packages to install as part of the
1711 image being built that are not essential for booting the machine.
1712 The image being built has no build dependency on this list of packages.
1713 </p>
1714<p>
1715 This variable affects only images based on
1716 <code class="filename">packagegroup-base</code>, which does not include the
1717 <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code>
1718 images.
1719 </p>
1720<p>
1721 This variable is similar to the
1722 <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS</a></code>
1723 variable with the exception that the image being built does not have a build
1724 dependency on the variable's list of packages.
1725 In other words, the image will build if a file in this list is not found.
1726 </p>
1727<p>
1728 An example is a machine that has WiFi capability but is not essential
1729 For the machine to boot the image.
1730 However, if you are building a more fully-featured image, you want to enable
1731 WiFi.
1732 In this case, the package containing the WiFi kernel module will not be produced
1733 if the WiFi driver is built into the kernel, in which case you still want the
1734 build to succeed instead of failing as a result of the package not being found.
1735 To accomplish this, assuming the package for the module was called
1736 <code class="filename">kernel-module-examplewifi</code>, you would use the
1737 following in the <code class="filename">.conf</code> file for the machine:
1738 </p>
1739<pre class="literallayout">
1740 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
1741 </pre>
1742<p>
1743 </p>
1744</dd>
1745<dt>
1746<a name="var-MACHINE_FEATURES"></a>MACHINE_FEATURES</dt>
1747<dd>
1748<p>Specifies the list of hardware features the
1749 <a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE">MACHINE</a> supports.
1750 For example, including the "bluetooth" feature causes the
1751 <code class="filename">bluez</code> bluetooth daemon to be built and
1752 added to the image.
1753 It also causes the <code class="filename">connman</code> recipe
1754 to look at <code class="filename">MACHINE_FEATURES</code> and when it
1755 finds "bluetooth" there it enables the bluetooth
1756 support in ConnMan.
1757 </p>
1758<p>
1759 For a list of features supported by the Yocto Project as shipped,
1760 see the "<a class="link" href="ref-features-machine.html" title="9.2. Machine">Machine</a>" section.
1761 </p>
1762</dd>
1763<dt>
1764<a name="var-MACHINE_FEATURES_BACKFILL"></a>MACHINE_FEATURES_BACKFILL</dt>
1765<dd>
1766<p>Features to be added to
1767 <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>
1768 if not also present in
1769 <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>.
1770 </p>
1771<p>
1772 This variable is set in the <code class="filename">meta/conf/bitbake.conf</code> file.
1773 It is not intended to be user-configurable.
1774 It is best to just reference the variable to see which machine features are
1775 being backfilled for all machine configurations.
1776 See the <a class="link" href="ref-features-backfill.html" title="9.4. Feature Backfilling">Feature backfilling</a> section for
1777 more information.
1778 </p>
1779</dd>
1780<dt>
1781<a name="var-MACHINE_FEATURES_BACKFILL_CONSIDERED"></a>MACHINE_FEATURES_BACKFILL_CONSIDERED</dt>
1782<dd><p>Features from
1783 <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES_BACKFILL" title="MACHINE_FEATURES_BACKFILL">MACHINE_FEATURES_BACKFILL</a></code>
1784 that should not be backfilled (i.e. added to
1785 <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>)
1786 during the build.
1787 See the <a class="link" href="ref-features-backfill.html" title="9.4. Feature Backfilling">Feature backfilling</a> section for
1788 more information.
1789 </p></dd>
1790<dt>
1791<a name="var-MAINTAINER"></a>MAINTAINER</dt>
1792<dd><p>The email address of the distribution maintainer.</p></dd>
1793<dt>
1794<a name="var-MLPREFIX"></a>MLPREFIX</dt>
1795<dd><p>
1796 Specifies a prefix has been added to
1797 <a class="link" href="ref-variables-glos.html#var-PN" title="PN"><code class="filename">PN</code></a> to create a special version
1798 of a recipe or package, such as a multilib version.
1799 The variable is used in places where the prefix needs to be
1800 added to or removed from a the name (e.g. the
1801 <a class="link" href="ref-variables-glos.html#var-BPN" title="BPN"><code class="filename">BPN</code></a> variable).
1802 <code class="filename">MLPREFIX</code> gets set when a prefix has been
1803 added to <code class="filename">PN</code>.
1804 </p></dd>
1805<dt>
1806<a name="var-MULTIMACH_TARGET_SYS"></a>MULTIMACH_TARGET_SYS</dt>
1807<dd><p>
1808 Separates files for different machines such that you can build
1809 for multiple target machines using the same output directories.
1810 See the <a class="link" href="ref-variables-glos.html#var-STAMP" title="STAMP"><code class="filename">STAMP</code></a> variable
1811 for an example.
1812 </p></dd>
1813</dl>
1814</div>
1815<div class="glossdiv" title="O">
1816<h3 class="title">O</h3>
1817<dl>
1818<dt>
1819<a name="var-OE_TERMINAL"></a>OE_TERMINAL</dt>
1820<dd>
1821<p>
1822 Controls how the OpenEmbedded build system spawns
1823 interactive terminals on the host development system
1824 (e.g. using the BitBake command with the
1825 <code class="filename">-c devshell</code> command-line option).
1826 For more information, see the
1827 "<a class="link" href="../dev-manual/platdev-appdev-devshell.html" target="_self">Using a Development Shell</a>" section
1828 in the Yocto Project Development Manual.
1829 </p>
1830<p>
1831 You can use the following values for the
1832 <code class="filename">OE_TERMINAL</code> variable:
1833 </p>
1834<pre class="literallayout">
1835 auto
1836 gnome
1837 xfce
1838 rxvt
1839 screen
1840 konsole
1841 none
1842 </pre>
1843<p>
1844 </p>
1845<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
1846<h3 class="title">Note</h3>Konsole support only works for KDE 3.x.
1847 Also, "auto" is the default behavior for
1848 <code class="filename">OE_TERMINAL</code>
1849</div>
1850<p>
1851 </p>
1852</dd>
1853</dl>
1854</div>
1855<div class="glossdiv" title="P">
1856<h3 class="title">P</h3>
1857<dl>
1858<dt>
1859<a name="var-P"></a>P</dt>
1860<dd>
1861<p>The recipe name and version.
1862 <code class="filename">P</code> is comprised of the following:
1863 </p>
1864<pre class="literallayout">
1865 ${PN}-${PV}
1866 </pre>
1867</dd>
1868<dt>
1869<a name="var-PACKAGE_ARCH"></a>PACKAGE_ARCH</dt>
1870<dd><p>The architecture of the resulting package or packages.</p></dd>
1871<dt>
1872<a name="var-PACKAGE_BEFORE_PN"></a>PACKAGE_BEFORE_PN</dt>
1873<dd><p>Enables easily adding packages to
1874 <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>
1875 before <code class="filename">${PN}</code> so that the packages can pick
1876 up files that would normally be included in the default package.</p></dd>
1877<dt>
1878<a name="var-PACKAGE_CLASSES"></a>PACKAGE_CLASSES</dt>
1879<dd>
1880<p>This variable, which is set in the <code class="filename">local.conf</code> configuration
1881 file found in the <code class="filename">conf</code> folder of the
1882 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>,
1883 specifies the package manager to use when packaging data.
1884 You can provide one or more arguments for the variable with the first
1885 argument being the package manager used to create images:
1886 </p>
1887<pre class="literallayout">
1888 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
1889 </pre>
1890<p>
1891 For information on build performance effects as a result of the
1892 package manager use, see
1893 <a class="link" href="ref-classes-package.html" title="7.13. Packaging - package*.bbclass">Packaging - <code class="filename">package*.bbclass</code></a>
1894 in this manual.
1895 </p>
1896</dd>
1897<dt>
1898<a name="var-PACKAGE_EXTRA_ARCHS"></a>PACKAGE_EXTRA_ARCHS</dt>
1899<dd><p>Specifies the list of architectures compatible with the device CPU.
1900 This variable is useful when you build for several different devices that use
1901 miscellaneous processors such as XScale and ARM926-EJS).</p></dd>
1902<dt>
1903<a name="var-PACKAGECONFIG"></a>PACKAGECONFIG</dt>
1904<dd>
1905<p>
1906 This variable provides a means of enabling or disabling
1907 features of a recipe on a per-recipe basis.
1908 The <code class="filename">PACKAGECONFIG</code>
1909 variable itself specifies a space-separated list of the
1910 features to enable.
1911 The features themselves are specified as flags on the
1912 <code class="filename">PACKAGECONFIG</code> variable.
1913 You can provide up to four arguments, which are separated by
1914 commas, to determine the behavior of each feature
1915 when it is enabled or disabled.
1916 You can omit any argument you like but must retain the
1917 separating commas.
1918 The arguments specify the following:
1919 </p>
1920<div class="orderedlist"><ol class="orderedlist" type="1">
1921<li class="listitem"><p>Extra arguments
1922 that should be added to the configure script argument list
1923 (<a class="link" href="ref-variables-glos.html#var-EXTRA_OECONF" title="EXTRA_OECONF"><code class="filename">EXTRA_OECONF</code></a>)
1924 if the feature is enabled.</p></li>
1925<li class="listitem"><p>Extra arguments
1926 that should be added to <code class="filename">EXTRA_OECONF</code>
1927 if the feature is disabled.
1928 </p></li>
1929<li class="listitem"><p>Additional build dependencies
1930 (<a class="link" href="ref-variables-glos.html#var-DEPENDS" title="DEPENDS"><code class="filename">DEPENDS</code></a>)
1931 that should be added if the feature is enabled.
1932 </p></li>
1933<li class="listitem"><p>Additional runtime dependencies
1934 (<a class="link" href="ref-variables-glos.html#var-RDEPENDS" title="RDEPENDS"><code class="filename">RDEPENDS</code></a>)
1935 that should be added if the feature is enabled.
1936 </p></li>
1937</ol></div>
1938<p>
1939 </p>
1940<p>
1941 Consider the following example taken from the
1942 <code class="filename">librsvg</code> recipe.
1943 In this example the feature is <code class="filename">croco</code>, which
1944 has three arguments that determine the feature's behavior.
1945 </p>
1946<pre class="literallayout">
1947 PACKAGECONFIG ??= "croco"
1948 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
1949 </pre>
1950<p>
1951 The <code class="filename">--with-croco</code> and
1952 <code class="filename">libcroco</code> arguments apply only if
1953 the feature is enabled.
1954 In this case, <code class="filename">--with-croco</code> is
1955 added to the configure script argument list and
1956 <code class="filename">libcroco</code> is added to
1957 <code class="filename"><a class="link" href="ref-variables-glos.html#var-DEPENDS" title="DEPENDS">DEPENDS</a></code>.
1958 On the other hand, if the feature is disabled say through
1959 a <code class="filename">.bbappend</code> file in another layer, then
1960 the second argument <code class="filename">--without-croco</code> is
1961 added to the configure script rather than
1962 <code class="filename">--with-croco</code>.
1963 </p>
1964</dd>
1965<dt>
1966<a name="var-PACKAGES"></a>PACKAGES</dt>
1967<dd>
1968<p>The list of packages to be created from the recipe.
1969 The default value is the following:
1970 </p>
1971<pre class="literallayout">
1972 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
1973 </pre>
1974</dd>
1975<dt>
1976<a name="var-PACKAGES_DYNAMIC"></a>PACKAGES_DYNAMIC</dt>
1977<dd>
1978<p>
1979 A promise that your recipe satisfies runtime dependencies
1980 for optional modules that are found in other recipes.
1981 <code class="filename">PACKAGES_DYNAMIC</code>
1982 does not actually satisfy the dependencies, it only states that
1983 they should be satisfied.
1984 For example, if a hard, runtime dependency
1985 (<code class="filename">RDEPENDS</code>) of another package is satisfied
1986 at build time through the <code class="filename">PACKAGES_DYNAMIC</code>
1987 variable, but a package with the module name is never actually
1988 produced, then the other package will be broken.
1989 Thus, if you attempt to include that package in an image,
1990 you will get a dependency failure from the packaging system
1991 during <code class="filename">do_rootfs</code>.
1992 Typically, if there is a chance that such a situation can
1993 occur and the package that is not created is valid
1994 without the dependency being satisfied, then you should use
1995 <code class="filename">RRECOMMENDS</code> (a soft runtime dependency)
1996 instead of <code class="filename">RDEPENDS</code>.
1997 </p>
1998<p>
1999 For an example of how to use the <code class="filename">PACKAGES_DYNAMIC</code>
2000 variable when you are splitting packages, see the
2001 "<a class="link" href="../dev-manual/handling-optional-module-packaging.html" target="_self">Handling Optional Module Packaging</a>" section
2002 in the Yocto Project Development Manual.
2003 </p>
2004</dd>
2005<dt>
2006<a name="var-PARALLEL_MAKE"></a>PARALLEL_MAKE</dt>
2007<dd><p>Specifies extra options that are passed to the <code class="filename">make</code> command during the
2008 compile tasks.
2009 This variable is usually in the form <code class="filename">-j 4</code>, where the number
2010 represents the maximum number of parallel threads make can run.
2011 If you development host supports multiple cores a good rule of thumb is to set
2012 this variable to twice the number of cores on the host.</p></dd>
2013<dt>
2014<a name="var-PF"></a>PF</dt>
2015<dd>
2016<p>Specifies the recipe or package name and includes all version and revision
2017 numbers (i.e. <code class="filename">eglibc-2.13-r20+svnr15508/</code> and
2018 <code class="filename">bash-4.2-r1/</code>).
2019 This variable is comprised of the following:
2020 </p>
2021<pre class="literallayout">
2022 ${PN}-${EXTENDPE}${PV}-${PR}
2023 </pre>
2024</dd>
2025<dt>
2026<a name="var-PN"></a>PN</dt>
2027<dd>
2028<p>This variable can have two separate functions depending on the context: a recipe
2029 name or a resulting package name.</p>
2030<p><code class="filename">PN</code> refers to a recipe name in the context of a file used
2031 by the OpenEmbedded build system as input to create a package.
2032 The name is normally extracted from the recipe file name.
2033 For example, if the recipe is named
2034 <code class="filename">expat_2.0.1.bb</code>, then the default value of <code class="filename">PN</code>
2035 will be "expat".</p>
2036<p>
2037 The variable refers to a package name in the context of a file created or produced by the
2038 OpenEmbedded build system.</p>
2039<p>If applicable, the <code class="filename">PN</code> variable also contains any special
2040 suffix or prefix.
2041 For example, using <code class="filename">bash</code> to build packages for the native
2042 machine, <code class="filename">PN</code> is <code class="filename">bash-native</code>.
2043 Using <code class="filename">bash</code> to build packages for the target and for Multilib,
2044 <code class="filename">PN</code> would be <code class="filename">bash</code> and
2045 <code class="filename">lib64-bash</code>, respectively.
2046 </p>
2047</dd>
2048<dt>
2049<a name="var-PR"></a>PR</dt>
2050<dd><p>The revision of the recipe.
2051 The default value for this variable is "r0".
2052 </p></dd>
2053<dt>
2054<a name="var-PRINC"></a>PRINC</dt>
2055<dd>
2056<p>Causes the <code class="filename">PR</code> variable of
2057 <code class="filename">.bbappend</code> files to dynamically increment.
2058 This increment minimizes the impact of layer ordering.</p>
2059<p>In order to ensure multiple <code class="filename">.bbappend</code> files can co-exist,
2060 <code class="filename">PRINC</code> should be self referencing.
2061 This variable defaults to 0.</p>
2062<p>Following is an example that increments <code class="filename">PR</code> by two:
2063 </p>
2064<pre class="literallayout">
2065 PRINC := "${@int(PRINC) + 2}"
2066 </pre>
2067<p>
2068 It is adviseable not to use strings such as ".= '.1'" with the variable because
2069 this usage is very sensitive to layer ordering.
2070 Explicit assignments should be avoided as they cannot adequately represent multiple
2071 <code class="filename">.bbappend</code> files.</p>
2072</dd>
2073<dt>
2074<a name="var-PV"></a>PV</dt>
2075<dd><p>The version of the recipe.
2076 The version is normally extracted from the recipe filename.
2077 For example, if the recipe is named
2078 <code class="filename">expat_2.0.1.bb</code>, then the default value of <code class="filename">PV</code>
2079 will be "2.0.1".
2080 <code class="filename">PV</code> is generally not overridden within
2081 a recipe unless it is building an unstable (i.e. development) version from a source code repository
2082 (e.g. Git or Subversion).
2083 </p></dd>
2084<dt>
2085<a name="var-PE"></a>PE</dt>
2086<dd><p>
2087 the epoch of the recipe.
2088 The default value is "0".
2089 The field is used to make upgrades possible when the versioning scheme changes in
2090 some backwards incompatible way.
2091 </p></dd>
2092<dt>
2093<a name="var-PREFERRED_PROVIDER"></a>PREFERRED_PROVIDER</dt>
2094<dd>
2095<p>
2096 If multiple recipes provide an item, this variable
2097 determines which recipe should be given preference.
2098 The variable must always be suffixed with the name of the
2099 provided item, and should be set to the
2100 <code class="filename">PN</code> of the recipe
2101 to which you want to give precedence.
2102 Here is an example:
2103 </p>
2104<pre class="literallayout">
2105 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
2106 </pre>
2107<p>
2108 </p>
2109</dd>
2110<dt>
2111<a name="var-PREFERRED_VERSION"></a>PREFERRED_VERSION</dt>
2112<dd>
2113<p>
2114 If there are multiple versions of recipes available, this
2115 variable determines which recipe should be given preference.
2116 The variable must always be suffixed with the <code class="filename">PN</code>
2117 for which to select, and should be set to the
2118 <code class="filename">PV</code> to which you want to give precedence.
2119 You can use the "<code class="filename">%</code>" character as a wildcard
2120 to match any number of characters, which can be useful when
2121 specifying versions that contain long revision number that could
2122 potentially change.
2123 Here are two examples:
2124 </p>
2125<pre class="literallayout">
2126 PREFERRED_VERSION_python = "2.6.6"
2127 PREFERRED_VERSION_linux-yocto = "3.0+git%"
2128 </pre>
2129<p>
2130 </p>
2131</dd>
2132</dl>
2133</div>
2134<div class="glossdiv" title="R">
2135<h3 class="title">R</h3>
2136<dl>
2137<dt>
2138<a name="var-RCONFLICTS"></a>RCONFLICTS</dt>
2139<dd>
2140<p>The list of packages that conflict with a package.
2141 Note that the package will not be installed if the conflicting packages are not
2142 first removed.</p>
2143<p>
2144 Like all package-controlling variables, you must always use them in
2145 conjunction with a package name override.
2146 Here is an example:
2147 </p>
2148<pre class="literallayout">
2149 RCONFLICTS_${PN} = "another-conflicting-package-name"
2150 </pre>
2151<p>
2152 </p>
2153</dd>
2154<dt>
2155<a name="var-RDEPENDS"></a>RDEPENDS</dt>
2156<dd>
2157<p>
2158 Lists a package's run-time dependencies (i.e. other packages)
2159 that must be installed for the package to be built.
2160 In other words, in order for the package to be built and
2161 run correctly, it depends on the listed packages.
2162 If a package in this list cannot be found, it is probable
2163 that a dependency error would occur before the build.
2164 </p>
2165<p>
2166 The names of the variables you list with
2167 <code class="filename">RDEPENDS</code> must be the names of other
2168 packages as listed in the
2169 <a class="link" href="ref-variables-glos.html#var-PACKAGES" title="PACKAGES"><code class="filename">PACKAGES</code></a>
2170 variable.
2171 You should not list recipe names (<code class="filename">PN</code>).
2172 </p>
2173<p>
2174 Because the <code class="filename">RDEPENDS</code> variable applies
2175 to packages being built, you should
2176 always attach a package name to the variable to specify the
2177 particular run-time package that has the dependency.
2178 For example, suppose you are building a development package
2179 that depends on the <code class="filename">perl</code> package.
2180 In this case, you would use the following
2181 <code class="filename">RDEPENDS</code> statement:
2182 </p>
2183<pre class="literallayout">
2184 RDEPENDS_${PN}-dev += "perl"
2185 </pre>
2186<p>
2187 In the example, the package name
2188 (<code class="filename">${PN}-dev</code>) must appear as it would
2189 in the
2190 <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>
2191 namespace before any renaming of the output package by
2192 classes like <code class="filename">debian.bbclass</code>.
2193 </p>
2194<p>
2195 In many cases you do not need to explicitly add dependencies
2196 to <code class="filename">RDEPENDS</code> since some automatic
2197 handling occurs:
2198 </p>
2199<div class="itemizedlist"><ul class="itemizedlist" type="disc">
2200<li class="listitem"><p><span class="emphasis"><em><code class="filename">shlibdeps</code></em></span>: If
2201 a run-time package contains a shared library
2202 (<code class="filename">.so</code>), the build
2203 processes the library in order to determine other
2204 libraries to which it is dynamically linked.
2205 The build process adds these libraries to
2206 <code class="filename">RDEPENDS</code> when creating the run-time
2207 package.</p></li>
2208<li class="listitem"><p><span class="emphasis"><em><code class="filename">pcdeps</code></em></span>: If
2209 the package ships a <code class="filename">pkg-config</code>
2210 information file, the build process uses this file
2211 to add items to the <code class="filename">RDEPENDS</code>
2212 variable to create the run-time packages.
2213 </p></li>
2214</ul></div>
2215<p>
2216 </p>
2217</dd>
2218<dt>
2219<a name="var-RRECOMMENDS"></a>RRECOMMENDS</dt>
2220<dd>
2221<p>
2222 A list of packages that extend the usability of a package being
2223 built.
2224 The package being built does not depend on this list of packages in
2225 order to successfully build, but needs them for the extended usability.
2226 To specify runtime dependencies for packages, see the
2227 <code class="filename"><a class="link" href="ref-variables-glos.html#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variable.
2228 </p>
2229<p>
2230 The OpenEmbedded build process automatically installs the list of packages
2231 as part of the built package.
2232 However, you can remove them later if you want.
2233 If, during the build, a package from the list cannot be found, the build
2234 process continues without an error.
2235 </p>
2236<p>
2237 Because the <code class="filename">RRECOMMENDS</code> variable applies to packages
2238 being built, you should
2239 always attach an override to the variable to specify the particular package
2240 whose usability is being extended.
2241 For example, suppose you are building a development package that is extended
2242 to support wireless functionality.
2243 In this case, you would use the following:
2244 </p>
2245<pre class="literallayout">
2246 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
2247 </pre>
2248<p>
2249 In the example, the package name (<code class="filename">${PN}-dev</code>) must
2250 appear as it would in the
2251 <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> namespace before any
2252 renaming of the output package by classes like <code class="filename">debian.bbclass</code>.
2253 </p>
2254</dd>
2255<dt>
2256<a name="var-RREPLACES"></a>RREPLACES</dt>
2257<dd><p>The list of packages that are replaced with this package.</p></dd>
2258</dl>
2259</div>
2260<div class="glossdiv" title="S">
2261<h3 class="title">S</h3>
2262<dl>
2263<dt>
2264<a name="var-S"></a>S</dt>
2265<dd>
2266<p>
2267 The location in the <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>
2268 where unpacked package source code resides.
2269 This location is within the working directory
2270 (<code class="filename"><a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>), which
2271 is not static.
2272 The unpacked source location depends on the package name
2273 (<code class="filename"><a class="link" href="ref-variables-glos.html#var-PN" title="PN">PN</a></code>) and
2274 package version (<code class="filename"><a class="link" href="ref-variables-glos.html#var-PV" title="PV">PV</a></code>) as
2275 follows:
2276 </p>
2277<pre class="literallayout">
2278 ${WORKDIR}/${PN}-${PV}
2279 </pre>
2280<p>
2281 As an example, assume a
2282 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a> top-level
2283 folder named <code class="filename">poky</code>
2284 and a default <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>
2285 at <code class="filename">poky/build</code>.
2286 In this case, the working directory the build system uses to build
2287 the <code class="filename">db</code> package is the following:
2288 </p>
2289<pre class="literallayout">
2290 ~/poky/build/tmp/work/qemux86-poky-linux/db-5.1.19-r3/db-5.1.19
2291 </pre>
2292<p>
2293 </p>
2294</dd>
2295<dt>
2296<a name="var-SDKIMAGE_FEATURES"></a>SDKIMAGE_FEATURES</dt>
2297<dd><p>Equivalent to
2298 <code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code>.
2299 However, this variable applies to the SDK generated from an image using
2300 <code class="filename">bitbake -c populate_sdk imagename</code>).
2301 </p></dd>
2302<dt>
2303<a name="var-SECTION"></a>SECTION</dt>
2304<dd><p>The section in which packages should be categorized.
2305 Package management utilities can make use of this variable.</p></dd>
2306<dt>
2307<a name="var-SELECTED_OPTIMIZATION"></a>SELECTED_OPTIMIZATION</dt>
2308<dd><p>
2309 The variable takes the value of
2310 <code class="filename"><a class="link" href="ref-variables-glos.html#var-FULL_OPTIMIZATION" title="FULL_OPTIMIZATION">FULL_OPTIMIZATION</a></code>
2311 unless <code class="filename"><a class="link" href="ref-variables-glos.html#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a></code> = "1".
2312 In this case the value of
2313 <code class="filename"><a class="link" href="ref-variables-glos.html#var-DEBUG_OPTIMIZATION" title="DEBUG_OPTIMIZATION">DEBUG_OPTIMIZATION</a></code> is used.
2314 </p></dd>
2315<dt>
2316<a name="var-SERIAL_CONSOLE"></a>SERIAL_CONSOLE</dt>
2317<dd><p>The speed and device for the serial port used to attach the serial console.
2318 This variable is given to the kernel as the "console"
2319 parameter and after booting occurs <code class="filename">getty</code> is started on that port
2320 so remote login is possible.</p></dd>
2321<dt>
2322<a name="var-SITEINFO_ENDIANNESS"></a>SITEINFO_ENDIANNESS</dt>
2323<dd><p>
2324 Specifies the endian byte order of the target system.
2325 The value should be either "le" for little-endian or "be" for big-endian.
2326 </p></dd>
2327<dt>
2328<a name="var-SITEINFO_BITS"></a>SITEINFO_BITS</dt>
2329<dd><p>
2330 Specifies the number of bits for the target system CPU.
2331 The value should be either "32" or "64".
2332 </p></dd>
2333<dt>
2334<a name="var-SPECIAL_PKGSUFFIX"></a>SPECIAL_PKGSUFFIX</dt>
2335<dd><p>
2336 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
2337 OpenEmbedded build system to create variants of recipes or packages.
2338 The list specifies the prefixes to strip off during certain circumstances
2339 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.
2340 </p></dd>
2341<dt>
2342<a name="var-SRC_URI"></a>SRC_URI</dt>
2343<dd>
2344<p>The list of source files - local or remote.
2345 This variable tells the OpenEmbedded build system which bits to pull
2346 in for the build and how to pull them in.
2347 For example, if the recipe only needs to fetch a tarball from the
2348 internet, the recipe uses a single <code class="filename">SRC_URI</code> entry.
2349 On the other hand, if the recipe needs to fetch a tarball, apply
2350 two patches, and include a custom file, the recipe would include four
2351 instances of the variable.</p>
2352<p>The following list explains the available URI protocols:
2353 </p>
2354<div class="itemizedlist"><ul class="itemizedlist" type="disc">
2355<li class="listitem">
2356<p><span class="emphasis"><em><code class="filename">file://</code> -</em></span> Fetches files, which is usually
2357 a file shipped with the metadata, from the local machine.
2358 The path is relative to the
2359 <a class="link" href="ref-variables-glos.html#var-FILESPATH" title="FILESPATH"><code class="filename">FILESPATH</code></a>
2360 variable.
2361 Thus, the build system searches, in order, from the following directories,
2362 which are assumed to be a subdirectories of the directory in which the
2363 recipe file resides:
2364 </p>
2365<div class="itemizedlist"><ul class="itemizedlist" type="circle">
2366<li class="listitem"><p><span class="emphasis"><em><code class="filename">${PN}</code> -</em></span> The recipe name
2367 with any special suffix or prefix, if applicable.
2368 For example, using <code class="filename">bash</code> to build for the native
2369 machine, <code class="filename">PN</code> is <code class="filename">bash-native</code>.
2370 Using <code class="filename">bash</code> to build for the target and for Multilib,
2371 <code class="filename">PN</code> would be <code class="filename">bash</code> and
2372 <code class="filename">lib64-bash</code>, respectively.
2373 </p></li>
2374<li class="listitem"><p><span class="emphasis"><em><code class="filename">${PF}</code> - </em></span>
2375 <code class="filename">${PN}-${EXTENDPE}${PV}-${PR}</code>.
2376 The recipe name including all version and revision numbers
2377 (i.e. <code class="filename">eglibc-2.13-r20+svnr15508/</code> and
2378 <code class="filename">bash-4.2-r1/</code>).</p></li>
2379<li class="listitem"><p><span class="emphasis"><em><code class="filename">${P}</code> -</em></span>
2380 <code class="filename">${PN}-${PV}</code>.
2381 The recipe name and version (i.e. <code class="filename">bash-4.2</code>).
2382 </p></li>
2383<li class="listitem"><p><span class="emphasis"><em><code class="filename">${BPN}</code> -</em></span> The
2384 base recipe name without any special suffix or version numbers.
2385 </p></li>
2386<li class="listitem"><p><span class="emphasis"><em><code class="filename">${BP}</code> -</em></span>
2387 <code class="filename">${BPN}-${PV}</code>.
2388 The base recipe name and version but without any special
2389 package name suffix.</p></li>
2390<li class="listitem"><p><span class="emphasis"><em>Files -</em></span> Files beneath the directory in which the recipe
2391 resides.</p></li>
2392<li class="listitem"><p><span class="emphasis"><em>Directory -</em></span> The directory itself in which the recipe
2393 resides.</p></li>
2394</ul></div>
2395</li>
2396<li class="listitem"><p><span class="emphasis"><em><code class="filename">bzr://</code> -</em></span> Fetches files from a
2397 Bazaar revision control repository.</p></li>
2398<li class="listitem"><p><span class="emphasis"><em><code class="filename">git://</code> -</em></span> Fetches files from a
2399 Git revision control repository.</p></li>
2400<li class="listitem"><p><span class="emphasis"><em><code class="filename">osc://</code> -</em></span> Fetches files from
2401 an OSC (OpenSuse Build service) revision control repository.</p></li>
2402<li class="listitem"><p><span class="emphasis"><em><code class="filename">repo://</code> -</em></span> Fetches files from
2403 a repo (Git) repository.</p></li>
2404<li class="listitem"><p><span class="emphasis"><em><code class="filename">svk://</code> -</em></span> Fetches files from
2405 an SVK revision control repository.</p></li>
2406<li class="listitem"><p><span class="emphasis"><em><code class="filename">http://</code> -</em></span> Fetches files from
2407 the Internet using <code class="filename">http</code>.</p></li>
2408<li class="listitem"><p><span class="emphasis"><em><code class="filename">https://</code> -</em></span> Fetches files
2409 from the Internet using <code class="filename">https</code>.</p></li>
2410<li class="listitem"><p><span class="emphasis"><em><code class="filename">ftp://</code> -</em></span> Fetches files
2411 from the Internet using <code class="filename">ftp</code>.</p></li>
2412<li class="listitem"><p><span class="emphasis"><em><code class="filename">cvs://</code> -</em></span> Fetches files from
2413 a CVS revision control repository.</p></li>
2414<li class="listitem"><p><span class="emphasis"><em><code class="filename">hg://</code> -</em></span> Fetches files from
2415 a Mercurial (<code class="filename">hg</code>) revision control repository.</p></li>
2416<li class="listitem"><p><span class="emphasis"><em><code class="filename">p4://</code> -</em></span> Fetches files from
2417 a Perforce (<code class="filename">p4</code>) revision control repository.</p></li>
2418<li class="listitem"><p><span class="emphasis"><em><code class="filename">ssh://</code> -</em></span> Fetches files from
2419 a secure shell.</p></li>
2420<li class="listitem"><p><span class="emphasis"><em><code class="filename">svn://</code> -</em></span> Fetches files from
2421 a Subversion (<code class="filename">svn</code>) revision control repository.</p></li>
2422</ul></div>
2423<p>
2424 </p>
2425<p>Standard and recipe-specific options for <code class="filename">SRC_URI</code> exist.
2426 Here are standard options:
2427 </p>
2428<div class="itemizedlist"><ul class="itemizedlist" type="disc">
2429<li class="listitem"><p><span class="emphasis"><em><code class="filename">apply</code> -</em></span> Whether to apply
2430 the patch or not.
2431 The default action is to apply the patch.</p></li>
2432<li class="listitem"><p><span class="emphasis"><em><code class="filename">striplevel</code> -</em></span> Which
2433 striplevel to use when applying the patch.
2434 The default level is 1.</p></li>
2435</ul></div>
2436<p>
2437 </p>
2438<p>Here are options specific to recipes building code from a revision control system:
2439 </p>
2440<div class="itemizedlist"><ul class="itemizedlist" type="disc">
2441<li class="listitem"><p><span class="emphasis"><em><code class="filename">mindate</code> -</em></span> Only applies
2442 the patch if <a class="link" href="ref-variables-glos.html#var-SRCDATE" title="SRCDATE"><code class="filename">SRCDATE</code></a>
2443 is equal to or greater than <code class="filename">mindate</code>.</p></li>
2444<li class="listitem"><p><span class="emphasis"><em><code class="filename">maxdate</code> -</em></span> Only applies
2445 the patch if <a class="link" href="ref-variables-glos.html#var-SRCDATE" title="SRCDATE"><code class="filename">SRCDATE</code></a>
2446 is not later than <code class="filename">mindate</code>.</p></li>
2447<li class="listitem"><p><span class="emphasis"><em><code class="filename">minrev</code> -</em></span> Only applies
2448 the patch if <a class="link" href="ref-variables-glos.html#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a>
2449 is equal to or greater than <code class="filename">minrev</code>.</p></li>
2450<li class="listitem"><p><span class="emphasis"><em><code class="filename">maxrev</code> -</em></span> Only applies
2451 the patch if <a class="link" href="ref-variables-glos.html#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a>
2452 is not later than <code class="filename">maxrev</code>.</p></li>
2453<li class="listitem"><p><span class="emphasis"><em><code class="filename">rev</code> -</em></span> Only applies the
2454 patch if <a class="link" href="ref-variables-glos.html#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a>
2455 is equal to <code class="filename">rev</code>.</p></li>
2456<li class="listitem"><p><span class="emphasis"><em><code class="filename">notrev</code> -</em></span> Only applies
2457 the patch if <a class="link" href="ref-variables-glos.html#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a>
2458 is not equal to <code class="filename">rev</code>.</p></li>
2459</ul></div>
2460<p>
2461 </p>
2462<p>Here are some additional options worth mentioning:
2463 </p>
2464<div class="itemizedlist"><ul class="itemizedlist" type="disc">
2465<li class="listitem"><p><span class="emphasis"><em><code class="filename">unpack</code> -</em></span> Controls
2466 whether or not to unpack the file if it is an archive.
2467 The default action is to upack the file.</p></li>
2468<li class="listitem"><p><span class="emphasis"><em><code class="filename">subdir</code> -</em></span> Places the file
2469 (or extracts its contents) into the specified
2470 subdirectory of <a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>.
2471 This option is useful for unusual tarballs or other archives that
2472 don't have their files already in a subdirectory within the archive.
2473 </p></li>
2474<li class="listitem"><p><span class="emphasis"><em><code class="filename">name</code> -</em></span> Specifies a
2475 name to be used for association with <code class="filename">SRC_URI</code> checksums
2476 when you have more than one file specified in <code class="filename">SRC_URI</code>.
2477 </p></li>
2478<li class="listitem"><p><span class="emphasis"><em><code class="filename">downloadfilename</code> -</em></span> Specifies
2479 the filename used when storing the downloaded file.</p></li>
2480</ul></div>
2481<p>
2482 </p>
2483</dd>
2484<dt>
2485<a name="var-SRC_URI_OVERRIDES_PACKAGE_ARCH"></a>SRC_URI_OVERRIDES_PACKAGE_ARCH</dt>
2486<dd>
2487<p></p>
2488<p>
2489 By default, the OpenEmbedded build system automatically detects whether
2490 <code class="filename"><a class="link" href="ref-variables-glos.html#var-SRC_URI" title="SRC_URI">SRC_URI</a></code>
2491 contains files that are machine-specific.
2492 If so, the build system automatically changes
2493 <code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></code>.
2494 Setting this variable to "0" disables this behavior.
2495 </p>
2496</dd>
2497<dt>
2498<a name="var-SRCDATE"></a>SRCDATE</dt>
2499<dd><p>
2500 The date of the source code used to build the package.
2501 This variable applies only if the source was fetched from a Source Code Manager (SCM).
2502 </p></dd>
2503<dt>
2504<a name="var-SRCREV"></a>SRCREV</dt>
2505<dd><p>
2506 The revision of the source code used to build the package.
2507 This variable applies to Subversion, Git, Mercurial and Bazaar
2508 only.
2509 Note that if you wish to build a fixed revision and you wish
2510 to avoid performing a query on the remote repository every time
2511 BitBake parses your recipe, you should specify a <code class="filename">SRCREV</code> that is a
2512 full revision identifier and not just a tag.
2513 </p></dd>
2514<dt>
2515<a name="var-SSTATE_DIR"></a>SSTATE_DIR</dt>
2516<dd><p>The directory for the shared state.</p></dd>
2517<dt>
2518<a name="var-SSTATE_MIRRORS"></a>SSTATE_MIRRORS</dt>
2519<dd>
2520<p>
2521 Configures the OpenEmbedded build system to search other
2522 mirror locations for prebuilt cache data objects before
2523 building out the data.
2524 This variable works like fetcher
2525 <code class="filename">MIRRORS</code>/<code class="filename">PREMIRRORS</code>
2526 and points to the cache locations to check for the shared
2527 objects.
2528 </p>
2529<p>
2530 You can specify a filesystem directory or a remote URL such
2531 as HTTP or FTP.
2532 The locations you specify need to contain the shared state
2533 cache (sstate-cache) results from previous builds.
2534 The sstate-cache you point to can also be from builds on
2535 other machines.
2536 </p>
2537<p>
2538 If a mirror uses the same structure as
2539 <a class="link" href="ref-variables-glos.html#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a>,
2540 you need to add
2541 "PATH" at the end as shown in the examples below.
2542 The build system substitues the correct path within the
2543 directory structure.
2544 </p>
2545<pre class="literallayout">
2546 SSTATE_MIRRORS ?= "\
2547 file://.* http://someserver.tld/share/sstate/PATH \n \
2548 file://.* file:///some/local/dir/sstate/PATH"
2549 </pre>
2550<p>
2551 </p>
2552</dd>
2553<dt>
2554<a name="var-STAGING_KERNEL_DIR"></a>STAGING_KERNEL_DIR</dt>
2555<dd><p>
2556 The directory with kernel headers that are required to build out-of-tree
2557 modules.
2558 </p></dd>
2559<dt>
2560<a name="var-STAMP"></a>STAMP</dt>
2561<dd>
2562<p>
2563 Specifies the base path used to create recipe stamp files.
2564 The path to an actual stamp file is constructed by evaluating this
2565 string and then appending additional information.
2566 Currently, the default assignment for <code class="filename">STAMP</code>
2567 as set in the <code class="filename">meta/conf/bitbake.conf</code> file
2568 is:
2569 </p>
2570<pre class="literallayout">
2571 STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}-${EXTENDPE}${PV}-${PR}"
2572 </pre>
2573<p>
2574 See <a class="link" href="ref-variables-glos.html#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>,
2575 <a class="link" href="ref-variables-glos.html#var-MULTIMACH_TARGET_SYS" title="MULTIMACH_TARGET_SYS"><code class="filename">MULTIMACH_TARGET_SYS</code></a>,
2576 <a class="link" href="ref-variables-glos.html#var-PN" title="PN"><code class="filename">PN</code></a>,
2577 <a class="link" href="ref-variables-glos.html#var-EXTENDPE" title="EXTENDPE"><code class="filename">EXTENDPE</code></a>,
2578 <a class="link" href="ref-variables-glos.html#var-PV" title="PV"><code class="filename">PV</code></a>, and
2579 <a class="link" href="ref-variables-glos.html#var-PR" title="PR"><code class="filename">PR</code></a> for related variable
2580 information.
2581 </p>
2582</dd>
2583<dt>
2584<a name="var-SUMMARY"></a>SUMMARY</dt>
2585<dd><p>The short (72 characters or less) summary of the binary package for packaging
2586 systems such as <code class="filename">opkg</code>, <code class="filename">rpm</code> or
2587 <code class="filename">dpkg</code>.
2588 By default, <code class="filename">SUMMARY</code> is used to define
2589 the <a class="link" href="ref-variables-glos.html#var-DESCRIPTION" title="DESCRIPTION"><code class="filename">DESCRIPTION</code></a>
2590 variable if <code class="filename">DESCRIPTION</code> is not set
2591 in the recipe.
2592 </p></dd>
2593</dl>
2594</div>
2595<div class="glossdiv" title="T">
2596<h3 class="title">T</h3>
2597<dl>
2598<dt>
2599<a name="var-T"></a>T</dt>
2600<dd>
2601<p>This variable points to a directory were Bitbake places temporary
2602 files when building a particular package.
2603 It is typically set as follows:
2604 </p>
2605<pre class="literallayout">
2606 T = ${WORKDIR}/temp
2607 </pre>
2608<p>
2609 The <a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>
2610 is the directory into which Bitbake unpacks and builds the package.
2611 The default <code class="filename">bitbake.conf</code> file sets this variable.</p>
2612<p>The <code class="filename">T</code> variable is not to be confused with
2613 the <a class="link" href="ref-variables-glos.html#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> variable,
2614 which points to the root of the directory tree where Bitbake
2615 places the output of an entire build.
2616 </p>
2617</dd>
2618<dt>
2619<a name="var-TARGET_ARCH"></a>TARGET_ARCH</dt>
2620<dd><p>The architecture of the device being built.
2621 While a number of values are possible, the OpenEmbedded build system primarily supports
2622 <code class="filename">arm</code> and <code class="filename">i586</code>.</p></dd>
2623<dt>
2624<a name="var-TARGET_CFLAGS"></a>TARGET_CFLAGS</dt>
2625<dd><p>
2626 Flags passed to the C compiler for the target system.
2627 This variable evaluates to the same as
2628 <code class="filename"><a class="link" href="ref-variables-glos.html#var-CFLAGS" title="CFLAGS">CFLAGS</a></code>.
2629 </p></dd>
2630<dt>
2631<a name="var-TARGET_FPU"></a>TARGET_FPU</dt>
2632<dd><p>Specifies the method for handling FPU code.
2633 For FPU-less targets, which include most ARM CPUs, the variable must be
2634 set to "soft".
2635 If not, the kernel emulation gets used, which results in a performance penalty.</p></dd>
2636<dt>
2637<a name="var-TARGET_OS"></a>TARGET_OS</dt>
2638<dd><p>Specifies the target's operating system.
2639 The variable can be set to "linux" for <code class="filename">eglibc</code>-based systems and
2640 to "linux-uclibc" for <code class="filename">uclibc</code>.
2641 For ARM/EABI targets, there are also "linux-gnueabi" and
2642 "linux-uclibc-gnueabi" values possible.</p></dd>
2643<dt>
2644<a name="var-TCLIBC"></a>TCLIBC</dt>
2645<dd>
2646<p>
2647 Specifies which variant of the GNU standard C library (<code class="filename">libc</code>)
2648 to use during the build process.
2649 This variable replaces <code class="filename">POKYLIBC</code>, which is no longer
2650 supported.
2651 </p>
2652<p>
2653 You can select <code class="filename">eglibc</code> or <code class="filename">uclibc</code>.
2654 </p>
2655<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
2656<h3 class="title">Note</h3>
2657 This release of the Yocto Project does not support the
2658 <code class="filename">glibc</code> implementation of <code class="filename">libc</code>.
2659 </div>
2660<p>
2661 </p>
2662</dd>
2663<dt>
2664<a name="var-TCMODE"></a>TCMODE</dt>
2665<dd>
2666<p>
2667 The toolchain selector.
2668 This variable replaces <code class="filename">POKYMODE</code>, which is no longer
2669 supported.
2670 </p>
2671<p>
2672 The <code class="filename">TCMODE</code> variable selects the external toolchain
2673 built using the OpenEmbedded build system or a few supported combinations of
2674 the upstream GCC or CodeSourcery Labs toolchain.
2675 The variable identifies the <code class="filename">tcmode-*</code> files used in
2676 the <code class="filename">meta/conf/distro/include</code> directory, which is found in the
2677 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
2678 </p>
2679<p>
2680 By default, <code class="filename">TCMODE</code> is set to "default", which
2681 chooses the <code class="filename">tcmode-default.inc</code> file.
2682 The variable is similar to
2683 <a class="link" href="ref-variables-glos.html#var-TCLIBC" title="TCLIBC"><code class="filename">TCLIBC</code></a>, which controls
2684 the variant of the GNU standard C library (<code class="filename">libc</code>)
2685 used during the build process: <code class="filename">eglibc</code> or <code class="filename">uclibc</code>.
2686 </p>
2687</dd>
2688<dt>
2689<a name="var-TMPDIR"></a>TMPDIR</dt>
2690<dd>
2691<p>
2692 This variable is the temporary directory the OpenEmbedded build system
2693 uses when it does its work building images.
2694 By default, the <code class="filename">TMPDIR</code> variable is named
2695 <code class="filename">tmp</code> within the
2696 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.
2697 </p>
2698<p>
2699 If you want to establish this directory in a location other than the
2700 default, you can uncomment the following statement in the
2701 <code class="filename">conf/local.conf</code> file in the
2702 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>:
2703 </p>
2704<pre class="literallayout">
2705 #TMPDIR = "${TOPDIR}/tmp"
2706 </pre>
2707<p>
2708 </p>
2709</dd>
2710<dt>
2711<a name="var-TOPDIR"></a>TOPDIR</dt>
2712<dd><p>
2713 This variable is the
2714 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.
2715 BitBake automatically sets this variable.
2716 The OpenEmbedded build system uses the Build Directory when building images.
2717 </p></dd>
2718</dl>
2719</div>
2720<div class="glossdiv" title="W">
2721<h3 class="title">W</h3>
2722<dl>
2723<dt>
2724<a name="var-WORKDIR"></a>WORKDIR</dt>
2725<dd>
2726<p>
2727 The pathname of the working directory in which the OpenEmbedded build system
2728 builds a recipe.
2729 This directory is located within the
2730 <a class="link" href="ref-variables-glos.html#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> directory structure and changes
2731 as different packages are built.
2732 </p>
2733<p>
2734 The actual <code class="filename">WORKDIR</code> directory depends on several things:
2735 </p>
2736<div class="itemizedlist"><ul class="itemizedlist" type="disc">
2737<li class="listitem">The temporary directory - <a class="link" href="ref-variables-glos.html#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>
2738</li>
2739<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>
2740</li>
2741<li class="listitem">The target machine - <a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a>
2742</li>
2743<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>
2744</li>
2745<li class="listitem">The recipe name - <a class="link" href="ref-variables-glos.html#var-PN" title="PN"><code class="filename">PN</code></a>
2746</li>
2747<li class="listitem">The recipe version - <a class="link" href="ref-variables-glos.html#var-PV" title="PV"><code class="filename">PV</code></a>
2748</li>
2749<li class="listitem">The recipe revision - <a class="link" href="ref-variables-glos.html#var-PR" title="PR"><code class="filename">PR</code></a>
2750</li>
2751</ul></div>
2752<p>
2753 </p>
2754<p>
2755 For packages that are not dependent on a particular machine,
2756 <code class="filename">WORKDIR</code> is defined as follows:
2757 </p>
2758<pre class="literallayout">
2759 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
2760 </pre>
2761<p>
2762 As an example, assume a
2763 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a> top-level
2764 folder name <code class="filename">poky</code> and a default
2765 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>
2766 at <code class="filename">poky/build</code>.
2767 In this case, the working directory the build system uses to build
2768 the <code class="filename">v86d</code> package is the following:
2769 </p>
2770<pre class="literallayout">
2771 ~/poky/build/tmp/work/qemux86-poky-linux/v86d-01.9-r0
2772 </pre>
2773<p>
2774 </p>
2775<p>
2776 For packages that are dependent on a particular machine, <code class="filename">WORKDIR</code>
2777 is defined slightly different:
2778 </p>
2779<pre class="literallayout">
2780 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
2781 </pre>
2782<p>
2783 As an example, again assume a Source Directory top-level folder
2784 named <code class="filename">poky</code> and a default Build Directory
2785 at <code class="filename">poky/build</code>.
2786 In this case, the working directory the build system uses to build
2787 the <code class="filename">acl</code> recipe, which is being built for a
2788 MIPS-based device, is the following:
2789 </p>
2790<pre class="literallayout">
2791 ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
2792 </pre>
2793<p>
2794 </p>
2795</dd>
2796</dl>
2797</div>
2798</div>
2799</div></body>
2800</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>11.1.1. Distribution (Distro)</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-varlocality-configuration.html" title="11.1. Configuration">
9<link rel="prev" href="ref-varlocality-configuration.html" title="11.1. Configuration">
10<link rel="next" href="ref-varlocality-config-machine.html" title="11.1.2. Machine">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.1.1. Distribution (Distro)">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="ref-varlocality-config-distro"></a>11.1.1. Distribution (Distro)</h3></div></div></div>
15<p>
16 This section lists variables whose context is the distribution, or distro.
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO" title="DISTRO">DISTRO</a></code></p></li>
20<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>
21 </p></li>
22<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO_VERSION" title="DISTRO_VERSION">DISTRO_VERSION</a>
23 </code></p></li>
24<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-MAINTAINER" title="MAINTAINER">MAINTAINER</a></code>
25 </p></li>
26<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a>
27 </code></p></li>
28<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>
29 </p></li>
30<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>
31 </p></li>
32<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-TCMODE" title="TCMODE">TCMODE</a></code>
33 </p></li>
34<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-TCLIBC" title="TCLIBC">TCLIBC</a></code>
35 </p></li>
36</ul></div>
37<p>
38 </p>
39</div></body>
40</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>11.1.3. Local</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-varlocality-configuration.html" title="11.1. Configuration">
9<link rel="prev" href="ref-varlocality-config-machine.html" title="11.1.2. Machine">
10<link rel="next" href="ref-varlocality-recipes.html" title="11.2. Recipes">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.1.3. Local">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="ref-varlocality-config-local"></a>11.1.3. Local</h3></div></div></div>
15<p>
16 This section lists variables whose context is the local configuration through the
17 <code class="filename">local.conf</code> file.
18 </p>
19<div class="itemizedlist"><ul class="itemizedlist" type="disc">
20<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-DISTRO" title="DISTRO">DISTRO</a></code>
21 </p></li>
22<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE">MACHINE</a></code>
23 </p></li>
24<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>
25 </p></li>
26<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-BBFILES" title="BBFILES">BBFILES</a></code>
27 </p></li>
28<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
29 </a></code></p></li>
30<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a>
31 </code></p></li>
32<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>
33 </code></p></li>
34<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-BBINCLUDELOGS" title="BBINCLUDELOGS">BBINCLUDELOGS</a>
35 </code></p></li>
36<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">
37 ENABLE_BINARY_LOCALE_GENERATION</a></code></p></li>
38</ul></div>
39<p>
40 </p>
41</div></body>
42</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>11.1.2. Machine</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-varlocality-configuration.html" title="11.1. Configuration">
9<link rel="prev" href="ref-varlocality-config-distro.html" title="11.1.1. Distribution (Distro)">
10<link rel="next" href="ref-varlocality-config-local.html" title="11.1.3. Local">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.1.2. Machine">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="ref-varlocality-config-machine"></a>11.1.2. Machine</h3></div></div></div>
15<p>
16 This section lists variables whose context is the machine.
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<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>
20 </p></li>
21<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE</a>
22 </code></p></li>
23<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>
24 </code></p></li>
25<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a>
26 </code></p></li>
27<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a>
28 </code></p></li>
29<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
30 </a></code></p></li>
31<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
32 </a></code></p></li>
33<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
34 </a></code></p></li>
35<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">
36 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code></p></li>
37</ul></div>
38<p>
39 </p>
40</div></body>
41</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>11.1. Configuration</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-varlocality.html" title="Chapter 11. Variable Context">
9<link rel="prev" href="ref-varlocality.html" title="Chapter 11. Variable Context">
10<link rel="next" href="ref-varlocality-config-distro.html" title="11.1.1. Distribution (Distro)">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.1. Configuration">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-varlocality-configuration"></a>11.1. Configuration</h2></div></div></div>
15<p>
16 The following subsections provide lists of variables whose context is
17 configuration: distribution, machine, and local.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>11.2.4. Extra Build Information</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-varlocality-recipes.html" title="11.2. Recipes">
9<link rel="prev" href="ref-varlocality-recipe-paths.html" title="11.2.3. Paths">
10<link rel="next" href="faq.html" title="Chapter 12. FAQ">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.2.4. Extra Build Information">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="ref-varlocality-recipe-build"></a>11.2.4. Extra Build Information</h3></div></div></div>
15<p>
16 This section lists variables that define extra build information for recipes.
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_OECMAKE" title="EXTRA_OECMAKE">EXTRA_OECMAKE</a>
20 </code></p></li>
21<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a>
22 </code></p></li>
23<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a>
24 </code></p></li>
25<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>
26 </p></li>
27<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE
28 </a></code></p></li>
29</ul></div>
30<p>
31 </p>
32</div></body>
33</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>11.2.2. Dependencies</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-varlocality-recipes.html" title="11.2. Recipes">
9<link rel="prev" href="ref-varlocality-recipe-required.html" title="11.2.1. Required">
10<link rel="next" href="ref-varlocality-recipe-paths.html" title="11.2.3. Paths">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.2.2. Dependencies">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="ref-varlocality-recipe-dependencies"></a>11.2.2. Dependencies</h3></div></div></div>
15<p>
16 This section lists variables that define recipe dependencies.
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-DEPENDS" title="DEPENDS">DEPENDS</a>
20 </code></p></li>
21<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a>
22 </code></p></li>
23<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-RRECOMMENDS" title="RRECOMMENDS">RRECOMMENDS</a>
24 </code></p></li>
25<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-RCONFLICTS" title="RCONFLICTS">RCONFLICTS</a>
26 </code></p></li>
27<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-RREPLACES" title="RREPLACES">RREPLACES</a>
28 </code></p></li>
29</ul></div>
30<p>
31 </p>
32</div></body>
33</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>11.2.3. Paths</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-varlocality-recipes.html" title="11.2. Recipes">
9<link rel="prev" href="ref-varlocality-recipe-dependencies.html" title="11.2.2. Dependencies">
10<link rel="next" href="ref-varlocality-recipe-build.html" title="11.2.4. Extra Build Information">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.2.3. Paths">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="ref-varlocality-recipe-paths"></a>11.2.3. Paths</h3></div></div></div>
15<p>
16 This section lists variables that define recipe paths.
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR">WORKDIR</a>
20 </code></p></li>
21<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-S" title="S">S</a>
22 </code></p></li>
23<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-FILES" title="FILES">FILES</a>
24 </code></p></li>
25</ul></div>
26<p>
27 </p>
28</div></body>
29</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>11.2.1. Required</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-varlocality-recipes.html" title="11.2. Recipes">
9<link rel="prev" href="ref-varlocality-recipes.html" title="11.2. Recipes">
10<link rel="next" href="ref-varlocality-recipe-dependencies.html" title="11.2.2. Dependencies">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.2.1. Required">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="ref-varlocality-recipe-required"></a>11.2.1. Required</h3></div></div></div>
15<p>
16 This section lists variables that are required for recipes.
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<li class="listitem"><p><code class="filename"><a class="link" href="ref-variables-glos.html#var-LICENSE" title="LICENSE">LICENSE</a>
20 </code></p></li>
21<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>
22 </code></p></li>
23<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
24 in recipes that fetch local or remote files.
25 </p></li>
26</ul></div>
27<p>
28 </p>
29</div></body>
30</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>11.2. Recipes</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-varlocality.html" title="Chapter 11. Variable Context">
9<link rel="prev" href="ref-varlocality-config-local.html" title="11.1.3. Local">
10<link rel="next" href="ref-varlocality-recipe-required.html" title="11.2.1. Required">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="11.2. Recipes">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="ref-varlocality-recipes"></a>11.2. Recipes</h2></div></div></div>
15<p>
16 The following subsections provide lists of variables whose context is
17 recipes: required, dependencies, path, and extra build information.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 11. Variable Context</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="ref-variables-glos.html" title="Chapter 10. Variables Glossary">
10<link rel="next" href="ref-varlocality-configuration.html" title="11.1. Configuration">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 11. Variable Context">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="ref-varlocality"></a>Chapter 11. Variable Context</h2></div></div></div>
15<div class="toc">
16<p><b>Table of Contents</b></p>
17<dl>
18<dt><span class="section"><a href="ref-varlocality-configuration.html">11.1. Configuration</a></span></dt>
19<dd><dl>
20<dt><span class="section"><a href="ref-varlocality-config-distro.html">11.1.1. Distribution (Distro)</a></span></dt>
21<dt><span class="section"><a href="ref-varlocality-config-machine.html">11.1.2. Machine</a></span></dt>
22<dt><span class="section"><a href="ref-varlocality-config-local.html">11.1.3. Local</a></span></dt>
23</dl></dd>
24<dt><span class="section"><a href="ref-varlocality-recipes.html">11.2. Recipes</a></span></dt>
25<dd><dl>
26<dt><span class="section"><a href="ref-varlocality-recipe-required.html">11.2.1. Required</a></span></dt>
27<dt><span class="section"><a href="ref-varlocality-recipe-dependencies.html">11.2.2. Dependencies</a></span></dt>
28<dt><span class="section"><a href="ref-varlocality-recipe-paths.html">11.2.3. Paths</a></span></dt>
29<dt><span class="section"><a href="ref-varlocality-recipe-build.html">11.2.4. Extra Build Information</a></span></dt>
30</dl></dd>
31</dl>
32</div>
33<p>
34 While most variables can be used in almost any context such as
35 <code class="filename">.conf</code>, <code class="filename">.bbclass</code>,
36 <code class="filename">.inc</code>, and <code class="filename">.bb</code> files,
37 some variables are often associated with a particular locality or context.
38 This chapter describes some common associations.
39 </p>
40</div></body>
41</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>1.3.2. Required Packages for the Host Development System</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="intro-requirements.html" title="1.3. System Requirements">
9<link rel="prev" href="detailed-supported-distros.html" title="1.3.1. Supported Linux Distributions">
10<link rel="next" href="ubuntu-packages.html" title="1.3.2.1. Ubuntu">
11</head>
12<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">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="required-packages-for-the-host-development-system"></a>1.3.2. Required Packages for the Host Development System</h3></div></div></div>
15<p>
16 The list of packages you need on the host development system can
17 be large when covering all build scenarios using the Yocto Project.
18 This section provides required packages by Linux distribution and
19 further categorized by function.
20 </p>
21</div></body>
22</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>13.2. Tracking Bugs</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="resources.html" title="Chapter 13. Contributing to the Yocto Project">
9<link rel="prev" href="resources-intro.html" title="13.1. Introduction">
10<link rel="next" href="resources-mailinglist.html" title="13.3. Mailing lists">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="13.2. Tracking Bugs">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="resources-bugtracker"></a>13.2. Tracking Bugs</h2></div></div></div>
15<p>
16 If you find problems with the Yocto Project, you should report them using the
17 Bugzilla application at <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_self">http://bugzilla.yoctoproject.org</a>.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>13.6. Contributions</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="resources.html" title="Chapter 13. Contributing to the Yocto Project">
9<link rel="prev" href="resources-links.html" title="13.5. Links">
10</head>
11<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="13.6. Contributions">
12<div class="titlepage"><div><div><h2 class="title" style="clear: both">
13<a name="resources-contributions"></a>13.6. Contributions</h2></div></div></div>
14<p>
15 The Yocto Project gladly accepts contributions.
16 You can submit changes to the project either by creating and sending pull requests,
17 or by submitting patches through email.
18 For information on how to do both, see the
19 "<a class="link" href="../dev-manual/how-to-submit-a-change.html" target="_self">How to Submit a Change</a>"
20 section in the Yocto Project Development Manual.
21 </p>
22</div></body>
23</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>13.1. Introduction</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="resources.html" title="Chapter 13. Contributing to the Yocto Project">
9<link rel="prev" href="resources.html" title="Chapter 13. Contributing to the Yocto Project">
10<link rel="next" href="resources-bugtracker.html" title="13.2. Tracking Bugs">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="13.1. Introduction">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="resources-intro"></a>13.1. Introduction</h2></div></div></div>
15<p>
16 The Yocto Project team is happy for people to experiment with the Yocto Project.
17 A number of places exist to find help if you run into difficulties or find bugs.
18 To find out how to download source code,
19 see the "<a class="link" href="../dev-manual/local-yp-release.html" target="_self">Yocto Project Release</a>"
20 list item in the Yocto Project Development Manual.
21 </p>
22</div></body>
23</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>13.4. Internet Relay Chat (IRC)</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="resources.html" title="Chapter 13. Contributing to the Yocto Project">
9<link rel="prev" href="resources-mailinglist.html" title="13.3. Mailing lists">
10<link rel="next" href="resources-links.html" title="13.5. Links">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="13.4. Internet Relay Chat (IRC)">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="resources-irc"></a>13.4. Internet Relay Chat (IRC)</h2></div></div></div>
15<p>
16 Two IRC channels on freenode are available for the Yocto Project and Poky discussions:
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<li class="listitem"><p><code class="filename">#yocto</code></p></li>
20<li class="listitem"><p><code class="filename">#poky</code></p></li>
21</ul></div>
22<p>
23 </p>
24</div></body>
25</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>13.5. Links</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="resources.html" title="Chapter 13. Contributing to the Yocto Project">
9<link rel="prev" href="resources-irc.html" title="13.4. Internet Relay Chat (IRC)">
10<link rel="next" href="resources-contributions.html" title="13.6. Contributions">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="13.5. Links">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="resources-links"></a>13.5. Links</h2></div></div></div>
15<p>
16 Following is a list of resources you will find helpful:
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.yoctoproject.org" target="_self">The Yocto Project website</a>:
20 </em></span> The home site for the Yocto Project.</p></li>
21<li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.intel.com/" target="_self">Intel Corporation</a>:</em></span>
22 The company who acquired OpenedHand in 2008 and began development on the
23 Yocto Project.</p></li>
24<li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.openembedded.org" target="_self">OpenEmbedded</a>:</em></span>
25 The upstream, generic, embedded distribution used as the basis for the build system in the
26 Yocto Project.
27 Poky derives from and contributes back to the OpenEmbedded project.</p></li>
28<li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://developer.berlios.de/projects/bitbake/" target="_self">
29 BitBake</a>:</em></span> The tool used to process metadata.</p></li>
30<li class="listitem"><p><span class="emphasis"><em>BitBake User Manual:</em></span>
31 A comprehensive guide to the BitBake tool.
32 You can find the BitBake User Manual in the <code class="filename">bitbake/doc/manual</code>
33 directory, which is found in the
34 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
35 </p></li>
36<li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://wiki.qemu.org/Index.html" target="_self">QEMU</a>:
37 </em></span> An open source machine emulator and virtualizer.</p></li>
38</ul></div>
39<p>
40 </p>
41</div></body>
42</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>13.3. Mailing lists</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="resources.html" title="Chapter 13. Contributing to the Yocto Project">
9<link rel="prev" href="resources-bugtracker.html" title="13.2. Tracking Bugs">
10<link rel="next" href="resources-irc.html" title="13.4. Internet Relay Chat (IRC)">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="13.3. Mailing lists">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="resources-mailinglist"></a>13.3. Mailing lists</h2></div></div></div>
15<p>
16 There are a number of mailing lists maintained by the Yocto Project as well as
17 related OpenEmbedded mailing lists for discussion, patch submission and announcements.
18 To subscribe to one of the following mailing lists, click on the appropriate URL
19 in the following list and follow the instructions:
20 </p>
21<div class="itemizedlist"><ul class="itemizedlist" type="disc">
22<li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_self">http://lists.yoctoproject.org/listinfo/yocto</a> -
23 General Yocto Project discussion mailing list. </p></li>
24<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> -
25 Discussion mailing list about OpenEmbedded-Core (the core metadata).</p></li>
26<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> -
27 Discussion mailing list about OpenEmbedded.</p></li>
28<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> -
29 Discussion mailing list about the BitBake build tool.</p></li>
30<li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/poky" target="_self">http://lists.yoctoproject.org/listinfo/poky</a> -
31 Discussion mailing list about Poky.</p></li>
32<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> -
33 Mailing list to receive official Yocto Project release and milestone
34 announcements.</p></li>
35</ul></div>
36<p>
37 </p>
38</div></body>
39</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 13. Contributing to the Yocto Project</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="faq.html" title="Chapter 12. FAQ">
10<link rel="next" href="resources-intro.html" title="13.1. Introduction">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 13. Contributing to the Yocto Project">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="resources"></a>Chapter 13. Contributing to the Yocto Project</h2></div></div></div>
15<div class="toc">
16<p><b>Table of Contents</b></p>
17<dl>
18<dt><span class="section"><a href="resources-intro.html">13.1. Introduction</a></span></dt>
19<dt><span class="section"><a href="resources-bugtracker.html">13.2. Tracking Bugs</a></span></dt>
20<dt><span class="section"><a href="resources-mailinglist.html">13.3. Mailing lists</a></span></dt>
21<dt><span class="section"><a href="resources-irc.html">13.4. Internet Relay Chat (IRC)</a></span></dt>
22<dt><span class="section"><a href="resources-links.html">13.5. Links</a></span></dt>
23<dt><span class="section"><a href="resources-contributions.html">13.6. Contributions</a></span></dt>
24</dl>
25</div>
26</div></body>
27</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.2. Shared State Cache</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="technical-details.html" title="Chapter 3. Technical Details">
9<link rel="prev" href="usingpoky-components-configuration.html" title="3.1.4. Configuration">
10<link rel="next" href="overall-architecture.html" title="3.2.1. Overall Architecture">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2. Shared State Cache">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="shared-state-cache"></a>3.2. Shared State Cache</h2></div></div></div>
15<p>
16 By design, the OpenEmbedded build system builds everything from scratch unless
17 BitBake can determine that parts don't need to be rebuilt.
18 Fundamentally, building from scratch is attractive as it means all parts are
19 built fresh and there is no possibility of stale data causing problems.
20 When developers hit problems, they typically default back to building from scratch
21 so they know the state of things from the start.
22 </p>
23<p>
24 Building an image from scratch is both an advantage and a disadvantage to the process.
25 As mentioned in the previous paragraph, building from scratch ensures that
26 everything is current and starts from a known state.
27 However, building from scratch also takes much longer as it generally means
28 rebuilding things that don't necessarily need rebuilt.
29 </p>
30<p>
31 The Yocto Project implements shared state code that supports incremental builds.
32 The implementation of the shared state code answers the following questions that
33 were fundamental roadblocks within the OpenEmbedded incremental build support system:
34 </p>
35<div class="itemizedlist"><ul class="itemizedlist" type="disc">
36<li class="listitem">What pieces of the system have changed and what pieces have not changed?</li>
37<li class="listitem">How are changed pieces of software removed and replaced?</li>
38<li class="listitem">How are pre-built components that don't need to be rebuilt from scratch
39 used when they are available?</li>
40</ul></div>
41<p>
42 </p>
43<p>
44 For the first question, the build system detects changes in the "inputs" to a given task by
45 creating a checksum (or signature) of the task's inputs.
46 If the checksum changes, the system assumes the inputs have changed and the task needs to be
47 rerun.
48 For the second question, the shared state (sstate) code tracks which tasks add which output
49 to the build process.
50 This means the output from a given task can be removed, upgraded or otherwise manipulated.
51 The third question is partly addressed by the solution for the second question
52 assuming the build system can fetch the sstate objects from remote locations and
53 install them if they are deemed to be valid.
54 </p>
55<p>
56 The rest of this section goes into detail about the overall incremental build
57 architecture, the checksums (signatures), shared state, and some tips and tricks.
58 </p>
59</div></body>
60</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.2.3. Shared State</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="shared-state-cache.html" title="3.2. Shared State Cache">
9<link rel="prev" href="checksums.html" title="3.2.2. Checksums (Signatures)">
10<link rel="next" href="tips-and-tricks.html" title="3.2.4. Tips and Tricks">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.3. Shared State">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="shared-state"></a>3.2.3. Shared State</h3></div></div></div>
15<p>
16 Checksums and dependencies, as discussed in the previous section, solve half the
17 problem.
18 The other part of the problem is being able to use checksum information during the build
19 and being able to reuse or rebuild specific components.
20 </p>
21<p>
22 The shared state class (<code class="filename">sstate.bbclass</code>)
23 is a relatively generic implementation of how to "capture" a snapshot of a given task.
24 The idea is that the build process does not care about the source of a task's output.
25 Output could be freshly built or it could be downloaded and unpacked from
26 somewhere - the build process doesn't need to worry about its source.
27 </p>
28<p>
29 There are two types of output, one is just about creating a directory
30 in <code class="filename">WORKDIR</code>.
31 A good example is the output of either <code class="filename">do_install</code> or
32 <code class="filename">do_package</code>.
33 The other type of output occurs when a set of data is merged into a shared directory
34 tree such as the sysroot.
35 </p>
36<p>
37 The Yocto Project team has tried to keep the details of the implementation hidden in
38 <code class="filename">sstate.bbclass</code>.
39 From a user's perspective, adding shared state wrapping to a task
40 is as simple as this <code class="filename">do_deploy</code> example taken from
41 <code class="filename">do_deploy.bbclass</code>:
42 </p>
43<pre class="literallayout">
44 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
45 SSTATETASKS += "do_deploy"
46 do_deploy[sstate-name] = "deploy"
47 do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
48 do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
49
50 python do_deploy_setscene () {
51 sstate_setscene(d)
52 }
53 addtask do_deploy_setscene
54 </pre>
55<p>
56 In the example, we add some extra flags to the task, a name field ("deploy"), an
57 input directory where the task sends data, and the output
58 directory where the data from the task should eventually be copied.
59 We also add a <code class="filename">_setscene</code> variant of the task and add the task
60 name to the <code class="filename">SSTATETASKS</code> list.
61 </p>
62<p>
63 If you have a directory whose contents you need to preserve, you can do this with
64 a line like the following:
65 </p>
66<pre class="literallayout">
67 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
68 </pre>
69<p>
70 This method, as well as the following example, also works for multiple directories.
71 </p>
72<pre class="literallayout">
73 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
74 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
75 do_package[sstate-lockfile] = "${PACKAGELOCK}"
76 </pre>
77<p>
78 These methods also include the ability to take a lockfile when manipulating
79 shared state directory structures since some cases are sensitive to file
80 additions or removals.
81 </p>
82<p>
83 Behind the scenes, the shared state code works by looking in
84 <a class="link" href="ref-variables-glos.html#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a> and
85 <a class="link" href="ref-variables-glos.html#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a>
86 for shared state files.
87 Here is an example:
88 </p>
89<pre class="literallayout">
90 SSTATE_MIRRORS ?= "\
91 file://.* http://someserver.tld/share/sstate/PATH \n \
92 file://.* file:///some/local/dir/sstate/PATH"
93 </pre>
94<p>
95 </p>
96<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
97<h3 class="title">Note</h3>
98 The shared state directory (<code class="filename">SSTATE_DIR</code>) is
99 organized into two-character subdirectories, where the subdirectory
100 names are based on the first two characters of the hash.
101 If the shared state directory structure for a mirror has the
102 same structure as <code class="filename">SSTATE_DIR</code>, you must
103 specify "PATH" as part of the URI to enable the build system
104 to map to the appropriate subdirectory.
105 </div>
106<p>
107 </p>
108<p>
109 The shared state package validity can be detected just by looking at the
110 filename since the filename contains the task checksum (or signature) as
111 described earlier in this section.
112 If a valid shared state package is found, the build process downloads it
113 and uses it to accelerate the task.
114 </p>
115<p>
116 The build processes uses the <code class="filename">*_setscene</code> tasks
117 for the task acceleration phase.
118 BitBake goes through this phase before the main execution code and tries
119 to accelerate any tasks for which it can find shared state packages.
120 If a shared state package for a task is available, the shared state
121 package is used.
122 This means the task and any tasks on which it is dependent are not
123 executed.
124 </p>
125<p>
126 As a real world example, the aim is when building an IPK-based image,
127 only the <code class="filename">do_package_write_ipk</code> tasks would have their
128 shared state packages fetched and extracted.
129 Since the sysroot is not used, it would never get extracted.
130 This is another reason why a task-based approach is preferred over a
131 recipe-based approach, which would have to install the output from every task.
132 </p>
133</div></body>
134</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.1.11. LICENSE, README, and README.hardware</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-core.html" title="5.1. Top level core components">
9<link rel="prev" href="structure-core-script.html" title="5.1.10. oe-init-build-env">
10<link rel="next" href="structure-build.html" title="5.2. The Build Directory - build/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.11. LICENSE, README, and README.hardware">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-basic-top-level"></a>5.1.11. <code class="filename">LICENSE, README, and README.hardware</code>
15</h3></div></div></div>
16<p>
17 These files are standard top-level files.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.3. build/conf/bblayers.conf</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-conf-local.conf.html" title="5.2.2. build/conf/local.conf">
10<link rel="next" href="structure-build-conf-sanity_info.html" title="5.2.4. build/conf/sanity_info">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.3. build/conf/bblayers.conf">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-conf-bblayers.conf"></a>5.2.3. <code class="filename">build/conf/bblayers.conf</code>
15</h3></div></div></div>
16<p>
17 This file defines layers, which is a directory tree, traversed (or walked) by BitBake.
18 If <code class="filename">bblayers.conf</code>
19 is not present, it is created from <code class="filename">bblayers.conf.sample</code> when
20 you <code class="filename">source</code> the environment setup script.
21 </p>
22</div></body>
23</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.2. build/conf/local.conf</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-pseudodone.html" title="5.2.1. build/pseudodone">
10<link rel="next" href="structure-build-conf-bblayers.conf.html" title="5.2.3. build/conf/bblayers.conf">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.2. build/conf/local.conf">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-conf-local.conf"></a>5.2.2. <code class="filename">build/conf/local.conf</code>
15</h3></div></div></div>
16<p>
17 This file contains all the local user configuration for your build environment.
18 If there is no <code class="filename">local.conf</code> present, it is created from
19 <code class="filename">local.conf.sample</code>.
20 The <code class="filename">local.conf</code> file contains documentation on the various configuration options.
21 Any variable set here overrides any variable set elsewhere within the environment unless
22 that variable is hard-coded within a file (e.g. by using '=' instead of '?=').
23 Some variables are hard-coded for various reasons but these variables are
24 relatively rare.
25 </p>
26<p>
27 Edit this file to set the <code class="filename"><a class="link" href="ref-variables-glos.html#var-MACHINE" title="MACHINE">MACHINE</a></code>
28 for which you want to build, which package types you wish to use
29 (<a class="link" href="ref-variables-glos.html#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES"><code class="filename">PACKAGE_CLASSES</code></a>),
30 where you want to downloaded files
31 (<code class="filename"><a class="link" href="ref-variables-glos.html#var-DL_DIR" title="DL_DIR">DL_DIR</a></code>),
32 and how you want your host machine to use resources
33 (<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
34 <a class="link" href="ref-variables-glos.html#var-PARALLEL_MAKE" title="PARALLEL_MAKE"><code class="filename">PARALLEL_MAKE</code></a>).
35 </p>
36</div></body>
37</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.4. build/conf/sanity_info</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-conf-bblayers.conf.html" title="5.2.3. build/conf/bblayers.conf">
10<link rel="next" href="structure-build-downloads.html" title="5.2.5. build/downloads/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.4. build/conf/sanity_info">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-conf-sanity_info"></a>5.2.4. <code class="filename">build/conf/sanity_info</code>
15</h3></div></div></div>
16<p>
17 This file is created during the build to indicate the state of the sanity checks.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.5. build/downloads/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-conf-sanity_info.html" title="5.2.4. build/conf/sanity_info">
10<link rel="next" href="structure-build-sstate-cache.html" title="5.2.6. build/sstate-cache/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.5. build/downloads/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-downloads"></a>5.2.5. <code class="filename">build/downloads/</code>
15</h3></div></div></div>
16<p>
17 This directory is used for the upstream source tarballs.
18 The directory can be reused by multiple builds or moved to another location.
19 You can control the location of this directory through the
20 <code class="filename"><a class="link" href="ref-variables-glos.html#var-DL_DIR" title="DL_DIR">DL_DIR</a></code> variable.
21 </p>
22</div></body>
23</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.1. build/pseudodone</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build.html" title="5.2. The Build Directory - build/">
10<link rel="next" href="structure-build-conf-local.conf.html" title="5.2.2. build/conf/local.conf">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.1. build/pseudodone">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-pseudodone"></a>5.2.1. <code class="filename">build/pseudodone</code>
15</h3></div></div></div>
16<p>
17 This tag file indicates that the initial pseudo binary was created.
18 The file is built the first time BitBake is invoked.
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.6. build/sstate-cache/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-downloads.html" title="5.2.5. build/downloads/">
10<link rel="next" href="structure-build-tmp.html" title="5.2.7. build/tmp/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.6. build/sstate-cache/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-sstate-cache"></a>5.2.6. <code class="filename">build/sstate-cache/</code>
15</h3></div></div></div>
16<p>
17 This directory is used for the shared state cache.
18 The directory can be reused by multiple builds or moved to another location.
19 You can control the location of this directory through the
20 <code class="filename"><a class="link" href="ref-variables-glos.html#var-SSTATE_DIR" title="SSTATE_DIR">SSTATE_DIR</a></code> variable.
21 </p>
22</div></body>
23</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.8. build/tmp/buildstats/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp.html" title="5.2.7. build/tmp/">
10<link rel="next" href="structure-build-tmp-cache.html" title="5.2.9. build/tmp/cache/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.8. build/tmp/buildstats/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-buildstats"></a>5.2.8. <code class="filename">build/tmp/buildstats/</code>
15</h3></div></div></div>
16<p>
17 This directory stores the build statistics.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.9. build/tmp/cache/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp-buildstats.html" title="5.2.8. build/tmp/buildstats/">
10<link rel="next" href="structure-build-tmp-deploy.html" title="5.2.10. build/tmp/deploy/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.9. build/tmp/cache/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-cache"></a>5.2.9. <code class="filename">build/tmp/cache/</code>
15</h3></div></div></div>
16<p>
17 When BitBake parses the metadata, it creates a cache file of the result that can
18 be used when subsequently running commands.
19 These results are stored here on a per-machine basis.
20 </p>
21</div></body>
22</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.11. build/tmp/deploy/deb/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp-deploy.html" title="5.2.10. build/tmp/deploy/">
10<link rel="next" href="structure-build-tmp-deploy-rpm.html" title="5.2.12. build/tmp/deploy/rpm/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.11. build/tmp/deploy/deb/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-deploy-deb"></a>5.2.11. <code class="filename">build/tmp/deploy/deb/</code>
15</h3></div></div></div>
16<p>
17 This directory receives any <code class="filename">.deb</code> packages produced by
18 the build process.
19 The packages are sorted into feeds for different architecture types.
20 </p>
21</div></body>
22</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.14. build/tmp/deploy/images/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp-deploy-licenses.html" title="5.2.13. build/tmp/deploy/licenses/">
10<link rel="next" href="structure-build-tmp-deploy-ipk.html" title="5.2.15. build/tmp/deploy/ipk/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.14. build/tmp/deploy/images/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-deploy-images"></a>5.2.14. <code class="filename">build/tmp/deploy/images/</code>
15</h3></div></div></div>
16<p>
17 This directory receives complete filesystem images.
18 If you want to flash the resulting image from a build onto a device, look here for the image.
19 </p>
20<p>
21 Be careful when deleting files in this directory.
22 You can safely delete old images from this directory (e.g.
23 <code class="filename">core-image-*</code>, <code class="filename">hob-image-*</code>,
24 etc.).
25 However, the kernel (<code class="filename">*zImage*</code>, <code class="filename">*uImage*</code>, etc.),
26 bootloader and other supplementary files might be deployed here prior to building an
27 image.
28 Because these files, however, are not directly produced from the image, if you
29 delete them they will not be automatically re-created when you build the image again.
30 </p>
31<p>
32 If you do accidentally delete files here, you will need to force them to be
33 re-created.
34 In order to do that, you will need to know the target that produced them.
35 For example, these commands rebuild and re-create the kernel files:
36 </p>
37<pre class="literallayout">
38 $ bitbake -c clean virtual/kernel
39 $ bitbake virtual/kernel
40 </pre>
41<p>
42 </p>
43</div></body>
44</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.15. build/tmp/deploy/ipk/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp-deploy-images.html" title="5.2.14. build/tmp/deploy/images/">
10<link rel="next" href="structure-build-tmp-sysroots.html" title="5.2.16. build/tmp/sysroots/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.15. build/tmp/deploy/ipk/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-deploy-ipk"></a>5.2.15. <code class="filename">build/tmp/deploy/ipk/</code>
15</h3></div></div></div>
16<p>
17 This directory receives <code class="filename">.ipk</code> packages produced by
18 the build process.</p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.13. build/tmp/deploy/licenses/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp-deploy-rpm.html" title="5.2.12. build/tmp/deploy/rpm/">
10<link rel="next" href="structure-build-tmp-deploy-images.html" title="5.2.14. build/tmp/deploy/images/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.13. build/tmp/deploy/licenses/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-deploy-licenses"></a>5.2.13. <code class="filename">build/tmp/deploy/licenses/</code>
15</h3></div></div></div>
16<p>
17 This directory receives package licensing information.
18 For example, the directory contains sub-directories for <code class="filename">bash</code>,
19 <code class="filename">busybox</code>, and <code class="filename">eglibc</code> (among others) that in turn
20 contain appropriate <code class="filename">COPYING</code> license files with other licensing information.
21 </p>
22</div></body>
23</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.12. build/tmp/deploy/rpm/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp-deploy-deb.html" title="5.2.11. build/tmp/deploy/deb/">
10<link rel="next" href="structure-build-tmp-deploy-licenses.html" title="5.2.13. build/tmp/deploy/licenses/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.12. build/tmp/deploy/rpm/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-deploy-rpm"></a>5.2.12. <code class="filename">build/tmp/deploy/rpm/</code>
15</h3></div></div></div>
16<p>
17 This directory receives any <code class="filename">.rpm</code> packages produced by
18 the build process.
19 The packages are sorted into feeds for different architecture types.
20 </p>
21</div></body>
22</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.10. build/tmp/deploy/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp-cache.html" title="5.2.9. build/tmp/cache/">
10<link rel="next" href="structure-build-tmp-deploy-deb.html" title="5.2.11. build/tmp/deploy/deb/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.10. build/tmp/deploy/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-deploy"></a>5.2.10. <code class="filename">build/tmp/deploy/</code>
15</h3></div></div></div>
16<p>
17 This directory contains any 'end result' output from the OpenEmbedded build process.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.18. build/tmp/log/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp-stamps.html" title="5.2.17. build/tmp/stamps/">
10<link rel="next" href="structure-build-tmp-pkgdata.html" title="5.2.19. build/tmp/pkgdata/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.18. build/tmp/log/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-log"></a>5.2.18. <code class="filename">build/tmp/log/</code>
15</h3></div></div></div>
16<p>
17 This directory contains general logs that are not otherwise placed using the
18 package's <code class="filename"><a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>.
19 Examples of logs are the output from the <code class="filename">check_pkg</code> or
20 <code class="filename">distro_check</code> tasks.
21 Running a build does not necessarily mean this directory is created.
22 </p>
23</div></body>
24</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.19. build/tmp/pkgdata/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp-log.html" title="5.2.18. build/tmp/log/">
10<link rel="next" href="structure-build-tmp-work.html" title="5.2.20. build/tmp/work/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.19. build/tmp/pkgdata/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-pkgdata"></a>5.2.19. <code class="filename">build/tmp/pkgdata/</code>
15</h3></div></div></div>
16<p>
17 This directory contains intermediate packaging data that is used later in the packaging process.
18 For more information, see the "<a class="link" href="ref-classes-package.html" title="7.13. Packaging - package*.bbclass">Packaging - package*.bbclass</a>" section.
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.17. build/tmp/stamps/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp-sysroots.html" title="5.2.16. build/tmp/sysroots/">
10<link rel="next" href="structure-build-tmp-log.html" title="5.2.18. build/tmp/log/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.17. build/tmp/stamps/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-stamps"></a>5.2.17. <code class="filename">build/tmp/stamps/</code>
15</h3></div></div></div>
16<p>
17 This directory holds information that that BitBake uses for accounting purposes
18 to track what tasks have run and when they have run.
19 The directory is sub-divided by architecture.
20 The files in the directory are empty of data.
21 However, BitBake uses the filenames and timestamps for tracking purposes.
22 </p>
23</div></body>
24</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.16. build/tmp/sysroots/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp-deploy-ipk.html" title="5.2.15. build/tmp/deploy/ipk/">
10<link rel="next" href="structure-build-tmp-stamps.html" title="5.2.17. build/tmp/stamps/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.16. build/tmp/sysroots/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-sysroots"></a>5.2.16. <code class="filename">build/tmp/sysroots/</code>
15</h3></div></div></div>
16<p>
17 This directory contains shared header files and libraries as well as other shared
18 data.
19 Packages that need to share output with other packages do so within this directory.
20 The directory is subdivided by architecture so multiple builds can run within
21 the one Build Directory.
22 </p>
23</div></body>
24</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.20. build/tmp/work/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-tmp-pkgdata.html" title="5.2.19. build/tmp/pkgdata/">
10<link rel="next" href="structure-meta.html" title="5.3. The Metadata - meta/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.20. build/tmp/work/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp-work"></a>5.2.20. <code class="filename">build/tmp/work/</code>
15</h3></div></div></div>
16<p>
17 This directory contains architecture-specific work sub-directories for packages built by BitBake.
18 All tasks execute from a work directory.
19 For example, the source for a particular package is unpacked, patched, configured and compiled all
20 within its own work directory.
21 Within the work directory, organization is based on the package group for which the source
22 is being compiled.
23 </p>
24<p>
25 It is worth considering the structure of a typical work directory.
26 As an example, consider the <code class="filename">linux-yocto-kernel-3.0</code>
27 on the machine <code class="filename">qemux86</code>
28 built within the Yocto Project.
29 For this package, a work directory of
30 <code class="filename">tmp/work/qemux86-poky-linux/linux-yocto-3.0+git1+&lt;.....&gt;</code>,
31 referred to as <code class="filename"><a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, is created.
32 Within this directory, the source is unpacked to
33 <code class="filename">linux-qemux86-standard-build</code> and then patched by Quilt
34 (see the
35 "<a class="link" href="../dev-manual/using-a-quilt-workflow.html" target="_self">Modifying Package
36 Source Code with Quilt</a>" section in the Yocto Project Development Manual.
37 Within the <code class="filename">linux-qemux86-standard-build</code> directory,
38 standard Quilt directories <code class="filename">linux-3.0/patches</code>
39 and <code class="filename">linux-3.0/.pc</code> are created,
40 and standard Quilt commands can be used.
41 </p>
42<p>
43 There are other directories generated within WORKDIR.
44 The most important directory is WORKDIR<code class="filename">/temp/</code>, which has log files for each
45 task (<code class="filename">log.do_*.pid</code>) and contains the scripts BitBake runs for
46 each task (<code class="filename">run.do_*.pid</code>).
47 The WORKDIR<code class="filename">/image/</code> directory is where "make
48 install" places its output that is then split into sub-packages
49 within WORKDIR<code class="filename">/packages-split/</code>.
50 </p>
51</div></body>
52</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2.7. build/tmp/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-build.html" title="5.2. The Build Directory - build/">
9<link rel="prev" href="structure-build-sstate-cache.html" title="5.2.6. build/sstate-cache/">
10<link rel="next" href="structure-build-tmp-buildstats.html" title="5.2.8. build/tmp/buildstats/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.2.7. build/tmp/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-build-tmp"></a>5.2.7. <code class="filename">build/tmp/</code>
15</h3></div></div></div>
16<p>
17 This directory receives all the OpenEmbedded build system's output.
18 BitBake creates this directory if it does not exist.
19 As a last resort, to clean up a build and start it from scratch (other than the downloads),
20 you can remove everything in the <code class="filename">tmp</code> directory or get rid of the
21 directory completely.
22 If you do, you should also completely remove the <code class="filename">build/sstate-cache</code>
23 directory as well.
24 </p>
25</div></body>
26</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.2. The Build Directory - build/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-structure.html" title="Chapter 5. Source Directory Structure">
9<link rel="prev" href="structure-basic-top-level.html" title="5.1.11. LICENSE, README, and README.hardware">
10<link rel="next" href="structure-build-pseudodone.html" title="5.2.1. build/pseudodone">
11</head>
12<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">
13<a name="structure-build"></a>5.2. The Build Directory - <code class="filename">build/</code>
14</h2></div></div></div></div></body>
15</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.1.1. bitbake/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-core.html" title="5.1. Top level core components">
9<link rel="prev" href="structure-core.html" title="5.1. Top level core components">
10<link rel="next" href="structure-core-build.html" title="5.1.2. build/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.1. bitbake/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-core-bitbake"></a>5.1.1. <code class="filename">bitbake/</code>
15</h3></div></div></div>
16<p>
17 The <a class="ulink" href="source-directory" target="_self">Source Directory</a>
18 includes a copy of BitBake for ease of use.
19 The copy usually matches the current stable BitBake release from the BitBake project.
20 BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks
21 defined by that data.
22 Failures are usually from the metadata and not from BitBake itself.
23 Consequently, most users do not need to worry about BitBake.
24 </p>
25<p>
26 When you run the <code class="filename">bitbake</code> command, the wrapper script in
27 <code class="filename">scripts/</code> is executed to run the main BitBake executable,
28 which resides in the <code class="filename">bitbake/bin/</code> directory.
29 Sourcing the <a class="link" href="structure-core-script.html" title="5.1.10. oe-init-build-env">oe-init-build-env</a>
30 script places the <code class="filename">scripts</code> and <code class="filename">bitbake/bin</code>
31 directories (in that order) into the shell's <code class="filename">PATH</code> environment
32 variable.
33 </p>
34<p>
35 For more information on BitBake, see the BitBake documentation
36 inculded in the <code class="filename">bitbake/doc/manual</code> directory of the
37 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>.
38 </p>
39</div></body>
40</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.1.2. build/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-core.html" title="5.1. Top level core components">
9<link rel="prev" href="structure-core-bitbake.html" title="5.1.1. bitbake/">
10<link rel="next" href="handbook.html" title="5.1.3. documentation">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.2. build/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-core-build"></a>5.1.2. <code class="filename">build/</code>
15</h3></div></div></div>
16<p>
17 This directory contains user configuration files and the output
18 generated by the OpenEmbedded build system in its standard configuration where
19 the source tree is combined with the output.
20 The <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>
21 is created initially when you <code class="filename">source</code>
22 the OpenEmbedded build environment setup script <code class="filename">oe-init-build-env</code>.
23 </p>
24<p>
25 It is also possible to place output and configuration
26 files in a directory separate from the
27 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>
28 by providing a directory name when you <code class="filename">source</code>
29 the setup script.
30 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>.
31 </p>
32</div></body>
33</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.1.6. meta-yocto-bsp/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-core.html" title="5.1. Top level core components">
9<link rel="prev" href="structure-core-meta-yocto.html" title="5.1.5. meta-yocto/">
10<link rel="next" href="structure-meta-hob.html" title="5.1.7. meta-hob/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.6. meta-yocto-bsp/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-core-meta-yocto-bsp"></a>5.1.6. <code class="filename">meta-yocto-bsp/</code>
15</h3></div></div></div>
16<p>
17 This directory contains the Yocto Project reference
18 hardware BSPs.
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.1.5. meta-yocto/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-core.html" title="5.1. Top level core components">
9<link rel="prev" href="structure-core-meta.html" title="5.1.4. meta/">
10<link rel="next" href="structure-core-meta-yocto-bsp.html" title="5.1.6. meta-yocto-bsp/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.5. meta-yocto/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-core-meta-yocto"></a>5.1.5. <code class="filename">meta-yocto/</code>
15</h3></div></div></div>
16<p>
17 This directory contains the configuration for the Poky
18 reference distribution.
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.1.4. meta/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-core.html" title="5.1. Top level core components">
9<link rel="prev" href="handbook.html" title="5.1.3. documentation">
10<link rel="next" href="structure-core-meta-yocto.html" title="5.1.5. meta-yocto/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.4. meta/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-core-meta"></a>5.1.4. <code class="filename">meta/</code>
15</h3></div></div></div>
16<p>
17 This directory contains the OpenEmbedded Core metadata.
18 The directory holds recipes, common classes, and machine
19 configuration for emulated targets (qemux86, qemuarm,
20 and so on.)
21 </p>
22</div></body>
23</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.1.10. oe-init-build-env</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-core.html" title="5.1. Top level core components">
9<link rel="prev" href="structure-core-scripts.html" title="5.1.9. scripts/">
10<link rel="next" href="structure-basic-top-level.html" title="5.1.11. LICENSE, README, and README.hardware">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.10. oe-init-build-env">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-core-script"></a>5.1.10. <code class="filename">oe-init-build-env</code>
15</h3></div></div></div>
16<p>
17 This script sets up the OpenEmbedded build environment.
18 Running this script with the <code class="filename">source</code> command in
19 a shell makes changes to <code class="filename">PATH</code> and sets other core BitBake variables based on the
20 current working directory.
21 You need to run this script before running BitBake commands.
22 The script uses other scripts within the <code class="filename">scripts</code> directory to do
23 the bulk of the work.
24 </p>
25<p>
26 By default, running this script without a Build Directory argument creates the
27 <code class="filename">build</code> directory.
28 If you provide a Build Directory argument when you <code class="filename">source</code>
29 the script, you direct OpenEmbedded build system to create a
30 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a> of your choice.
31 For example, the following command creates a Build Directory named
32 <code class="filename">mybuilds</code> that is outside of the
33 <a class="link" href="../dev-manual/source-directory.html" target="_self">Source Directory</a>:
34 </p>
35<pre class="literallayout">
36 $ source oe-init-build-env ~/mybuilds
37 </pre>
38<p>
39 </p>
40<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
41<h3 class="title">Note</h3>
42 The OpenEmbedded build system does not support file or directory names that
43 contain spaces.
44 If you attempt to run the <code class="filename">oe-init-build-env</code> script
45 from a Source Directory that contains spaces in either the filenames
46 or directory names, the script returns an error indicating no such
47 file or directory.
48 Be sure to use a Source Directory free of names containing spaces.
49 </div>
50<p>
51 </p>
52</div></body>
53</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.1.9. scripts/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-core.html" title="5.1. Top level core components">
9<link rel="prev" href="structure-meta-skeleton.html" title="5.1.8. meta-skeleton/">
10<link rel="next" href="structure-core-script.html" title="5.1.10. oe-init-build-env">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.9. scripts/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-core-scripts"></a>5.1.9. <code class="filename">scripts/</code>
15</h3></div></div></div>
16<p>
17 This directory contains various integration scripts that implement
18 extra functionality in the Yocto Project environment (e.g. QEMU scripts).
19 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
20 directory to the shell's <code class="filename">PATH</code> environment variable.
21 </p>
22<p>
23 The <code class="filename">scripts</code> directory has useful scripts that assist contributing
24 back to the Yocto Project, such as <code class="filename">create_pull_request</code> and
25 <code class="filename">send_pull_request</code>.
26 </p>
27</div></body>
28</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.1. Top level core components</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-structure.html" title="Chapter 5. Source Directory Structure">
9<link rel="prev" href="ref-structure.html" title="Chapter 5. Source Directory Structure">
10<link rel="next" href="structure-core-bitbake.html" title="5.1.1. bitbake/">
11</head>
12<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">
13<a name="structure-core"></a>5.1. Top level core components</h2></div></div></div></div></body>
14</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.1. meta/classes/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta.html" title="5.3. The Metadata - meta/">
10<link rel="next" href="structure-meta-conf.html" title="5.3.2. meta/conf/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.1. meta/classes/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-classes"></a>5.3.1. <code class="filename">meta/classes/</code>
15</h3></div></div></div>
16<p>
17 This directory contains the <code class="filename">*.bbclass</code> files.
18 Class files are used to abstract common code so it can be reused by multiple
19 packages.
20 Every package inherits the <code class="filename">base.bbclass</code> file.
21 Examples of other important classes are <code class="filename">autotools.bbclass</code>, which
22 in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
23 Another example is <code class="filename">kernel.bbclass</code> that contains common code and functions
24 for working with the Linux kernel.
25 Functions like image generation or packaging also have their specific class files
26 such as <code class="filename">image.bbclass</code>, <code class="filename">rootfs_*.bbclass</code> and
27 <code class="filename">package*.bbclass</code>.
28 </p>
29</div></body>
30</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.4. meta/conf/distro/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-conf-machine.html" title="5.3.3. meta/conf/machine/">
10<link rel="next" href="structure-meta-recipes-bsp.html" title="5.3.5. meta/recipes-bsp/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.4. meta/conf/distro/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-conf-distro"></a>5.3.4. <code class="filename">meta/conf/distro/</code>
15</h3></div></div></div>
16<p>
17 Any distribution-specific configuration is controlled from this directory.
18 For the Yocto Project, the <code class="filename">defaultsetup.conf</code> is the main file here.
19 This directory includes the versions and the
20 <code class="filename">SRCDATE</code> definitions for applications that are configured here.
21 An example of an alternative configuration might be <code class="filename">poky-bleeding.conf</code>.
22 Although this file mainly inherits its configuration from Poky.
23 </p>
24</div></body>
25</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.3. meta/conf/machine/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-conf.html" title="5.3.2. meta/conf/">
10<link rel="next" href="structure-meta-conf-distro.html" title="5.3.4. meta/conf/distro/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.3. meta/conf/machine/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-conf-machine"></a>5.3.3. <code class="filename">meta/conf/machine/</code>
15</h3></div></div></div>
16<p>
17 This directory contains all the machine configuration files.
18 If you set <code class="filename">MACHINE="qemux86"</code>,
19 the OpenEmbedded build system looks for a <code class="filename">qemux86.conf</code> file in this
20 directory.
21 The <code class="filename">include</code> directory contains various data common to multiple machines.
22 If you want to add support for a new machine to the Yocto Project, look in this directory.
23 </p>
24</div></body>
25</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.2. meta/conf/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-classes.html" title="5.3.1. meta/classes/">
10<link rel="next" href="structure-meta-conf-machine.html" title="5.3.3. meta/conf/machine/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.2. meta/conf/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-conf"></a>5.3.2. <code class="filename">meta/conf/</code>
15</h3></div></div></div>
16<p>
17 This directory contains the core set of configuration files that start from
18 <code class="filename">bitbake.conf</code> and from which all other configuration
19 files are included.
20 See the include statements at the end of the file and you will note that even
21 <code class="filename">local.conf</code> is loaded from there.
22 While <code class="filename">bitbake.conf</code> sets up the defaults, you can often override
23 these by using the (<code class="filename">local.conf</code>) file, machine file or
24 the distribution configuration file.
25 </p>
26</div></body>
27</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.1.7. meta-hob/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-core.html" title="5.1. Top level core components">
9<link rel="prev" href="structure-core-meta-yocto-bsp.html" title="5.1.6. meta-yocto-bsp/">
10<link rel="next" href="structure-meta-skeleton.html" title="5.1.8. meta-skeleton/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.7. meta-hob/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-hob"></a>5.1.7. <code class="filename">meta-hob/</code>
15</h3></div></div></div>
16<p>
17 This directory contains template recipes used by the
18 <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_self">Hob</a>
19 build UI.
20 </p>
21</div></body>
22</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.5. meta/recipes-bsp/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-conf-distro.html" title="5.3.4. meta/conf/distro/">
10<link rel="next" href="structure-meta-recipes-connectivity.html" title="5.3.6. meta/recipes-connectivity/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.5. meta/recipes-bsp/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-bsp"></a>5.3.5. <code class="filename">meta/recipes-bsp/</code>
15</h3></div></div></div>
16<p>
17 This directory contains anything linking to specific hardware or hardware
18 configuration information such as "u-boot" and "grub".
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.6. meta/recipes-connectivity/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-bsp.html" title="5.3.5. meta/recipes-bsp/">
10<link rel="next" href="structure-meta-recipes-core.html" title="5.3.7. meta/recipes-core/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.6. meta/recipes-connectivity/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-connectivity"></a>5.3.6. <code class="filename">meta/recipes-connectivity/</code>
15</h3></div></div></div>
16<p>
17 This directory contains libraries and applications related to communication with other devices.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.7. meta/recipes-core/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-connectivity.html" title="5.3.6. meta/recipes-connectivity/">
10<link rel="next" href="structure-meta-recipes-devtools.html" title="5.3.8. meta/recipes-devtools/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.7. meta/recipes-core/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-core"></a>5.3.7. <code class="filename">meta/recipes-core/</code>
15</h3></div></div></div>
16<p>
17 This directory contains what is needed to build a basic working Linux image
18 including commonly used dependencies.
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.8. meta/recipes-devtools/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-core.html" title="5.3.7. meta/recipes-core/">
10<link rel="next" href="structure-meta-recipes-extended.html" title="5.3.9. meta/recipes-extended/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.8. meta/recipes-devtools/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-devtools"></a>5.3.8. <code class="filename">meta/recipes-devtools/</code>
15</h3></div></div></div>
16<p>
17 This directory contains tools that are primarily used by the build system.
18 The tools, however, can also be used on targets.
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.9. meta/recipes-extended/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-devtools.html" title="5.3.8. meta/recipes-devtools/">
10<link rel="next" href="structure-meta-recipes-gnome.html" title="5.3.10. meta/recipes-gnome/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.9. meta/recipes-extended/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-extended"></a>5.3.9. <code class="filename">meta/recipes-extended/</code>
15</h3></div></div></div>
16<p>
17 This directory contains non-essential applications that add features compared to the
18 alternatives in core.
19 You might need this directory for full tool functionality or for Linux Standard Base (LSB)
20 compliance.
21 </p>
22</div></body>
23</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.10. meta/recipes-gnome/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-extended.html" title="5.3.9. meta/recipes-extended/">
10<link rel="next" href="structure-meta-recipes-graphics.html" title="5.3.11. meta/recipes-graphics/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.10. meta/recipes-gnome/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-gnome"></a>5.3.10. <code class="filename">meta/recipes-gnome/</code>
15</h3></div></div></div>
16<p>
17 This directory contains all things related to the GTK+ application framework.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.11. meta/recipes-graphics/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-gnome.html" title="5.3.10. meta/recipes-gnome/">
10<link rel="next" href="structure-meta-recipes-kernel.html" title="5.3.12. meta/recipes-kernel/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.11. meta/recipes-graphics/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-graphics"></a>5.3.11. <code class="filename">meta/recipes-graphics/</code>
15</h3></div></div></div>
16<p>
17 This directory contains X and other graphically related system libraries
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.12. meta/recipes-kernel/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-graphics.html" title="5.3.11. meta/recipes-graphics/">
10<link rel="next" href="structure-meta-recipes-multimedia.html" title="5.3.13. meta/recipes-multimedia/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.12. meta/recipes-kernel/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-kernel"></a>5.3.12. <code class="filename">meta/recipes-kernel/</code>
15</h3></div></div></div>
16<p>
17 This directory contains the kernel and generic applications and libraries that
18 have strong kernel dependencies.
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.13. meta/recipes-multimedia/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-kernel.html" title="5.3.12. meta/recipes-kernel/">
10<link rel="next" href="structure-meta-recipes-qt.html" title="5.3.14. meta/recipes-qt/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.13. meta/recipes-multimedia/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-multimedia"></a>5.3.13. <code class="filename">meta/recipes-multimedia/</code>
15</h3></div></div></div>
16<p>
17 This directory contains codecs and support utilities for audio, images and video.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.14. meta/recipes-qt/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-multimedia.html" title="5.3.13. meta/recipes-multimedia/">
10<link rel="next" href="structure-meta-recipes-rt.html" title="5.3.15. meta/recipes-rt/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.14. meta/recipes-qt/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-qt"></a>5.3.14. <code class="filename">meta/recipes-qt/</code>
15</h3></div></div></div>
16<p>
17 This directory contains all things related to the Qt application framework.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.15. meta/recipes-rt/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-qt.html" title="5.3.14. meta/recipes-qt/">
10<link rel="next" href="structure-meta-recipes-sato.html" title="5.3.16. meta/recipes-sato/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.15. meta/recipes-rt/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-rt"></a>5.3.15. <code class="filename">meta/recipes-rt/</code>
15</h3></div></div></div>
16<p>
17 This directory contains package and image recipes for using and testing
18 the <code class="filename">PREEMPT_RT</code> kernel.
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.16. meta/recipes-sato/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-rt.html" title="5.3.15. meta/recipes-rt/">
10<link rel="next" href="structure-meta-recipes-support.html" title="5.3.17. meta/recipes-support/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.16. meta/recipes-sato/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-sato"></a>5.3.16. <code class="filename">meta/recipes-sato/</code>
15</h3></div></div></div>
16<p>
17 This directory contains the Sato demo/reference UI/UX and its associated applications
18 and configuration data.
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.17. meta/recipes-support/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-sato.html" title="5.3.16. meta/recipes-sato/">
10<link rel="next" href="structure-meta-site.html" title="5.3.18. meta/site/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.17. meta/recipes-support/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-support"></a>5.3.17. <code class="filename">meta/recipes-support/</code>
15</h3></div></div></div>
16<p>
17 This directory contains recipes that used by other recipes, but that are not directly
18 included in images (i.e. dependencies of other recipes).
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.19. meta/recipes.txt</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-site.html" title="5.3.18. meta/site/">
10<link rel="next" href="ref-bitbake.html" title="Chapter 6. BitBake">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.19. meta/recipes.txt">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-recipes-txt"></a>5.3.19. <code class="filename">meta/recipes.txt</code>
15</h3></div></div></div>
16<p>
17 This file is a description of the contents of <code class="filename">recipes-*</code>.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3.18. meta/site/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-meta.html" title="5.3. The Metadata - meta/">
9<link rel="prev" href="structure-meta-recipes-support.html" title="5.3.17. meta/recipes-support/">
10<link rel="next" href="structure-meta-recipes-txt.html" title="5.3.19. meta/recipes.txt">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3.18. meta/site/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-site"></a>5.3.18. <code class="filename">meta/site/</code>
15</h3></div></div></div>
16<p>
17 This directory contains a list of cached results for various architectures.
18 Because certain "autoconf" test results cannot be determined when cross-compiling due to
19 the tests not able to run on a live system, the information in this directory is
20 passed to "autoconf" for the various architectures.
21 </p>
22</div></body>
23</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.1.8. meta-skeleton/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="structure-core.html" title="5.1. Top level core components">
9<link rel="prev" href="structure-meta-hob.html" title="5.1.7. meta-hob/">
10<link rel="next" href="structure-core-scripts.html" title="5.1.9. scripts/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.1.8. meta-skeleton/">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="structure-meta-skeleton"></a>5.1.8. <code class="filename">meta-skeleton/</code>
15</h3></div></div></div>
16<p>
17 This directory contains template recipes for BSP and kernel development.
18 </p>
19</div></body>
20</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>5.3. The Metadata - meta/</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="ref-structure.html" title="Chapter 5. Source Directory Structure">
9<link rel="prev" href="structure-build-tmp-work.html" title="5.2.20. build/tmp/work/">
10<link rel="next" href="structure-meta-classes.html" title="5.3.1. meta/classes/">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="5.3. The Metadata - meta/">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="structure-meta"></a>5.3. The Metadata - <code class="filename">meta/</code>
15</h2></div></div></div>
16<p>
17 As mentioned previously, metadata is the core of the Yocto Project.
18 Metadata has several important subdivisions:
19 </p>
20</div></body>
21</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.3.1. Support</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="x32.html" title="3.3. x32">
9<link rel="prev" href="x32.html" title="3.3. x32">
10<link rel="next" href="future-development-and-limitations.html" title="3.3.2. Future Development and Limitations">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.1. Support">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="support"></a>3.3.1. Support</h3></div></div></div>
15<p>
16 While the x32 psABI specifications are not fully finalized, this Yocto Project
17 release supports current development specifications of x32 psABI.
18 As of this release of the Yocto Project, x32 psABI support exists as follows:
19 </p>
20<div class="itemizedlist"><ul class="itemizedlist" type="disc">
21<li class="listitem"><p>You can create packages and images in x32 psABI format on x86_64 architecture targets.
22 </p></li>
23<li class="listitem"><p>You can use the x32 psABI support through the <code class="filename">meta-x32</code>
24 layer on top of the OE-core/Yocto layer.</p></li>
25<li class="listitem"><p>The toolchain from the <code class="filename">experimental/meta-x32</code> layer
26 is used for building x32 psABI program binaries.</p></li>
27<li class="listitem"><p>You can successfully build many recipes with the x32 toolchain.</p></li>
28<li class="listitem"><p>You can create and boot <code class="filename">core-image-minimal</code> and
29 <code class="filename">core-image-sato</code> images.</p></li>
30</ul></div>
31<p>
32 </p>
33</div></body>
34</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 3. Technical Details</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="examining-build-history-information.html" title="2.4.2.4. Examining Build History Information">
10<link rel="next" href="usingpoky-components.html" title="3.1. Yocto Project Components">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 3. Technical Details">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="technical-details"></a>Chapter 3. Technical Details</h2></div></div></div>
15<div class="toc">
16<p><b>Table of Contents</b></p>
17<dl>
18<dt><span class="section"><a href="usingpoky-components.html">3.1. Yocto Project Components</a></span></dt>
19<dd><dl>
20<dt><span class="section"><a href="usingpoky-components-bitbake.html">3.1.1. BitBake</a></span></dt>
21<dt><span class="section"><a href="usingpoky-components-metadata.html">3.1.2. Metadata (Recipes)</a></span></dt>
22<dt><span class="section"><a href="usingpoky-components-classes.html">3.1.3. Classes</a></span></dt>
23<dt><span class="section"><a href="usingpoky-components-configuration.html">3.1.4. Configuration</a></span></dt>
24</dl></dd>
25<dt><span class="section"><a href="shared-state-cache.html">3.2. Shared State Cache</a></span></dt>
26<dd><dl>
27<dt><span class="section"><a href="overall-architecture.html">3.2.1. Overall Architecture</a></span></dt>
28<dt><span class="section"><a href="checksums.html">3.2.2. Checksums (Signatures)</a></span></dt>
29<dt><span class="section"><a href="shared-state.html">3.2.3. Shared State</a></span></dt>
30<dt><span class="section"><a href="tips-and-tricks.html">3.2.4. Tips and Tricks</a></span></dt>
31</dl></dd>
32<dt><span class="section"><a href="x32.html">3.3. x32</a></span></dt>
33<dd><dl>
34<dt><span class="section"><a href="support.html">3.3.1. Support</a></span></dt>
35<dt><span class="section"><a href="future-development-and-limitations.html">3.3.2. Future Development and Limitations</a></span></dt>
36<dt><span class="section"><a href="using-x32-right-now.html">3.3.3. Using x32 Right Now</a></span></dt>
37</dl></dd>
38<dt><span class="section"><a href="licenses.html">3.4. Licenses</a></span></dt>
39<dd><dl>
40<dt><span class="section"><a href="usingpoky-configuring-LIC_FILES_CHKSUM.html">3.4.1. Tracking License Changes</a></span></dt>
41<dt><span class="section"><a href="enabling-commercially-licensed-recipes.html">3.4.2. Enabling Commercially Licensed Recipes</a></span></dt>
42</dl></dd>
43</dl>
44</div>
45<p>
46 This chapter provides technical details for various parts of the Yocto Project.
47 Currently, topics include Yocto Project components and shared state (sstate) cache.
48 </p>
49</div></body>
50</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.2.4. Tips and Tricks</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="shared-state-cache.html" title="3.2. Shared State Cache">
9<link rel="prev" href="shared-state.html" title="3.2.3. Shared State">
10<link rel="next" href="debugging.html" title="3.2.4.1. Debugging">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.2.4. Tips and Tricks">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="tips-and-tricks"></a>3.2.4. Tips and Tricks</h3></div></div></div>
15<p>
16 The code in the build system that supports incremental builds is not
17 simple code.
18 This section presents some tips and tricks that help you work around
19 issues related to shared state code.
20 </p>
21</div></body>
22</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>1.3.2.1. Ubuntu</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="required-packages-for-the-host-development-system.html" title="1.3.2. Required Packages for the Host Development System">
9<link rel="prev" href="required-packages-for-the-host-development-system.html" title="1.3.2. Required Packages for the Host Development System">
10<link rel="next" href="fedora-packages.html" title="1.3.2.2. Fedora Packages">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="1.3.2.1. Ubuntu">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="ubuntu-packages"></a>1.3.2.1. Ubuntu</h4></div></div></div>
15<p>
16 The following list shows the required packages by function
17 given a supported Ubuntu Linux distribution:
18 </p>
19<div class="itemizedlist"><ul class="itemizedlist" type="disc">
20<li class="listitem">
21<p><span class="emphasis"><em>Essentials:</em></span>
22 Packages needed to build an image on a headless
23 system:
24 </p>
25<pre class="literallayout">
26 $ sudo apt-get install gawk wget git-core diffstat unzip texinfo \
27 build-essential chrpath
28 </pre>
29</li>
30<li class="listitem">
31<p><span class="emphasis"><em>Graphical Extras:</em></span>
32 Packages recommended if the host system has graphics support:
33 </p>
34<pre class="literallayout">
35 $ sudo apt-get install libsdl1.2-dev xterm
36 </pre>
37</li>
38<li class="listitem">
39<p><span class="emphasis"><em>Documentation:</em></span>
40 Packages needed if you are going to build out the
41 Yocto Project documentation manuals:
42 </p>
43<pre class="literallayout">
44 $ sudo apt-get install make xsltproc docbook-utils fop
45 </pre>
46</li>
47<li class="listitem">
48<p><span class="emphasis"><em>ADT Installer Extras:</em></span>
49 Packages needed if you are going to be using the
50 <a class="link" href="../adt-manual/using-the-adt-installer.html" target="_self">Application Development Toolkit (ADT) Installer</a>:
51 </p>
52<pre class="literallayout">
53 $ sudo apt-get install autoconf automake libtool libglib2.0-dev
54 </pre>
55</li>
56</ul></div>
57<p>
58 </p>
59</div></body>
60</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.4.2. Understanding What the Build History Contains</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="maintaining-build-output-quality.html" title="2.4. Maintaining Build Output Quality">
9<link rel="prev" href="enabling-and-disabling-build-history.html" title="2.4.1. Enabling and Disabling Build History">
10<link rel="next" href="build-history-package-information.html" title="2.4.2.1. Build History Package Information">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.4.2. Understanding What the Build History Contains">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="understanding-what-the-build-history-contains"></a>2.4.2. Understanding What the Build History Contains</h3></div></div></div>
15<p>
16 Build history information is kept in
17 <a class="link" href="ref-variables-glos.html#var-TMPDIR" title="TMPDIR"><code class="filename">$TMPDIR</code></a><code class="filename">/buildhistory</code>
18 in the Build Directory.
19 The following is an example abbreviated listing:
20 </p>
21<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>
22<p>
23 </p>
24</div></body>
25</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.4.2.3. Using Build History to Gather Image Information Only</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="understanding-what-the-build-history-contains.html" title="2.4.2. Understanding What the Build History Contains">
9<link rel="prev" href="build-history-image-information.html" title="2.4.2.2. Build History Image Information">
10<link rel="next" href="examining-build-history-information.html" title="2.4.2.4. Examining Build History Information">
11</head>
12<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">
13<div class="titlepage"><div><div><h4 class="title">
14<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>
15<p>
16 As you can see, build history produces image information,
17 including dependency graphs, so you can see why something
18 was pulled into the image.
19 If you are just interested in this information and not
20 interested in collecting history or any package information,
21 you can enable writing only image information without
22 any history by adding the following
23 to your <code class="filename">conf/local.conf</code> file found in the
24 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>:
25 </p>
26<pre class="literallayout">
27 INHERIT += "buildhistory"
28 BUILDHISTORY_COMMIT = "0"
29 BUILDHISTORY_FEATURES = "image"
30 </pre>
31<p>
32 </p>
33</div></body>
34</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.3.3. Using x32 Right Now</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="x32.html" title="3.3. x32">
9<link rel="prev" href="future-development-and-limitations.html" title="3.3.2. Future Development and Limitations">
10<link rel="next" href="licenses.html" title="3.4. Licenses">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3.3. Using x32 Right Now">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="using-x32-right-now"></a>3.3.3. Using x32 Right Now</h3></div></div></div>
15<p>
16 Despite the fact the x32 psABI support is in development state for this release of the
17 Yocto Project, you can follow these steps to use the x32 spABI:
18 </p>
19<div class="itemizedlist"><ul class="itemizedlist" type="disc">
20<li class="listitem"><p>Add the <code class="filename">experimental/meta-x32</code> layer to your local
21 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a>.
22 You can find the <code class="filename">experimental/meta-x32</code> source repository at
23 <a class="ulink" href="http://git.yoctoproject.org" target="_self">http://git.yoctoproject.org</a>.</p></li>
24<li class="listitem">
25<p>Edit your <code class="filename">conf/bblayers.conf</code> file so that it includes
26 the <code class="filename">meta-x32</code>.
27 Here is an example:
28 </p>
29<pre class="literallayout">
30 BBLAYERS ?= " \
31 /home/nitin/prj/poky.git/meta \
32 /home/nitin/prj/poky.git/meta-yocto \
33 /home/nitin/prj/poky.git/meta-yocto-bsp \
34 /home/nitin/prj/meta-x32.git \
35 "
36 </pre>
37</li>
38<li class="listitem">
39<p>Enable the x32 psABI tuning file for <code class="filename">x86_64</code>
40 machines by editing the <code class="filename">conf/local.conf</code> like this:
41 </p>
42<pre class="literallayout">
43 MACHINE = "qemux86-64"
44 DEFAULTTUNE = "x86-64-x32"
45 baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
46 or 'INVALID'), True) or 'lib'}"
47 #MACHINE = "atom-pc"
48 #DEFAULTTUNE = "core2-64-x32"
49 </pre>
50</li>
51<li class="listitem">
52<p>As usual, use BitBake to build an image that supports the x32 psABI.
53 Here is an example:
54 </p>
55<pre class="literallayout">
56 $ bitake core-image-sato
57 </pre>
58</li>
59<li class="listitem">
60<p>As usual, run your image using QEMU:
61 </p>
62<pre class="literallayout">
63 $ runqemu qemux86-64 core-image-sato
64 </pre>
65</li>
66</ul></div>
67<p>
68 </p>
69</div></body>
70</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.4.1.2. Explanation of Syntax</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.4.1. Tracking License Changes">
9<link rel="prev" href="usingpoky-specifying-LIC_FILES_CHKSUM.html" title="3.4.1.1. Specifying the LIC_FILES_CHKSUM Variable">
10<link rel="next" href="enabling-commercially-licensed-recipes.html" title="3.4.2. Enabling Commercially Licensed Recipes">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4.1.2. Explanation of Syntax">
13<div class="titlepage"><div><div><h4 class="title">
14<a name="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"></a>3.4.1.2. Explanation of Syntax</h4></div></div></div>
15<p>
16 As mentioned in the previous section, the
17 <code class="filename">LIC_FILES_CHKSUM</code> variable lists all the
18 important files that contain the license text for the source code.
19 It is possible to specify a checksum for an entire file, or a specific section of a
20 file (specified by beginning and ending line numbers with the "beginline" and "endline"
21 parameters, respectively).
22 The latter is useful for source files with a license notice header,
23 README documents, and so forth.
24 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
25 first line of the file.
26 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
27 ends with the last line of the file.
28 </p>
29<p>
30 The "md5" parameter stores the md5 checksum of the license text.
31 If the license text changes in any way as compared to this parameter
32 then a mismatch occurs.
33 This mismatch triggers a build failure and notifies the developer.
34 Notification allows the developer to review and address the license text changes.
35 Also note that if a mismatch occurs during the build, the correct md5
36 checksum is placed in the build log and can be easily copied to the recipe.
37 </p>
38<p>
39 There is no limit to how many files you can specify using the
40 <code class="filename">LIC_FILES_CHKSUM</code> variable.
41 Generally, however, every project requires a few specifications for license tracking.
42 Many projects have a "COPYING" file that stores the license information for all the source
43 code files.
44 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
45 </p>
46<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;">
47<h3 class="title">Tip</h3>
48 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
49 error and displays the correct "md5" parameter value during the build.
50 The correct parameter is also captured in the build log.
51 </div>
52<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;">
53<h3 class="title">Tip</h3>
54 If the whole file contains only license text, you do not need to use the "beginline" and
55 "endline" parameters.
56 </div>
57</div></body>
58</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.1. Running a Build</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky.html" title="Chapter 2. Using the Yocto Project">
9<link rel="prev" href="usingpoky.html" title="Chapter 2. Using the Yocto Project">
10<link rel="next" href="build-overview.html" title="2.1.1. Build Overview">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.1. Running a Build">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="usingpoky-build"></a>2.1. Running a Build</h2></div></div></div>
15<p>
16 This section provides a summary of the build process and provides information
17 for less obvious aspects of the build process.
18 For general information on how to build an image using the OpenEmbedded build
19 system, see the
20 "<a class="link" href="../yocto-project-qs/building-image.html" target="_self">Building an Image</a>"
21 section of the Yocto Project Quick Start.
22 </p>
23</div></body>
24</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.1.1. BitBake</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-components.html" title="3.1. Yocto Project Components">
9<link rel="prev" href="usingpoky-components.html" title="3.1. Yocto Project Components">
10<link rel="next" href="usingpoky-components-metadata.html" title="3.1.2. Metadata (Recipes)">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.1. BitBake">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="usingpoky-components-bitbake"></a>3.1.1. BitBake</h3></div></div></div>
15<p>
16 BitBake is the tool at the heart of the OpenEmbedded build system and is responsible
17 for parsing the metadata, generating a list of tasks from it,
18 and then executing those tasks.
19 To see a list of the options BitBake supports, use the following help command:
20 </p>
21<pre class="literallayout">
22 $ bitbake --help
23 </pre>
24<p>
25 </p>
26<p>
27 The most common usage for BitBake is <code class="filename">bitbake &lt;packagename&gt;</code>, where
28 <code class="filename">packagename</code> is the name of the package you want to build
29 (referred to as the "target" in this manual).
30 The target often equates to the first part of a <code class="filename">.bb</code> filename.
31 So, to run the <code class="filename">matchbox-desktop_1.2.3.bb</code> file, you
32 might type the following:
33 </p>
34<pre class="literallayout">
35 $ bitbake matchbox-desktop
36 </pre>
37<p>
38 Several different versions of <code class="filename">matchbox-desktop</code> might exist.
39 BitBake chooses the one selected by the distribution configuration.
40 You can get more details about how BitBake chooses between different
41 target versions and providers in the
42 "<a class="link" href="ref-bitbake-providers.html" title="6.2. Preferences and Providers">Preferences and Providers</a>" section.
43 </p>
44<p>
45 BitBake also tries to execute any dependent tasks first.
46 So for example, before building <code class="filename">matchbox-desktop</code>, BitBake
47 would build a cross compiler and <code class="filename">eglibc</code> if they had not already
48 been built.
49 </p>
50<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
51<h3 class="title">Note</h3>This release of the Yocto Project does not support the <code class="filename">glibc</code>
52 GNU version of the Unix standard C library. By default, the OpenEmbedded build system
53 builds with <code class="filename">eglibc</code>.</div>
54<p>
55 </p>
56<p>
57 A useful BitBake option to consider is the <code class="filename">-k</code> or
58 <code class="filename">--continue</code> option.
59 This option instructs BitBake to try and continue processing the job as much
60 as possible even after encountering an error.
61 When an error occurs, the target that
62 failed and those that depend on it cannot be remade.
63 However, when you use this option other dependencies can still be processed.
64 </p>
65</div></body>
66</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.1.3. Classes</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-components.html" title="3.1. Yocto Project Components">
9<link rel="prev" href="usingpoky-components-metadata.html" title="3.1.2. Metadata (Recipes)">
10<link rel="next" href="usingpoky-components-configuration.html" title="3.1.4. Configuration">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.3. Classes">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="usingpoky-components-classes"></a>3.1.3. Classes</h3></div></div></div>
15<p>
16 Class files (<code class="filename">.bbclass</code>) contain information that is useful to share
17 between metadata files.
18 An example is the Autotools class, which contains
19 common settings for any application that Autotools uses.
20 The "<a class="link" href="ref-classes.html" title="Chapter 7. Classes">Classes</a>" chapter provides details
21 about common classes and how to use them.
22 </p>
23</div></body>
24</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.1.4. Configuration</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-components.html" title="3.1. Yocto Project Components">
9<link rel="prev" href="usingpoky-components-classes.html" title="3.1.3. Classes">
10<link rel="next" href="shared-state-cache.html" title="3.2. Shared State Cache">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.4. Configuration">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="usingpoky-components-configuration"></a>3.1.4. Configuration</h3></div></div></div>
15<p>
16 The configuration files (<code class="filename">.conf</code>) define various configuration variables
17 that govern the OpenEmbedded build process.
18 These files fall into several areas that define machine configuration options,
19 distribution configuration options, compiler tuning options, general common configuration
20 options and user configuration options (<code class="filename">local.conf</code>, which is found
21 in the <a class="ulink" href="build-directory" target="_self">Build Directory</a>).
22 </p>
23</div></body>
24</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.1.2. Metadata (Recipes)</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-components.html" title="3.1. Yocto Project Components">
9<link rel="prev" href="usingpoky-components-bitbake.html" title="3.1.1. BitBake">
10<link rel="next" href="usingpoky-components-classes.html" title="3.1.3. Classes">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1.2. Metadata (Recipes)">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="usingpoky-components-metadata"></a>3.1.2. Metadata (Recipes)</h3></div></div></div>
15<p>
16 The <code class="filename">.bb</code> files are usually referred to as "recipes."
17 In general, a recipe contains information about a single piece of software.
18 The information includes the location from which to download the source patches
19 (if any are needed), which special configuration options to apply,
20 how to compile the source files, and how to package the compiled output.
21 </p>
22<p>
23 The term "package" can also be used to describe recipes.
24 However, since the same word is used for the packaged output from the OpenEmbedded
25 build system (i.e. <code class="filename">.ipk</code> or <code class="filename">.deb</code> files),
26 this document avoids using the term "package" when referring to recipes.
27 </p>
28</div></body>
29</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.1. Yocto Project Components</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="technical-details.html" title="Chapter 3. Technical Details">
9<link rel="prev" href="technical-details.html" title="Chapter 3. Technical Details">
10<link rel="next" href="usingpoky-components-bitbake.html" title="3.1.1. BitBake">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.1. Yocto Project Components">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="usingpoky-components"></a>3.1. Yocto Project Components</h2></div></div></div>
15<p>
16 The BitBake task executor together with various types of configuration files form the
17 OpenEmbedded Core.
18 This section overviews the BitBake task executor and the
19 configuration files by describing what they are used for and how they interact.
20 </p>
21<p>
22 BitBake handles the parsing and execution of the data files.
23 The data itself is of various types:
24 </p>
25<div class="itemizedlist"><ul class="itemizedlist" type="disc">
26<li class="listitem"><p><span class="emphasis"><em>Recipes:</em></span> Provides details about particular
27 pieces of software</p></li>
28<li class="listitem"><p><span class="emphasis"><em>Class Data:</em></span> An abstraction of common build
29 information (e.g. how to build a Linux kernel).</p></li>
30<li class="listitem"><p><span class="emphasis"><em>Configuration Data:</em></span> Defines machine-specific settings,
31 policy decisions, etc.
32 Configuration data acts as the glue to bind everything together.</p></li>
33</ul></div>
34<p>
35 For more information on data, see the
36 "<a class="link" href="../dev-manual/yocto-project-terms.html" target="_self">Yocto Project Terms</a>"
37 section in the Yocto Project Development Manual.
38 </p>
39<p>
40 BitBake knows how to combine multiple data sources together and refers to each data source
41 as a layer.
42 For information on layers, see the
43 "<a class="link" href="../dev-manual/understanding-and-creating-layers.html" target="_self">Understanding and
44 Creating Layers</a>" section of the Yocto Project Development Manual.
45 </p>
46<p>
47 Following are some brief details on these core components.
48 For more detailed information on these components see the
49 "<a class="link" href="ref-structure.html" title="Chapter 5. Source Directory Structure">Directory Structure</a>" chapter.
50 </p>
51</div></body>
52</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.4.1. Tracking License Changes</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="licenses.html" title="3.4. Licenses">
9<link rel="prev" href="licenses.html" title="3.4. Licenses">
10<link rel="next" href="usingpoky-specifying-LIC_FILES_CHKSUM.html" title="3.4.1.1. Specifying the LIC_FILES_CHKSUM Variable">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.4.1. Tracking License Changes">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="usingpoky-configuring-LIC_FILES_CHKSUM"></a>3.4.1. Tracking License Changes</h3></div></div></div>
15<p>
16 The license of an upstream project might change in the future.
17 In order to prevent these changes going unnoticed, the
18 <code class="filename"><a class="link" href="ref-variables-glos.html#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a></code>
19 variable tracks changes to the license text. The checksums are validated at the end of the
20 configure step, and if the checksums do not match, the build will fail.
21 </p>
22</div></body>
23</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.3.4. General BitBake Problems</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures">
9<link rel="prev" href="usingpoky-debugging-dependencies.html" title="2.3.3. Dependency Graphs">
10<link rel="next" href="usingpoky-debugging-buildfile.html" title="2.3.5. Building with No Dependencies">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.4. General BitBake Problems">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="usingpoky-debugging-bitbake"></a>2.3.4. General BitBake Problems</h3></div></div></div>
15<p>
16 You can see debug output from BitBake by using the <code class="filename">-D</code> option.
17 The debug output gives more information about what BitBake
18 is doing and the reason behind it.
19 Each <code class="filename">-D</code> option you use increases the logging level.
20 The most common usage is <code class="filename">-DDD</code>.
21 </p>
22<p>
23 The output from <code class="filename">bitbake -DDD -v targetname</code> can reveal why
24 BitBake chose a certain version of a package or why BitBake
25 picked a certain provider.
26 This command could also help you in a situation where you think BitBake did something
27 unexpected.
28 </p>
29</div></body>
30</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.3.5. Building with No Dependencies</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures">
9<link rel="prev" href="usingpoky-debugging-bitbake.html" title="2.3.4. General BitBake Problems">
10<link rel="next" href="usingpoky-debugging-variables.html" title="2.3.6. Variables">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.5. Building with No Dependencies">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="usingpoky-debugging-buildfile"></a>2.3.5. Building with No Dependencies</h3></div></div></div>
15<p>
16 If you really want to build a specific <code class="filename">.bb</code> file, you can use
17 the command form <code class="filename">bitbake -b &lt;somepath/somefile.bb&gt;</code>.
18 This command form does not check for dependencies so you should use it
19 only when you know its dependencies already exist.
20 You can also specify fragments of the filename.
21 In this case, BitBake checks for a unique match.
22 </p>
23</div></body>
24</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.3.3. Dependency Graphs</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures">
9<link rel="prev" href="usingpoky-debugging-taskrunning.html" title="2.3.2. Running Specific Tasks">
10<link rel="next" href="usingpoky-debugging-bitbake.html" title="2.3.4. General BitBake Problems">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.3. Dependency Graphs">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="usingpoky-debugging-dependencies"></a>2.3.3. Dependency Graphs</h3></div></div></div>
15<p>
16 Sometimes it can be hard to see why BitBake wants to build some other packages before a given
17 package you have specified.
18 The <code class="filename">bitbake -g targetname</code> command creates the
19 <code class="filename">depends.dot</code>, <code class="filename">package-depends.dot</code>,
20 and <code class="filename">task-depends.dot</code> files in the current directory.
21 These files show the package and task dependencies and are useful for debugging problems.
22 You can use the <code class="filename">bitbake -g -u depexp targetname</code> command to
23 display the results in a more human-readable form.
24 </p>
25</div></body>
26</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.3.8. Other Tips</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures">
9<link rel="prev" href="logging-with-bash.html" title="2.3.7.2. Logging With Bash">
10<link rel="next" href="maintaining-build-output-quality.html" title="2.4. Maintaining Build Output Quality">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.8. Other Tips">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="usingpoky-debugging-others"></a>2.3.8. Other Tips</h3></div></div></div>
15<p>
16 Here are some other tips that you might find useful:
17 </p>
18<div class="itemizedlist"><ul class="itemizedlist" type="disc">
19<li class="listitem"><p>When adding new packages, it is worth watching for
20 undesirable items making their way into compiler command lines.
21 For example, you do not want references to local system files like
22 <code class="filename">/usr/lib/</code> or <code class="filename">/usr/include/</code>.
23 </p></li>
24<li class="listitem"><p>If you want to remove the psplash boot splashscreen,
25 add <code class="filename">psplash=false</code> to the kernel command line.
26 Doing so prevents psplash from loading and thus allows you to see the console.
27 It is also possible to switch out of the splashscreen by
28 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
29 </p></li>
30</ul></div>
31<p>
32 </p>
33</div></body>
34</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.3.1. Task Failures</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures">
9<link rel="prev" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures">
10<link rel="next" href="usingpoky-debugging-taskrunning.html" title="2.3.2. Running Specific Tasks">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.1. Task Failures">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="usingpoky-debugging-taskfailures"></a>2.3.1. Task Failures</h3></div></div></div>
15<p>The log file for shell tasks is available in
16 <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>.
17 For example, the <code class="filename">compile</code> task for the QEMU minimal image for the x86
18 machine (<code class="filename">qemux86</code>) might be
19 <code class="filename">tmp/work/qemux86-poky-linux/core-image-minimal-1.0-r0/temp/log.do_compile.20830</code>.
20 To see what BitBake runs to generate that log, look at the corresponding
21 <code class="filename">run.do_taskname.pid</code> file located in the same directory.
22 </p>
23<p>
24 Presently, the output from Python tasks is sent directly to the console.
25 </p>
26</div></body>
27</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.3.2. Running Specific Tasks</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures">
9<link rel="prev" href="usingpoky-debugging-taskfailures.html" title="2.3.1. Task Failures">
10<link rel="next" href="usingpoky-debugging-dependencies.html" title="2.3.3. Dependency Graphs">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.2. Running Specific Tasks">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="usingpoky-debugging-taskrunning"></a>2.3.2. Running Specific Tasks</h3></div></div></div>
15<p>
16 Any given package consists of a set of tasks.
17 The standard BitBake behavior in most cases is: <code class="filename">fetch</code>,
18 <code class="filename">unpack</code>,
19 <code class="filename">patch</code>, <code class="filename">configure</code>,
20 <code class="filename">compile</code>, <code class="filename">install</code>, <code class="filename">package</code>,
21 <code class="filename">package_write</code>, and <code class="filename">build</code>.
22 The default task is <code class="filename">build</code> and any tasks on which it depends
23 build first.
24 Some tasks exist, such as <code class="filename">devshell</code>, that are not part of the
25 default build chain.
26 If you wish to run a task that is not part of the default build chain, you can use the
27 <code class="filename">-c</code> option in BitBake as follows:
28 </p>
29<pre class="literallayout">
30 $ bitbake matchbox-desktop -c devshell
31 </pre>
32<p>
33 </p>
34<p>
35 If you wish to rerun a task, use the <code class="filename">-f</code> force option.
36 For example, the following sequence forces recompilation after changing files in the
37 working directory.
38 </p>
39<pre class="literallayout">
40 $ bitbake matchbox-desktop
41 .
42 .
43 [make some changes to the source code in the working directory]
44 .
45 .
46 $ bitbake matchbox-desktop -c compile -f
47 $ bitbake matchbox-desktop
48 </pre>
49<p>
50 </p>
51<p>
52 This sequence first builds <code class="filename">matchbox-desktop</code> and then recompiles it.
53 The last command reruns all tasks (basically the packaging tasks) after the compile.
54 BitBake recognizes that the <code class="filename">compile</code> task was rerun and therefore
55 understands that the other tasks also need to be run again.
56 </p>
57<p>
58 You can view a list of tasks in a given package by running the
59 <code class="filename">listtasks</code> task as follows:
60 </p>
61<pre class="literallayout">
62 $ bitbake matchbox-desktop -c listtasks
63 </pre>
64<p>
65 The results are in the file <code class="filename">${WORKDIR}/temp/log.do_listtasks</code>.
66 </p>
67</div></body>
68</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.3.6. Variables</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures">
9<link rel="prev" href="usingpoky-debugging-buildfile.html" title="2.3.5. Building with No Dependencies">
10<link rel="next" href="recipe-logging-mechanisms.html" title="2.3.7. Recipe Logging Mechanisms">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3.6. Variables">
13<div class="titlepage"><div><div><h3 class="title">
14<a name="usingpoky-debugging-variables"></a>2.3.6. Variables</h3></div></div></div>
15<p>
16 The <code class="filename">-e</code> option dumps the resulting environment for
17 either the configuration (no package specified) or for a
18 specific package when specified; or <code class="filename">-b recipename</code>
19 to show the environment from parsing a single recipe file only.
20 </p>
21</div></body>
22</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.3. Debugging Build Failures</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky.html" title="Chapter 2. Using the Yocto Project">
9<link rel="prev" href="usingpoky-install.html" title="2.2. Installing and Using the Result">
10<link rel="next" href="usingpoky-debugging-taskfailures.html" title="2.3.1. Task Failures">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.3. Debugging Build Failures">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="usingpoky-debugging"></a>2.3. Debugging Build Failures</h2></div></div></div>
15<p>
16 The exact method for debugging build failures depends on the nature of the
17 problem and on the system's area from which the bug originates.
18 Standard debugging practices such as comparison against the last
19 known working version with examination of the changes and the re-application of steps
20 to identify the one causing the problem are
21 valid for the Yocto Project just as they are for any other system.
22 Even though it is impossible to detail every possible potential failure,
23 this section provides some general tips to aid in debugging.
24 </p>
25</div></body>
26</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>2.2. Installing and Using the Result</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky.html" title="Chapter 2. Using the Yocto Project">
9<link rel="prev" href="building-an-image-using-gpl-components.html" title="2.1.2. Building an Image Using GPL Components">
10<link rel="next" href="usingpoky-debugging.html" title="2.3. Debugging Build Failures">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="2.2. Installing and Using the Result">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="usingpoky-install"></a>2.2. Installing and Using the Result</h2></div></div></div>
15<p>
16 Once an image has been built, it often needs to be installed.
17 The images and kernels built by the OpenEmbedded build system are placed in the
18 <a class="link" href="../dev-manual/build-directory.html" target="_self">Build Directory</a> in
19 <code class="filename">tmp/deploy/images</code>.
20 For information on how to run pre-built images such as <code class="filename">qemux86</code>
21 and <code class="filename">qemuarm</code>, see the
22 "<a class="link" href="../yocto-project-qs/using-pre-built.html" target="_self">Using Pre-Built Binaries and QEMU</a>"
23 section in the Yocto Project Quick Start.
24 For information about how to install these images, see the documentation for your
25 particular board/machine.
26 </p>
27</div></body>
28</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.4.1.1. Specifying the LIC_FILES_CHKSUM Variable</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.4.1. Tracking License Changes">
9<link rel="prev" href="usingpoky-configuring-LIC_FILES_CHKSUM.html" title="3.4.1. Tracking License Changes">
10<link rel="next" href="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html" title="3.4.1.2. Explanation of Syntax">
11</head>
12<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">
13<div class="titlepage"><div><div><h4 class="title">
14<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>
15<p>
16 The <code class="filename">LIC_FILES_CHKSUM</code>
17 variable contains checksums of the license text in the source code for the recipe.
18 Following is an example of how to specify <code class="filename">LIC_FILES_CHKSUM</code>:
19 </p>
20<pre class="literallayout">
21 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
22 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
23 file://licfile2.txt;endline=50;md5=zzzz \
24 ..."
25 </pre>
26<p>
27 </p>
28<p>
29 The build system uses the
30 <code class="filename"><a class="link" href="ref-variables-glos.html#var-S" title="S">S</a></code> variable as the
31 default directory used when searching files listed in
32 <code class="filename">LIC_FILES_CHKSUM</code>.
33 The previous example employs the default directory.
34 </p>
35<p>
36 You can also use relative paths as shown in the following example:
37 </p>
38<pre class="literallayout">
39 LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
40 md5=bb14ed3c4cda583abc85401304b5cd4e"
41 LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
42 </pre>
43<p>
44 </p>
45<p>
46 In this example, the first line locates a file in
47 <code class="filename">${S}/src/ls.c</code>.
48 The second line refers to a file in
49 <code class="filename"><a class="link" href="ref-variables-glos.html#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, which is the parent
50 of <code class="filename"><a class="link" href="ref-variables-glos.html#var-S" title="S">S</a></code>.
51 </p>
52<p>
53 Note that this variable is mandatory for all recipes, unless the
54 <code class="filename">LICENSE</code> variable is set to "CLOSED".
55 </p>
56</div></body>
57</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Chapter 2. Using the Yocto Project</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="index.html" title="The Yocto Project Reference Manual">
9<link rel="prev" href="intro-getit-dev.html" title="1.5. Development Checkouts">
10<link rel="next" href="usingpoky-build.html" title="2.1. Running a Build">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="chapter" title="Chapter 2. Using the Yocto Project">
13<div class="titlepage"><div><div><h2 class="title">
14<a name="usingpoky"></a>Chapter 2. Using the Yocto Project</h2></div></div></div>
15<div class="toc">
16<p><b>Table of Contents</b></p>
17<dl>
18<dt><span class="section"><a href="usingpoky-build.html">2.1. Running a Build</a></span></dt>
19<dd><dl>
20<dt><span class="section"><a href="build-overview.html">2.1.1. Build Overview</a></span></dt>
21<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>
22</dl></dd>
23<dt><span class="section"><a href="usingpoky-install.html">2.2. Installing and Using the Result</a></span></dt>
24<dt><span class="section"><a href="usingpoky-debugging.html">2.3. Debugging Build Failures</a></span></dt>
25<dd><dl>
26<dt><span class="section"><a href="usingpoky-debugging-taskfailures.html">2.3.1. Task Failures</a></span></dt>
27<dt><span class="section"><a href="usingpoky-debugging-taskrunning.html">2.3.2. Running Specific Tasks</a></span></dt>
28<dt><span class="section"><a href="usingpoky-debugging-dependencies.html">2.3.3. Dependency Graphs</a></span></dt>
29<dt><span class="section"><a href="usingpoky-debugging-bitbake.html">2.3.4. General BitBake Problems</a></span></dt>
30<dt><span class="section"><a href="usingpoky-debugging-buildfile.html">2.3.5. Building with No Dependencies</a></span></dt>
31<dt><span class="section"><a href="usingpoky-debugging-variables.html">2.3.6. Variables</a></span></dt>
32<dt><span class="section"><a href="recipe-logging-mechanisms.html">2.3.7. Recipe Logging Mechanisms</a></span></dt>
33<dt><span class="section"><a href="usingpoky-debugging-others.html">2.3.8. Other Tips</a></span></dt>
34</dl></dd>
35<dt><span class="section"><a href="maintaining-build-output-quality.html">2.4. Maintaining Build Output Quality</a></span></dt>
36<dd><dl>
37<dt><span class="section"><a href="enabling-and-disabling-build-history.html">2.4.1. Enabling and Disabling Build History</a></span></dt>
38<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>
39</dl></dd>
40</dl>
41</div>
42<p>
43 This chapter describes common usage for the Yocto Project.
44 The information is introductory in nature as other manuals in the Yocto Project
45 documentation set provide more details on how to use the Yocto Project.
46 </p>
47</div></body>
48</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 @@
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>3.3. x32</title>
5<link rel="stylesheet" type="text/css" href="../book.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7<link rel="home" href="index.html" title="The Yocto Project Reference Manual">
8<link rel="up" href="technical-details.html" title="Chapter 3. Technical Details">
9<link rel="prev" href="invalidating-shared-state.html" title="3.2.4.2. Invalidating Shared State">
10<link rel="next" href="support.html" title="3.3.1. Support">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="section" title="3.3. x32">
13<div class="titlepage"><div><div><h2 class="title" style="clear: both">
14<a name="x32"></a>3.3. x32</h2></div></div></div>
15<p>
16 x32 is a new processor-specific Application Binary Interface (psABI) for x86_64.
17 An ABI defines the calling conventions between functions in a processing environment.
18 The interface determines what registers are used and what the sizes are for various C data types.
19 </p>
20<p>
21 Some processing environments prefer using 32-bit applications even when running
22 on Intel 64-bit platforms.
23 Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
24 The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
25 leaving the system underutilized.
26 Now consider the x86_64 psABI.
27 This ABI is newer and uses 64-bits for data sizes and program pointers.
28 The extra bits increase the footprint size of the programs, libraries,
29 and also increases the memory and file system size requirements.
30 Executing under the x32 psABI enables user programs to utilize CPU and system resources
31 more efficiently while keeping the memory footprint of the applications low.
32 Extra bits are used for registers but not for addressing mechanisms.
33 </p>
34</div></body>
35</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 @@
1<?xml version="1.0" encoding="utf-8" standalone="no"?>
2<toc label="The Yocto Project Reference Manual" topic="html/poky-ref-manual/index.html">
3 <topic label="Introduction" href="html/poky-ref-manual/intro.html">
4 <topic label="Introduction" href="html/poky-ref-manual/intro-welcome.html"/>
5 <topic label="Documentation Overview" href="html/poky-ref-manual/intro-manualoverview.html"/>
6 <topic label="System Requirements" href="html/poky-ref-manual/intro-requirements.html">
7 <topic label="Supported Linux Distributions" href="html/poky-ref-manual/detailed-supported-distros.html"/>
8 <topic label="Required Packages for the Host Development System" href="html/poky-ref-manual/required-packages-for-the-host-development-system.html">
9 <topic label="Ubuntu" href="html/poky-ref-manual/ubuntu-packages.html"/>
10 <topic label="Fedora Packages" href="html/poky-ref-manual/fedora-packages.html"/>
11 <topic label="OpenSUSE Packages" href="html/poky-ref-manual/opensuse-packages.html"/>
12 <topic label="CentOS Packages" href="html/poky-ref-manual/centos-packages.html"/>
13 </topic>
14 </topic>
15 <topic label="Obtaining the Yocto Project" href="html/poky-ref-manual/intro-getit.html"/>
16 <topic label="Development Checkouts" href="html/poky-ref-manual/intro-getit-dev.html"/>
17 </topic>
18 <topic label="Using the Yocto Project" href="html/poky-ref-manual/usingpoky.html">
19 <topic label="Running a Build" href="html/poky-ref-manual/usingpoky-build.html">
20 <topic label="Build Overview" href="html/poky-ref-manual/build-overview.html"/>
21 <topic label="Building an Image Using GPL Components" href="html/poky-ref-manual/building-an-image-using-gpl-components.html"/>
22 </topic>
23 <topic label="Installing and Using the Result" href="html/poky-ref-manual/usingpoky-install.html"/>
24 <topic label="Debugging Build Failures" href="html/poky-ref-manual/usingpoky-debugging.html">
25 <topic label="Task Failures" href="html/poky-ref-manual/usingpoky-debugging-taskfailures.html"/>
26 <topic label="Running Specific Tasks" href="html/poky-ref-manual/usingpoky-debugging-taskrunning.html"/>
27 <topic label="Dependency Graphs" href="html/poky-ref-manual/usingpoky-debugging-dependencies.html"/>
28 <topic label="General BitBake Problems" href="html/poky-ref-manual/usingpoky-debugging-bitbake.html"/>
29 <topic label="Building with No Dependencies" href="html/poky-ref-manual/usingpoky-debugging-buildfile.html"/>
30 <topic label="Variables" href="html/poky-ref-manual/usingpoky-debugging-variables.html"/>
31 <topic label="Recipe Logging Mechanisms" href="html/poky-ref-manual/recipe-logging-mechanisms.html">
32 <topic label="Logging With Python" href="html/poky-ref-manual/logging-with-python.html"/>
33 <topic label="Logging With Bash" href="html/poky-ref-manual/logging-with-bash.html"/>
34 </topic>
35 <topic label="Other Tips" href="html/poky-ref-manual/usingpoky-debugging-others.html"/>
36 </topic>
37 <topic label="Maintaining Build Output Quality" href="html/poky-ref-manual/maintaining-build-output-quality.html">
38 <topic label="Enabling and Disabling Build History" href="html/poky-ref-manual/enabling-and-disabling-build-history.html"/>
39 <topic label="Understanding What the Build History Contains" href="html/poky-ref-manual/understanding-what-the-build-history-contains.html">
40 <topic label="Build History Package Information" href="html/poky-ref-manual/build-history-package-information.html"/>
41 <topic label="Build History Image Information" href="html/poky-ref-manual/build-history-image-information.html"/>
42 <topic label="Using Build History to Gather Image Information Only" href="html/poky-ref-manual/using-build-history-to-gather-image-information-only.html"/>
43 <topic label="Examining Build History Information" href="html/poky-ref-manual/examining-build-history-information.html"/>
44 </topic>
45 </topic>
46 </topic>
47 <topic label="Technical Details" href="html/poky-ref-manual/technical-details.html">
48 <topic label="Yocto Project Components" href="html/poky-ref-manual/usingpoky-components.html">
49 <topic label="BitBake" href="html/poky-ref-manual/usingpoky-components-bitbake.html"/>
50 <topic label="Metadata (Recipes)" href="html/poky-ref-manual/usingpoky-components-metadata.html"/>
51 <topic label="Classes" href="html/poky-ref-manual/usingpoky-components-classes.html"/>
52 <topic label="Configuration" href="html/poky-ref-manual/usingpoky-components-configuration.html"/>
53 </topic>
54 <topic label="Shared State Cache" href="html/poky-ref-manual/shared-state-cache.html">
55 <topic label="Overall Architecture" href="html/poky-ref-manual/overall-architecture.html"/>
56 <topic label="Checksums (Signatures)" href="html/poky-ref-manual/checksums.html"/>
57 <topic label="Shared State" href="html/poky-ref-manual/shared-state.html"/>
58 <topic label="Tips and Tricks" href="html/poky-ref-manual/tips-and-tricks.html">
59 <topic label="Debugging" href="html/poky-ref-manual/debugging.html"/>
60 <topic label="Invalidating Shared State" href="html/poky-ref-manual/invalidating-shared-state.html"/>
61 </topic>
62 </topic>
63 <topic label="x32" href="html/poky-ref-manual/x32.html">
64 <topic label="Support" href="html/poky-ref-manual/support.html"/>
65 <topic label="Future Development and Limitations" href="html/poky-ref-manual/future-development-and-limitations.html"/>
66 <topic label="Using x32 Right Now" href="html/poky-ref-manual/using-x32-right-now.html"/>
67 </topic>
68 <topic label="Licenses" href="html/poky-ref-manual/licenses.html">
69 <topic label="Tracking License Changes" href="html/poky-ref-manual/usingpoky-configuring-LIC_FILES_CHKSUM.html">
70 <topic label="Specifying the LIC_FILES_CHKSUM Variable" href="html/poky-ref-manual/usingpoky-specifying-LIC_FILES_CHKSUM.html"/>
71 <topic label="Explanation of Syntax" href="html/poky-ref-manual/usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax.html"/>
72 </topic>
73 <topic label="Enabling Commercially Licensed Recipes" href="html/poky-ref-manual/enabling-commercially-licensed-recipes.html">
74 <topic label="License Flag Matching" href="html/poky-ref-manual/license-flag-matching.html"/>
75 <topic label="Other Variables Related to Commercial Licenses" href="html/poky-ref-manual/other-variables-related-to-commercial-licenses.html"/>
76 </topic>
77 </topic>
78 </topic>
79 <topic label="Migrating to a Newer Yocto Project Release" href="html/poky-ref-manual/migration.html">
80 <topic label="Moving to the Yocto Project 1.3 Release" href="html/poky-ref-manual/moving-to-the-yocto-project-1.3-release.html">
81 <topic label="Local Configuration" href="html/poky-ref-manual/1.3-local-configuration.html">
82 <topic label="SSTATE_MIRRORS" href="html/poky-ref-manual/migration-1.3-sstate-mirrors.html"/>
83 <topic label="bblayers.conf" href="html/poky-ref-manual/migration-1.3-bblayers-conf.html"/>
84 </topic>
85 <topic label="Recipes" href="html/poky-ref-manual/1.3-recipes.html">
86 <topic label="Python Function Whitespace" href="html/poky-ref-manual/migration-1.3-python-function-whitespace.html"/>
87 <topic label="proto= in SRC_URI" href="html/poky-ref-manual/migration-1.3-proto=-in-src-uri.html"/>
88 <topic label="nativesdk" href="html/poky-ref-manual/migration-1.3-nativesdk.html"/>
89 <topic label="Task Recipes" href="html/poky-ref-manual/migration-1.3-task-recipes.html"/>
90 <topic label="IMAGE_FEATURES" href="html/poky-ref-manual/migration-1.3-image-features.html"/>
91 <topic label="Removed Recipes" href="html/poky-ref-manual/migration-1.3-removed-recipes.html"/>
92 </topic>
93 </topic>
94 </topic>
95 <topic label="Source Directory Structure" href="html/poky-ref-manual/ref-structure.html">
96 <topic label="Top level core components" href="html/poky-ref-manual/structure-core.html">
97 <topic label="bitbake/" href="html/poky-ref-manual/structure-core-bitbake.html"/>
98 <topic label="build/" href="html/poky-ref-manual/structure-core-build.html"/>
99 <topic label="documentation" href="html/poky-ref-manual/handbook.html"/>
100 <topic label="meta/" href="html/poky-ref-manual/structure-core-meta.html"/>
101 <topic label="meta-yocto/" href="html/poky-ref-manual/structure-core-meta-yocto.html"/>
102 <topic label="meta-yocto-bsp/" href="html/poky-ref-manual/structure-core-meta-yocto-bsp.html"/>
103 <topic label="meta-hob/" href="html/poky-ref-manual/structure-meta-hob.html"/>
104 <topic label="meta-skeleton/" href="html/poky-ref-manual/structure-meta-skeleton.html"/>
105 <topic label="scripts/" href="html/poky-ref-manual/structure-core-scripts.html"/>
106 <topic label="oe-init-build-env" href="html/poky-ref-manual/structure-core-script.html"/>
107 <topic label="LICENSE, README, and README.hardware" href="html/poky-ref-manual/structure-basic-top-level.html"/>
108 </topic>
109 <topic label="The Build Directory - build/" href="html/poky-ref-manual/structure-build.html">
110 <topic label="build/pseudodone" href="html/poky-ref-manual/structure-build-pseudodone.html"/>
111 <topic label="build/conf/local.conf" href="html/poky-ref-manual/structure-build-conf-local.conf.html"/>
112 <topic label="build/conf/bblayers.conf" href="html/poky-ref-manual/structure-build-conf-bblayers.conf.html"/>
113 <topic label="build/conf/sanity_info" href="html/poky-ref-manual/structure-build-conf-sanity_info.html"/>
114 <topic label="build/downloads/" href="html/poky-ref-manual/structure-build-downloads.html"/>
115 <topic label="build/sstate-cache/" href="html/poky-ref-manual/structure-build-sstate-cache.html"/>
116 <topic label="build/tmp/" href="html/poky-ref-manual/structure-build-tmp.html"/>
117 <topic label="build/tmp/buildstats/" href="html/poky-ref-manual/structure-build-tmp-buildstats.html"/>
118 <topic label="build/tmp/cache/" href="html/poky-ref-manual/structure-build-tmp-cache.html"/>
119 <topic label="build/tmp/deploy/" href="html/poky-ref-manual/structure-build-tmp-deploy.html"/>
120 <topic label="build/tmp/deploy/deb/" href="html/poky-ref-manual/structure-build-tmp-deploy-deb.html"/>
121 <topic label="build/tmp/deploy/rpm/" href="html/poky-ref-manual/structure-build-tmp-deploy-rpm.html"/>
122 <topic label="build/tmp/deploy/licenses/" href="html/poky-ref-manual/structure-build-tmp-deploy-licenses.html"/>
123 <topic label="build/tmp/deploy/images/" href="html/poky-ref-manual/structure-build-tmp-deploy-images.html"/>
124 <topic label="build/tmp/deploy/ipk/" href="html/poky-ref-manual/structure-build-tmp-deploy-ipk.html"/>
125 <topic label="build/tmp/sysroots/" href="html/poky-ref-manual/structure-build-tmp-sysroots.html"/>
126 <topic label="build/tmp/stamps/" href="html/poky-ref-manual/structure-build-tmp-stamps.html"/>
127 <topic label="build/tmp/log/" href="html/poky-ref-manual/structure-build-tmp-log.html"/>
128 <topic label="build/tmp/pkgdata/" href="html/poky-ref-manual/structure-build-tmp-pkgdata.html"/>
129 <topic label="build/tmp/work/" href="html/poky-ref-manual/structure-build-tmp-work.html"/>
130 </topic>
131 <topic label="The Metadata - meta/" href="html/poky-ref-manual/structure-meta.html">
132 <topic label="meta/classes/" href="html/poky-ref-manual/structure-meta-classes.html"/>
133 <topic label="meta/conf/" href="html/poky-ref-manual/structure-meta-conf.html"/>
134 <topic label="meta/conf/machine/" href="html/poky-ref-manual/structure-meta-conf-machine.html"/>
135 <topic label="meta/conf/distro/" href="html/poky-ref-manual/structure-meta-conf-distro.html"/>
136 <topic label="meta/recipes-bsp/" href="html/poky-ref-manual/structure-meta-recipes-bsp.html"/>
137 <topic label="meta/recipes-connectivity/" href="html/poky-ref-manual/structure-meta-recipes-connectivity.html"/>
138 <topic label="meta/recipes-core/" href="html/poky-ref-manual/structure-meta-recipes-core.html"/>
139 <topic label="meta/recipes-devtools/" href="html/poky-ref-manual/structure-meta-recipes-devtools.html"/>
140 <topic label="meta/recipes-extended/" href="html/poky-ref-manual/structure-meta-recipes-extended.html"/>
141 <topic label="meta/recipes-gnome/" href="html/poky-ref-manual/structure-meta-recipes-gnome.html"/>
142 <topic label="meta/recipes-graphics/" href="html/poky-ref-manual/structure-meta-recipes-graphics.html"/>
143 <topic label="meta/recipes-kernel/" href="html/poky-ref-manual/structure-meta-recipes-kernel.html"/>
144 <topic label="meta/recipes-multimedia/" href="html/poky-ref-manual/structure-meta-recipes-multimedia.html"/>
145 <topic label="meta/recipes-qt/" href="html/poky-ref-manual/structure-meta-recipes-qt.html"/>
146 <topic label="meta/recipes-rt/" href="html/poky-ref-manual/structure-meta-recipes-rt.html"/>
147 <topic label="meta/recipes-sato/" href="html/poky-ref-manual/structure-meta-recipes-sato.html"/>
148 <topic label="meta/recipes-support/" href="html/poky-ref-manual/structure-meta-recipes-support.html"/>
149 <topic label="meta/site/" href="html/poky-ref-manual/structure-meta-site.html"/>
150 <topic label="meta/recipes.txt" href="html/poky-ref-manual/structure-meta-recipes-txt.html"/>
151 </topic>
152 </topic>
153 <topic label="BitBake" href="html/poky-ref-manual/ref-bitbake.html">
154 <topic label="Parsing" href="html/poky-ref-manual/ref-bitbake-parsing.html"/>
155 <topic label="Preferences and Providers" href="html/poky-ref-manual/ref-bitbake-providers.html"/>
156 <topic label="Dependencies" href="html/poky-ref-manual/ref-bitbake-dependencies.html"/>
157 <topic label="The Task List" href="html/poky-ref-manual/ref-bitbake-tasklist.html"/>
158 <topic label="Running a Task" href="html/poky-ref-manual/ref-bitbake-runtask.html"/>
159 <topic label="BitBake Command Line" href="html/poky-ref-manual/ref-bitbake-commandline.html"/>
160 <topic label="Fetchers" href="html/poky-ref-manual/ref-bitbake-fetchers.html"/>
161 </topic>
162 <topic label="Classes" href="html/poky-ref-manual/ref-classes.html">
163 <topic label="The base class - base.bbclass" href="html/poky-ref-manual/ref-classes-base.html"/>
164 <topic label="Autotooled Packages - autotools.bbclass" href="html/poky-ref-manual/ref-classes-autotools.html"/>
165 <topic label="Alternatives - update-alternatives.bbclass" href="html/poky-ref-manual/ref-classes-update-alternatives.html"/>
166 <topic label="Initscripts - update-rc.d.bbclass" href="html/poky-ref-manual/ref-classes-update-rc.d.html"/>
167 <topic label="Binary config scripts - binconfig.bbclass" href="html/poky-ref-manual/ref-classes-binconfig.html"/>
168 <topic label="Debian renaming - debian.bbclass" href="html/poky-ref-manual/ref-classes-debian.html"/>
169 <topic label="Pkg-config - pkgconfig.bbclass" href="html/poky-ref-manual/ref-classes-pkgconfig.html"/>
170 <topic label="Distribution of sources - src_distribute_local.bbclass" href="html/poky-ref-manual/ref-classes-src-distribute.html"/>
171 <topic label="Perl modules - cpan.bbclass" href="html/poky-ref-manual/ref-classes-perl.html"/>
172 <topic label="Python extensions - distutils.bbclass" href="html/poky-ref-manual/ref-classes-distutils.html"/>
173 <topic label="Developer Shell - devshell.bbclass" href="html/poky-ref-manual/ref-classes-devshell.html"/>
174 <topic label="Package Groups - packagegroup.bbclass" href="html/poky-ref-manual/ref-classes-packagegroup.html"/>
175 <topic label="Packaging - package*.bbclass" href="html/poky-ref-manual/ref-classes-package.html"/>
176 <topic label="Building kernels - kernel.bbclass" href="html/poky-ref-manual/ref-classes-kernel.html"/>
177 <topic label="Creating images - image.bbclass and rootfs*.bbclass" href="html/poky-ref-manual/ref-classes-image.html"/>
178 <topic label="Host System sanity checks - sanity.bbclass" href="html/poky-ref-manual/ref-classes-sanity.html"/>
179 <topic label="Generated output quality assurance checks - insane.bbclass" href="html/poky-ref-manual/ref-classes-insane.html"/>
180 <topic label="Autotools configuration data cache - siteinfo.bbclass" href="html/poky-ref-manual/ref-classes-siteinfo.html"/>
181 <topic label="Adding Users - useradd.bbclass" href="html/poky-ref-manual/ref-classes-useradd.html"/>
182 <topic label="Using External Source - externalsrc.bbclass" href="html/poky-ref-manual/ref-classes-externalsrc.html"/>
183 <topic label="Other Classes" href="html/poky-ref-manual/ref-classes-others.html"/>
184 </topic>
185 <topic label="Images" href="html/poky-ref-manual/ref-images.html"/>
186 <topic label="Reference: Features" href="html/poky-ref-manual/ref-features.html">
187 <topic label="Distro" href="html/poky-ref-manual/ref-features-distro.html"/>
188 <topic label="Machine" href="html/poky-ref-manual/ref-features-machine.html"/>
189 <topic label="Images" href="html/poky-ref-manual/ref-features-image.html"/>
190 <topic label="Feature Backfilling" href="html/poky-ref-manual/ref-features-backfill.html"/>
191 </topic>
192 <topic label="Variables Glossary" href="html/poky-ref-manual/ref-variables-glos.html">
193 <topic label="Glossary" href="html/poky-ref-manual/ref-variables-glos.html#ref-variables-glossary"/>
194 </topic>
195 <topic label="Variable Context" href="html/poky-ref-manual/ref-varlocality.html">
196 <topic label="Configuration" href="html/poky-ref-manual/ref-varlocality-configuration.html">
197 <topic label="Distribution (Distro)" href="html/poky-ref-manual/ref-varlocality-config-distro.html"/>
198 <topic label="Machine" href="html/poky-ref-manual/ref-varlocality-config-machine.html"/>
199 <topic label="Local" href="html/poky-ref-manual/ref-varlocality-config-local.html"/>
200 </topic>
201 <topic label="Recipes" href="html/poky-ref-manual/ref-varlocality-recipes.html">
202 <topic label="Required" href="html/poky-ref-manual/ref-varlocality-recipe-required.html"/>
203 <topic label="Dependencies" href="html/poky-ref-manual/ref-varlocality-recipe-dependencies.html"/>
204 <topic label="Paths" href="html/poky-ref-manual/ref-varlocality-recipe-paths.html"/>
205 <topic label="Extra Build Information" href="html/poky-ref-manual/ref-varlocality-recipe-build.html"/>
206 </topic>
207 </topic>
208 <topic label="FAQ" href="html/poky-ref-manual/faq.html"/>
209 <topic label="Contributing to the Yocto Project" href="html/poky-ref-manual/resources.html">
210 <topic label="Introduction" href="html/poky-ref-manual/resources-intro.html"/>
211 <topic label="Tracking Bugs" href="html/poky-ref-manual/resources-bugtracker.html"/>
212 <topic label="Mailing lists" href="html/poky-ref-manual/resources-mailinglist.html"/>
213 <topic label="Internet Relay Chat (IRC)" href="html/poky-ref-manual/resources-irc.html"/>
214 <topic label="Links" href="html/poky-ref-manual/resources-links.html"/>
215 <topic label="Contributions" href="html/poky-ref-manual/resources-contributions.html"/>
216 </topic>
217</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 @@
1DESCRIPTION = "GNU Helloworld application"
2SECTION = "examples"
3LICENSE = "GPLv3"
4LIC_FILES_CHKSUM = "file://COPYING;md5=adefda309052235aa5d1e99ce7557010"
5
6SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2"
7
8inherit 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 @@
1#include <stdio.h>
2
3int main(void)
4{
5 printf("Hello world!\n");
6
7 return 0;
8}
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 @@
1DESCRIPTION = "Simple helloworld application"
2SECTION = "examples"
3LICENSE = "MIT"
4LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
5
6SRC_URI = "file://helloworld.c"
7
8S = "${WORKDIR}"
9
10do_compile() {
11 ${CC} helloworld.c -o helloworld
12}
13
14do_install() {
15 install -d ${D}${bindir}
16 install -m 0755 helloworld ${D}${bindir}
17}
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 @@
1require xorg-lib-common.inc
2
3DESCRIPTION = "X11 Pixmap library"
4LICENSE = "X-BSD"
5LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
6DEPENDS += "libxext"
7PR = "r2"
8PE = "1"
9
10XORG_PN = "libXpm"
11
12PACKAGES =+ "sxpm cxpm"
13FILES_cxpm = "${bindir}/cxpm"
14FILES_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 @@
1DESCRIPTION = "Tools for managing memory technology devices."
2SECTION = "base"
3DEPENDS = "zlib"
4HOMEPAGE = "http://www.linux-mtd.infradead.org/"
5LICENSE = "GPLv2"
6LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
7 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
8
9SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz"
10
11CFLAGS_prepend = "-I ${S}/include "
12
13do_install() {
14 oe_runmake install DESTDIR=${D}
15}
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='faq'>
6<title>FAQ</title>
7<qandaset>
8 <qandaentry>
9 <question>
10 <para>
11 How does Poky differ from <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>?
12 </para>
13 </question>
14 <answer>
15 <para>
16 The term "Poky" refers to the specific reference build system that
17 the Yocto Project provides.
18 Poky is based on <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink>
19 and BitBake.
20 Thus, the generic term used here for the build system is
21 the "OpenEmbedded build system."
22 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
23 changes always being merged to OE-Core or BitBake first before being pulled back
24 into Poky.
25 This practice benefits both projects immediately.
26 For a fuller description of the term "Poky", see the
27 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> term in the Yocto Project
28 Development Manual.
29 </para>
30 </answer>
31 </qandaentry>
32
33 <qandaentry>
34 <question>
35 <para>
36 I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
37 Can I still use the Yocto Project?
38 </para>
39 </question>
40 <answer>
41 <para>
42 You can use a stand-alone tarball to provide Python 2.6.
43 You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations:
44 <itemizedlist>
45 <listitem><para><ulink url='&YOCTO_PYTHON-i686_DL_URL;'>32-bit tarball</ulink></para></listitem>
46 <listitem><para><ulink url='&YOCTO_PYTHON-x86_64_DL_URL;'>64-bit tarball</ulink></para></listitem>
47 </itemizedlist>
48 </para>
49 <para>
50 These tarballs are self-contained with all required libraries and should work
51 on most Linux systems.
52 To use the tarballs extract them into the root
53 directory and run the appropriate command:
54 <literallayout class='monospaced'>
55 $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH
56 $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH
57 </literallayout>
58 </para>
59 <para>
60 Once you run the command, BitBake uses Python 2.6.
61 </para>
62 </answer>
63 </qandaentry>
64
65 <qandaentry>
66 <question>
67 <para>
68 How can you claim Poky / OpenEmbedded-Core is stable?
69 </para>
70 </question>
71 <answer>
72 <para>
73 There are three areas that help with stability;
74 <itemizedlist>
75 <listitem><para>The Yocto Project team keeps
76 <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> small
77 and focused, containing around 830 recipes as opposed to the thousands
78 available in other OpenEmbedded community layers.
79 Keeping it small makes it easy to test and maintain.</para></listitem>
80 <listitem><para>The Yocto Project team runs manual and automated tests
81 using a small, fixed set of reference hardware as well as emulated
82 targets.</para></listitem>
83 <listitem><para>The Yocto Project uses an an autobuilder,
84 which provides continuous build and integration tests.</para></listitem>
85 </itemizedlist>
86 </para>
87 </answer>
88 </qandaentry>
89
90 <qandaentry>
91 <question>
92 <para>
93 How do I get support for my board added to the Yocto Project?
94 </para>
95 </question>
96 <answer>
97 <para>
98 Support for an additional board is added by creating a BSP layer for it.
99 For more information on how to create a BSP layer, see the
100 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
101 </para>
102 <para>
103 Usually, if the board is not completely exotic, adding support in
104 the Yocto Project is fairly straightforward.
105 </para>
106 </answer>
107 </qandaentry>
108
109 <qandaentry>
110 <question>
111 <para>
112 Are there any products built using the OpenEmbedded build system?
113 </para>
114 </question>
115 <answer>
116 <para>
117 The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink>
118 is built using the OpenEmbedded build system.
119 See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
120 website for more information.
121 There are a number of pre-production devices using the OpenEmbedded build system
122 and the Yocto Project team
123 announces them as soon as they are released.
124 </para>
125 </answer>
126 </qandaentry>
127
128 <qandaentry>
129 <question>
130 <para>
131 What does the OpenEmbedded build system produce as output?
132 </para>
133 </question>
134 <answer>
135 <para>
136 Because the same set of recipes can be used to create output of various formats, the
137 output of an OpenEmbedded build depends on how it was started.
138 Usually, the output is a flashable image ready for the target device.
139 </para>
140 </answer>
141 </qandaentry>
142
143 <qandaentry>
144 <question>
145 <para>
146 How do I add my package to the Yocto Project?
147 </para>
148 </question>
149 <answer>
150 <para>
151 To add a package, you need to create a BitBake recipe.
152 For information on how to add a package, see the section
153 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg'>Adding a Package</ulink>"
154 in the Yocto Project Development Manual.
155 </para>
156 </answer>
157 </qandaentry>
158
159 <qandaentry>
160 <question>
161 <para>
162 Do I have to reflash my entire board with a new Yocto Project image when recompiling
163 a package?
164 </para>
165 </question>
166 <answer>
167 <para>
168 The OpenEmbedded build system can build packages in various formats such as
169 <filename>ipk</filename> for <filename>opkg</filename>,
170 Debian package (<filename>.deb</filename>), or RPM.
171 The packages can then be upgraded using the package tools on the device, much like
172 on a desktop distribution such as Ubuntu or Fedora.
173 </para>
174 </answer>
175 </qandaentry>
176
177 <qandaentry>
178 <question>
179 <para>
180 What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
181 </para>
182 </question>
183 <answer>
184 <para>
185 GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink>
186 platform targeted at mobile and embedded devices.
187 The the main difference between GNOME Mobile and standard GNOME is that
188 desktop-orientated libraries have been removed, along with deprecated libraries,
189 creating a much smaller footprint.
190 </para>
191 </answer>
192 </qandaentry>
193
194 <qandaentry>
195 <question>
196 <para>
197 I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'.
198 What is wrong?
199 </para>
200 </question>
201 <answer>
202 <para>
203 You are probably running the build on an NTFS filesystem.
204 Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
205 </para>
206 </answer>
207 </qandaentry>
208
209 <qandaentry>
210 <question>
211 <para>
212 How do I make the Yocto Project work in RHEL/CentOS?
213 </para>
214 </question>
215 <answer>
216 <para>
217 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
218 install some required packages.
219 The standard CentOS packages needed are:
220 <itemizedlist>
221 <listitem><para>"Development tools" (selected during installation)</para></listitem>
222 <listitem><para><filename>texi2html</filename></para></listitem>
223 <listitem><para><filename>compat-gcc-34</filename></para></listitem>
224 </itemizedlist>
225 On top of these, you need the following external packages:
226 <itemizedlist>
227 <listitem><para><filename>python-sqlite2</filename> from
228 <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
229 </para></listitem>
230 <listitem><para><filename>help2man</filename> from
231 <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>
232 </itemizedlist>
233 </para>
234
235 <para>
236 Once these packages are installed, the OpenEmbedded build system will be able
237 to build standard images.
238 However, there might be a problem with the QEMU emulator segfaulting.
239 You can either disable the generation of binary locales by setting
240 <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
241 </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename>
242 from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
243 </para>
244 </answer>
245 </qandaentry>
246
247 <qandaentry>
248 <question>
249 <para>
250 I see lots of 404 responses for files on
251 <filename>http://www.yoctoproject.org/sources/*</filename>. Is something wrong?
252 </para>
253 </question>
254 <answer>
255 <para>
256 Nothing is wrong.
257 The OpenEmbedded build system checks any configured source mirrors before downloading
258 from the upstream sources.
259 The build system does this searching for both source archives and
260 pre-checked out versions of SCM managed software.
261 These checks help in large installations because it can reduce load on the SCM servers
262 themselves.
263 The address above is one of the default mirrors configured into the
264 build system.
265 Consequently, if an upstream source disappears, the team
266 can place sources there so builds continue to work.
267 </para>
268 </answer>
269 </qandaentry>
270
271 <qandaentry>
272 <question>
273 <para>
274 I have machine-specific data in a package for one machine only but the package is
275 being marked as machine-specific in all cases, how do I prevent this?
276 </para>
277 </question>
278 <answer>
279 <para>
280 Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
281 </filename> = "0" in the <filename>.bb</filename> file but make sure the package is
282 manually marked as
283 machine-specific in the case that needs it.
284 The code that handles <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in <filename>base.bbclass</filename>.
285 </para>
286 </answer>
287 </qandaentry>
288
289 <qandaentry>
290 <question>
291 <para>
292 I'm behind a firewall and need to use a proxy server. How do I do that?
293 </para>
294 </question>
295 <answer>
296 <para>
297 Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename>
298 and you therefore need to specify the proxy settings in a
299 <filename>.wgetrc</filename> file in your home directory.
300 Example settings in that file would be
301 <literallayout class='monospaced'>
302 http_proxy = http://proxy.yoyodyne.com:18023/
303 ftp_proxy = http://proxy.yoyodyne.com:18023/
304 </literallayout>
305 The Yocto Project also includes a <filename>site.conf.sample</filename>
306 file that shows how to configure CVS and Git proxy servers
307 if needed.
308 </para>
309 </answer>
310 </qandaentry>
311
312 <qandaentry>
313 <question>
314 <para>
315 What’s the difference between <filename>foo</filename> and <filename>foo-native</filename>?
316 </para>
317 </question>
318 <answer>
319 <para>
320 The <filename>*-native</filename> targets are designed to run on the system
321 being used for the build.
322 These are usually tools that are needed to assist the build in some way such as
323 <filename>quilt-native</filename>, which is used to apply patches.
324 The non-native version is the one that runs on the target device.
325 </para>
326 </answer>
327 </qandaentry>
328
329 <qandaentry>
330 <question>
331 <para>
332 I'm seeing random build failures. Help?!
333 </para>
334 </question>
335 <answer>
336 <para>
337 If the same build is failing in totally different and random ways,
338 the most likely explanation is that either the hardware you're running the
339 build on has some problem, or, if you are running the build under virtualisation,
340 the virtualisation probably has bugs.
341 The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and
342 CPU activity and is sensitive to even single bit failures in any of these areas.
343 True random failures have always been traced back to hardware or virtualisation issues.
344 </para>
345 </answer>
346 </qandaentry>
347
348 <qandaentry>
349 <question>
350 <para>
351 What do we need to ship for license compliance?
352 </para>
353 </question>
354 <answer>
355 <para>
356 This is a difficult question and you need to consult your lawyer for the answer
357 for your specific case.
358 It is worth bearing in mind that for GPL compliance there needs to be enough
359 information shipped to allow someone else to rebuild the same end result
360 you are shipping.
361 This means sharing the source code, any patches applied to it, and also any
362 configuration information about how that package was configured and built.
363 </para>
364 </answer>
365 </qandaentry>
366
367 <qandaentry>
368 <question>
369 <para>
370 How do I disable the cursor on my touchscreen device?
371 </para>
372 </question>
373 <answer>
374 <para>
375 You need to create a form factor file as described in the
376 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>"
377 section and set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to one as follows:
378 <literallayout class='monospaced'>
379 HAVE_TOUCHSCREEN=1
380 </literallayout>
381 </para>
382 </answer>
383 </qandaentry>
384
385 <qandaentry>
386 <question>
387 <para>
388 How do I make sure connected network interfaces are brought up by default?
389 </para>
390 </question>
391 <answer>
392 <para>
393 The default interfaces file provided by the netbase recipe does not
394 automatically bring up network interfaces.
395 Therefore, you will need to add a BSP-specific netbase that includes an interfaces
396 file.
397 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>"
398 section for information on creating these types of miscellaneous recipe files.
399 </para>
400 <para>
401 For example, add the following files to your layer:
402 <literallayout class='monospaced'>
403 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
404 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
405 </literallayout>
406 </para>
407 </answer>
408 </qandaentry>
409
410 <qandaentry>
411 <question>
412 <para>
413 How do I create images with more free space?
414 </para>
415 </question>
416 <answer>
417 <para>
418 Images are created to be 1.2 times the size of the populated root filesystem.
419 To modify this ratio so that there is more free space available, you need to
420 set the configuration value <filename>IMAGE_OVERHEAD_FACTOR</filename>.
421 For example, setting <filename>IMAGE_OVERHEAD_FACTOR</filename> to 1.5 sets
422 the image size ratio to one and a half times the size of the populated
423 root filesystem.
424 <literallayout class='monospaced'>
425 IMAGE_OVERHEAD_FACTOR = "1.5"
426 </literallayout>
427 </para>
428 </answer>
429 </qandaentry>
430
431 <qandaentry>
432 <question>
433 <para>
434 Why don't you support directories with spaces in the pathnames?
435 </para>
436 </question>
437 <answer>
438 <para>
439 The Yocto Project team has tried to do this before but too many of the tools
440 the OpenEmbedded build system depends on such as <filename>autoconf</filename>
441 break when they find spaces in pathnames.
442 Until that situation changes, the team will not support spaces in pathnames.
443 </para>
444 </answer>
445 </qandaentry>
446
447 <qandaentry>
448 <question>
449 <para>
450 How do I use an external toolchain?
451 </para>
452 </question>
453 <answer>
454 <para>
455 The toolchain configuration is very flexible and customizable.
456 It is primarily controlled with the
457 <filename><link linkend='var-TCMODE'>TCMODE</link></filename> variable.
458 This variable controls which <filename>tcmode-*.inc</filename> file to include
459 from the <filename>meta/conf/distro/include</filename> directory within the
460 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
461 </para>
462
463 <para>
464 The default value of <filename>TCMODE</filename> is "default"
465 (i.e. <filename>tcmode-default.inc</filename>).
466 However, other patterns are accepted.
467 In particular, "external-*" refers to external toolchains of which there are some
468 basic examples included in the OpenEmbedded Core (<filename>meta</filename>).
469 You can use your own custom toolchain definition in your own layer
470 (or as defined in the <filename>local.conf</filename> file) at the location
471 <filename>conf/distro/include/tcmode-*.inc</filename>.
472 </para>
473
474 <para>
475 In addition to the toolchain configuration, you also need a corresponding toolchain recipe file.
476 This recipe file needs to package up any pre-built objects in the toolchain such as
477 <filename>libgcc</filename>, <filename>libstdcc++</filename>,
478 any locales, and <filename>libc</filename>.
479 An example is the <filename>external-sourcery-toolchain.bb</filename>, which is located
480 in <filename>meta/recipes-core/meta/</filename> within the source directory.
481 </para>
482 </answer>
483 </qandaentry>
484
485 <qandaentry>
486 <question>
487 <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>
488 How does the OpenEmbedded build system obtain source code and will it work behind my
489 firewall or proxy server?
490 </para>
491 </question>
492 <answer>
493 <para>
494 The way the build system obtains source code is highly configurable.
495 You can setup the build system to get source code in most environments if
496 HTTP transport is available.
497 </para>
498 <para>
499 When the build system searches for source code, it first tries the local download directory.
500 If that location fails, Poky tries PREMIRRORS, the upstream source,
501 and then MIRRORS in that order.
502 </para>
503 <para>
504 By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS
505 for SCM-based sources,
506 upstreams for normal tarballs, and then falls back to a number of other mirrors
507 including the Yocto Project source mirror if those fail.
508 </para>
509 <para>
510 As an example, you could add a specific server for Poky to attempt before any
511 others by adding something like the following to the <filename>local.conf</filename>
512 configuration file:
513 <literallayout class='monospaced'>
514 PREMIRRORS_prepend = "\
515 git://.*/.* http://www.yoctoproject.org/sources/ \n \
516 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
517 http://.*/.* http://www.yoctoproject.org/sources/ \n \
518 https://.*/.* http://www.yoctoproject.org/sources/ \n"
519 </literallayout>
520 </para>
521 <para>
522 These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS
523 requests and direct them to the <filename>http://</filename> sources mirror.
524 You can use <filename>file://</filename> URLs to point to local directories
525 or network shares as well.
526 </para>
527 <para>
528 Aside from the previous technique, these options also exist:
529 <literallayout class='monospaced'>
530 BB_NO_NETWORK = "1"
531 </literallayout>
532 This statement tells BitBake to throw an error instead of trying to access the
533 Internet.
534 This technique is useful if you want to ensure code builds only from local sources.
535 </para>
536 <para>
537 Here is another technique:
538 <literallayout class='monospaced'>
539 BB_FETCH_PREMIRRORONLY = "1"
540 </literallayout>
541 This statement limits Poky to pulling source from the PREMIRRORS only.
542 Again, this technique is useful for reproducing builds.
543 </para>
544 <para>
545 Here is another technique:
546 <literallayout class='monospaced'>
547 BB_GENERATE_MIRROR_TARBALLS = "1"
548 </literallayout>
549 This statement tells Poky to generate mirror tarballs.
550 This technique is useful if you want to create a mirror server.
551 If not, however, the technique can simply waste time during the build.
552 </para>
553 <para>
554 Finally, consider an example where you are behind an HTTP-only firewall.
555 You could make the following changes to the <filename>local.conf</filename>
556 configuration file as long as the PREMIRROR server is up to date:
557 <literallayout class='monospaced'>
558 PREMIRRORS_prepend = "\
559 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
560 http://.*/.* http://www.yoctoproject.org/sources/ \n \
561 https://.*/.* http://www.yoctoproject.org/sources/ \n"
562 BB_FETCH_PREMIRRORONLY = "1"
563 </literallayout>
564 These changes would cause Poky to successfully fetch source over HTTP and
565 any network accesses to anything other than the PREMIRROR would fail.
566 </para>
567 <para>
568 The build system also honors the standard shell environment variables
569 <filename>http_proxy</filename>, <filename>ftp_proxy</filename>,
570 <filename>https_proxy</filename>, and <filename>all_proxy</filename>
571 to redirect requests through proxy servers.
572 </para>
573 </answer>
574 </qandaentry>
575
576 <qandaentry>
577 <question>
578 <para>
579 Can I get rid of build output so I can start over?
580 </para>
581 </question>
582 <answer>
583 <para>
584 Yes - you can easily do this.
585 When you use BitBake to build an image, all the build output goes into the
586 directory created when you source the <filename>oe-init-build-env</filename>
587 setup file.
588 By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>
589 is named <filename>build</filename> but can be named
590 anything you want.
591 </para>
592
593 <para>
594 Within the build directory is the <filename>tmp</filename> directory.
595 To remove all the build output yet preserve any source code or downloaded files
596 from previous builds, simply remove the <filename>tmp</filename> directory.
597 </para>
598 </answer>
599 </qandaentry>
600
601
602</qandaset>
603</chapter>
604<!--
605vim: expandtab tw=80 ts=4
606-->
diff --git a/documentation/ref-manual/figures/buildhistory-web.png b/documentation/ref-manual/figures/buildhistory-web.png
new file mode 100644
index 0000000000..f6db86c977
--- /dev/null
+++ b/documentation/ref-manual/figures/buildhistory-web.png
Binary files differ
diff --git a/documentation/ref-manual/figures/buildhistory.png b/documentation/ref-manual/figures/buildhistory.png
new file mode 100644
index 0000000000..614b8ee2e4
--- /dev/null
+++ b/documentation/ref-manual/figures/buildhistory.png
Binary files differ
diff --git a/documentation/ref-manual/figures/poky-title.png b/documentation/ref-manual/figures/poky-title.png
new file mode 100644
index 0000000000..2893d84620
--- /dev/null
+++ b/documentation/ref-manual/figures/poky-title.png
Binary files differ
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='intro'>
6<title>Introduction</title>
7
8<section id='intro-welcome'>
9 <title>Introduction</title>
10
11 <para>
12 This manual provides reference information for the current release of the Yocto Project.
13 The Yocto Project is an open-source collaboration project focused on embedded Linux
14 developers.
15 Amongst other things, the Yocto Project uses the OpenEmbedded build system, which
16 is based on the Poky project, to construct complete Linux images.
17 You can find complete introductory and getting started information on the Yocto Project
18 by reading the
19 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
20 For task-based information using the Yocto Project, see the
21 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>.
22 You can also find lots of information on the Yocto Project on the
23 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
24 </para>
25</section>
26
27<section id='intro-manualoverview'>
28 <title>Documentation Overview</title>
29 <para>
30 This reference manual consists of the following:
31 <itemizedlist>
32 <listitem><para><emphasis>
33 <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis> This chapter
34 provides an overview of the components that make up the Yocto Project
35 followed by information about debugging images created in the Yocto Project.
36 </para></listitem>
37 <listitem><para><emphasis>
38 <link linkend='technical-details'>Technical Details</link>:</emphasis>
39 This chapter describes fundamental Yocto Project components as well as an explanation
40 behind how the Yocto Project uses shared state (sstate) cache to speed build time.
41 </para></listitem>
42 <listitem><para><emphasis>
43 <link linkend='ref-structure'>Directory Structure</link>:</emphasis>
44 This chapter describes the
45 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink> created
46 either by unpacking a released Yocto Project tarball on your host development system,
47 or by cloning the upstream
48 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
49 </para></listitem>
50 <listitem><para><emphasis>
51 <link linkend='ref-bitbake'>BitBake</link>:</emphasis>
52 This chapter provides an overview of the BitBake tool and its role within
53 the Yocto Project.</para></listitem>
54 <listitem><para><emphasis>
55 <link linkend='ref-classes'>Classes</link>:</emphasis>
56 This chapter describes the classes used in the Yocto Project.</para></listitem>
57 <listitem><para><emphasis>
58 <link linkend='ref-images'>Images</link>:</emphasis>
59 This chapter describes the standard images that the Yocto Project supports.
60 </para></listitem>
61 <listitem><para><emphasis>
62 <link linkend='ref-features'>Features</link>:</emphasis>
63 This chapter describes mechanisms for creating distribution, machine, and image
64 features during the build process using the OpenEmbedded build system.</para></listitem>
65 <listitem><para><emphasis>
66 <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis>
67 This chapter presents most variables used by the OpenEmbedded build system, which
68 using BitBake.
69 Entries describe the function of the variable and how to apply them.
70 </para></listitem>
71 <listitem><para><emphasis>
72 <link linkend='ref-varlocality'>Variable Context</link>:</emphasis>
73 This chapter provides variable locality or context.</para></listitem>
74 <listitem><para><emphasis>
75 <link linkend='faq'>FAQ</link>:</emphasis>
76 This chapter provides answers for commonly asked questions in the Yocto Project
77 development environment.</para></listitem>
78 <listitem><para><emphasis>
79 <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis>
80 This chapter provides guidance on how you can contribute back to the Yocto
81 Project.</para></listitem>
82 </itemizedlist>
83 </para>
84</section>
85
86
87<section id='intro-requirements'>
88<title>System Requirements</title>
89 <para>
90 For general Yocto Project system requirements, see the
91 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" section
92 in the Yocto Project Quick Start.
93 The remainder of this section provides details on system requirements
94 not covered in the Yocto Project Quick Start.
95 </para>
96
97 <section id='detailed-supported-distros'>
98 <title>Supported Linux Distributions</title>
99
100 <para>
101 Currently, the Yocto Project is supported on the following distributions:
102 <itemizedlist>
103 <listitem><para>Ubuntu 10.04.4 LTS</para></listitem>
104 <listitem><para>Ubuntu 11.10</para></listitem>
105 <listitem><para>Ubuntu 12.04.1 LTS</para></listitem>
106 <listitem><para>Ubuntu 12.04.1 LTS</para></listitem>
107 <listitem><para>Ubuntu 12.10</para></listitem>
108 <listitem><para>Fedora release 16 (Verne)</para></listitem>
109 <listitem><para>Fedora release 17 (Beefy Miracle)</para></listitem>
110 <listitem><para>Fedora release 18 (Spherical Cow)</para></listitem>
111 <listitem><para>CentOS release 5.6 (Final)</para></listitem>
112 <listitem><para>CentOS release 5.7 (Final)</para></listitem>
113 <listitem><para>CentOS release 5.8 (Final)</para></listitem>
114 <listitem><para>CentOS release 6.3 (Final)</para></listitem>
115 <listitem><para>Debian GNU/Linux 6.0.6 (squeeze)</para></listitem>
116 <listitem><para>openSUSE 11.4</para></listitem>
117 <listitem><para>openSUSE 12.1</para></listitem>
118 <listitem><para>openSUSE 12.2</para></listitem>
119 </itemizedlist>
120 </para>
121
122 <note>
123 For additional information on distributions that support the
124 Yocto Project, see the
125 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink> wiki page.
126 </note>
127 </section>
128
129 <section id='required-packages-for-the-host-development-system'>
130 <title>Required Packages for the Host Development System</title>
131
132 <para>
133 The list of packages you need on the host development system can
134 be large when covering all build scenarios using the Yocto Project.
135 This section provides required packages by Linux distribution and
136 further categorized by function.
137 </para>
138
139 <section id='ubuntu-packages'>
140 <title>Ubuntu</title>
141
142 <para>
143 The following list shows the required packages by function
144 given a supported Ubuntu Linux distribution:
145 <itemizedlist>
146 <listitem><para><emphasis>Essentials:</emphasis>
147 Packages needed to build an image on a headless
148 system:
149 <literallayout class='monospaced'>
150 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
151 </literallayout></para></listitem>
152 <listitem><para><emphasis>Graphical Extras:</emphasis>
153 Packages recommended if the host system has graphics support:
154 <literallayout class='monospaced'>
155 $ sudo apt-get install libsdl1.2-dev xterm
156 </literallayout></para></listitem>
157 <listitem><para><emphasis>Documentation:</emphasis>
158 Packages needed if you are going to build out the
159 Yocto Project documentation manuals:
160 <literallayout class='monospaced'>
161 $ sudo apt-get install make xsltproc docbook-utils fop
162 </literallayout></para></listitem>
163 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
164 Packages needed if you are going to be using the
165 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
166 <literallayout class='monospaced'>
167 $ sudo apt-get install autoconf automake libtool libglib2.0-dev
168 </literallayout></para></listitem>
169 </itemizedlist>
170 </para>
171 </section>
172
173 <section id='fedora-packages'>
174 <title>Fedora Packages</title>
175
176 <para>
177 The following list shows the required packages by function
178 given a supported Fedora Linux distribution:
179 <itemizedlist>
180 <listitem><para><emphasis>Essentials:</emphasis>
181 Packages needed to build an image for a headless
182 system:
183 <literallayout class='monospaced'>
184 $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL;
185 </literallayout></para></listitem>
186 <listitem><para><emphasis>Graphical Extras:</emphasis>
187 Packages recommended if the host system has graphics support:
188 <literallayout class='monospaced'>
189 $ sudo yum install SDL-devel xterm
190 </literallayout></para></listitem>
191 <listitem><para><emphasis>Documentation:</emphasis>
192 Packages needed if you are going to build out the
193 Yocto Project documentation manuals:
194 <literallayout class='monospaced'>
195 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
196 docbook-dtds docbook-utils fop libxslt
197 </literallayout></para></listitem>
198 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
199 Packages needed if you are going to be using the
200 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
201 <literallayout class='monospaced'>
202 $ sudo yum install autoconf automake libtool glib2-devel
203 </literallayout></para></listitem>
204 </itemizedlist>
205 </para>
206 </section>
207
208 <section id='opensuse-packages'>
209 <title>OpenSUSE Packages</title>
210
211 <para>
212 The following list shows the required packages by function
213 given a supported OpenSUSE Linux distribution:
214 <itemizedlist>
215 <listitem><para><emphasis>Essentials:</emphasis>
216 Packages needed to build an image for a headless
217 system:
218 <literallayout class='monospaced'>
219 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
220 </literallayout></para></listitem>
221 <listitem><para><emphasis>Graphical Extras:</emphasis>
222 Packages recommended if the host system has graphics support:
223 <literallayout class='monospaced'>
224 $ sudo zypper install libSDL-devel xterm
225 </literallayout></para></listitem>
226 <listitem><para><emphasis>Documentation:</emphasis>
227 Packages needed if you are going to build out the
228 Yocto Project documentation manuals:
229 <literallayout class='monospaced'>
230 $ sudo zypper install make fop xsltproc
231 </literallayout></para></listitem>
232 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
233 Packages needed if you are going to be using the
234 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
235 <literallayout class='monospaced'>
236 $ sudo zypper install autoconf automake libtool glib2-devel
237 </literallayout></para></listitem>
238 </itemizedlist>
239 </para>
240 </section>
241
242 <section id='centos-packages'>
243 <title>CentOS Packages</title>
244
245 <para>
246 The following list shows the required packages by function
247 given a supported CentOS Linux distribution:
248 <itemizedlist>
249 <listitem><para><emphasis>Essentials:</emphasis>
250 Packages needed to build an image for a headless
251 system:
252 <literallayout class='monospaced'>
253 $ sudo yum -y install &CENTOS_HOST_PACKAGES_ESSENTIAL;
254 </literallayout></para></listitem>
255 <listitem><para><emphasis>Graphical Extras:</emphasis>
256 Packages recommended if the host system has graphics support:
257 <literallayout class='monospaced'>
258 $ sudo yum -y install SDL-devel xterm
259 </literallayout></para></listitem>
260 <listitem><para><emphasis>Documentation:</emphasis>
261 Packages needed if you are going to build out the
262 Yocto Project documentation manuals:
263 <literallayout class='monospaced'>
264 $ sudo yum -y install make docbook-style-dsssl docbook-style-xsl \
265 docbook-dtds docbook-utils fop libxslt
266 </literallayout></para></listitem>
267 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
268 Packages needed if you are going to be using the
269 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
270 <literallayout class='monospaced'>
271 $ sudo yum -y install autoconf automake libtool glib2-devel
272 </literallayout></para></listitem>
273 </itemizedlist>
274 <note>Depending on the CentOS version you are using, other requirements
275 and dependencies might exist.
276 For details, you should look at the CentOS sections on the
277 <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink>
278 wiki page.</note>
279 </para>
280 </section>
281 </section>
282</section>
283
284<section id='intro-getit'>
285 <title>Obtaining the Yocto Project</title>
286 <para>
287 The Yocto Project development team makes the Yocto Project available through a number
288 of methods:
289 <itemizedlist>
290 <listitem><para><emphasis>Releases:</emphasis> Stable, tested releases are available through
291 <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem>
292 <listitem><para><emphasis>Nightly Builds:</emphasis> These releases are available at
293 <ulink url='http://autobuilder.yoctoproject.org/nightly'/>.
294 These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and
295 experimental builds.</para></listitem>
296 <listitem><para><emphasis>Yocto Project Website:</emphasis> You can find releases
297 of the Yocto Project and supported BSPs at the
298 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
299 Along with these downloads, you can find lots of other information at this site.
300 </para></listitem>
301 </itemizedlist>
302 </para>
303</section>
304
305<section id='intro-getit-dev'>
306 <title>Development Checkouts</title>
307 <para>
308 Development using the Yocto Project requires a local
309 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
310 You can set up the source directory by downloading a Yocto Project release tarball and unpacking it,
311 or by cloning a copy of the upstream
312 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
313 For information on both these methods, see the
314 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Setup</ulink>"
315 section in the Yocto Project Development Manual.
316 </para>
317</section>
318
319</chapter>
320<!--
321vim: expandtab tw=80 ts=4
322-->
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='migration'>
6<title>Migrating to a Newer Yocto Project Release</title>
7
8 <para>
9 This chapter provides information you can use to migrate work to a
10 newer Yocto Project release. You can find the same information in the
11 release notes for a given release.
12 </para>
13
14<section id='moving-to-the-yocto-project-1.3-release'>
15 <title>Moving to the Yocto Project 1.3 Release</title>
16
17 <para>
18 This section provides migration information for moving to the
19 Yocto Project 1.3 Release.
20 </para>
21
22 <section id='1.3-local-configuration'>
23 <title>Local Configuration</title>
24
25 <para>
26 Differences include changes for
27 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
28 and <filename>bblayers.conf</filename>.
29 </para>
30
31 <section id='migration-1.3-sstate-mirrors'>
32 <title>SSTATE_MIRRORS</title>
33
34 <para>
35 The shared state cache (sstate-cache) as pointed to by
36 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> by default
37 now has two-character subdirectories to prevent there being an issue with too
38 many files in the same directory.
39 Also, native sstate-cache packages will go into a subdirectory named using
40 the distro ID string.
41 If you copy the newly structured sstate-cache to a mirror location
42 (either local or remote) and then point to it in
43 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>,
44 you need to append "PATH" to the end of the mirror URL so that
45 the path used by BitBake before the mirror substitution is
46 appended to the path used to access the mirror.
47 Here is an example:
48 <literallayout class='monospaced'>
49 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
50 </literallayout>
51 </para>
52 </section>
53
54 <section id='migration-1.3-bblayers-conf'>
55 <title>bblayers.conf</title>
56
57 <para>
58 The <filename>meta-yocto</filename> layer has been split into
59 two parts: <filename>meta-yocto</filename> and
60 <filename>meta-yocto-bsp</filename>, corresponding to the
61 Poky reference distro configuration and the reference
62 hardware Board Support Packages (BSPs), respectively.
63 When running BitBake or Hob for the first time after upgrading,
64 your <filename>conf/bblayers.conf</filename> file will be
65 updated to handle this change and you will be asked to
66 re-run/restart for the changes to take effect.
67 </para>
68 </section>
69 </section>
70
71 <section id='1.3-recipes'>
72 <title>Recipes</title>
73
74 <para>
75 Differences include changes for the following:
76 <itemizedlist>
77 <listitem><para>Python function whitespace</para></listitem>
78 <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem>
79 <listitem><para><filename>nativesdk</filename></para></listitem>
80 <listitem><para>Task recipes</para></listitem>
81 <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem>
82 <listitem><para>Removed recipes</para></listitem>
83 </itemizedlist>
84 </para>
85
86 <section id='migration-1.3-python-function-whitespace'>
87 <title>Python Function Whitespace</title>
88
89 <para>
90 All Python functions must now use four spaces for indentation.
91 Previously, an inconsistent mix of spaces and tabs existed,
92 which made extending these functions using
93 <filename>_append</filename> or <filename>_prepend</filename>
94 complicated given that Python treats whitespace as
95 syntactically significant.
96 If you are defining or extending any Python functions (e.g.
97 <filename>populate_packages</filename>, <filename>do_unpack</filename>,
98 <filename>do_patch</filename> and so forth) in custom recipes
99 or classes, you need to ensure you are using consistent
100 four-space indentation.
101 </para>
102 </section>
103
104 <section id='migration-1.3-proto=-in-src-uri'>
105 <title>proto= in SRC_URI</title>
106
107 <para>
108 Any use of <filename>proto=</filename> in
109 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
110 needs to be changed to <filename>protocol=</filename>.
111 In particular, this applies to the following URIs:
112 <itemizedlist>
113 <listitem><para><filename>svn://</filename></para></listitem>
114 <listitem><para><filename>bzr://</filename></para></listitem>
115 <listitem><para><filename>hg://</filename></para></listitem>
116 <listitem><para><filename>osc://</filename></para></listitem>
117 </itemizedlist>
118 Other URIs were already using <filename>protocol=</filename>.
119 This change improves consistency.
120 </para>
121 </section>
122
123 <section id='migration-1.3-nativesdk'>
124 <title>nativesdk</title>
125
126 <para>
127 The suffix <filename>nativesdk</filename> is now implemented
128 as a prefix, which simplifies a lot of the packaging code for
129 <filename>nativesdk</filename> recipes.
130 All custom <filename>nativesdk</filename> recipes and any
131 references need to be updated to use
132 <filename>nativesdk-*</filename> instead of
133 <filename>*-nativesdk</filename>.
134 </para>
135 </section>
136
137 <section id='migration-1.3-task-recipes'>
138 <title>Task Recipes</title>
139
140 <para>
141 "Task" recipes are now known as "Package groups" and have
142 been renamed from <filename>task-*.bb</filename> to
143 <filename>packagegroup-*.bb</filename>.
144 Existing references to the previous <filename>task-*</filename>
145 names should work in most cases as there is an automatic
146 upgrade path for most packages.
147 However, you should update references in your own recipes and
148 configurations as they could be removed in future releases.
149 You should also rename any custom <filename>task-*</filename>
150 recipes to <filename>packagegroup-*</filename>, and change
151 them to inherit <filename>packagegroup</filename> instead of
152 <filename>task</filename>, as well as taking the opportunity
153 to remove anything now handled by
154 <filename>packagegroup.bbclass</filename>, such as providing
155 <filename>-dev</filename> and <filename>-dbg</filename>
156 packages, setting
157 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>,
158 and so forth.
159 See the
160 "<link linkend='ref-classes-packagegroup'>Package Groups - packagegroup.bbclass</link>"
161 section for further details.
162 </para>
163 </section>
164
165 <section id='migration-1.3-image-features'>
166 <title>IMAGE_FEATURES</title>
167
168 <para>
169 Image recipes that previously included "apps-console-core"
170 in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
171 should now include "splash" instead to enable the boot-up
172 splash screen.
173 Retaining "apps-console-core" will still include the splash
174 screen generates a warning.
175 The "apps-x11-core" and "apps-x11-games"
176 <filename>IMAGE_FEATURES</filename> features have been removed.
177 </para>
178 </section>
179
180 <section id='migration-1.3-removed-recipes'>
181 <title>Removed Recipes</title>
182
183 <para>
184 The following recipes have been removed.
185 For most of them, it is unlikely that you would have any
186 references to them in your own metadata.
187 However, you should check your metadata against this list to be sure:
188 <itemizedlist>
189 <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>:
190 Replaced by <filename>libx11</filename>, which has a negligible
191 size difference with modern Xorg.</para></listitem>
192 <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>:
193 Use <filename>xserver-xorg</filename>, which has a negligible
194 size difference when DRI and GLX modules are not installed.</para></listitem>
195 <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>:
196 Effectively unmaintained for many years.</para></listitem>
197 <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>:
198 No longer serves any purpose.</para></listitem>
199 <listitem><para><emphasis><filename>galago</filename></emphasis>:
200 Replaced by telepathy.</para></listitem>
201 <listitem><para><emphasis><filename>gail</filename></emphasis>:
202 Functionality was integrated into GTK+ 2.13.</para></listitem>
203 <listitem><para><emphasis><filename>eggdbus</filename></emphasis>:
204 No longer needed.</para></listitem>
205 <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>:
206 The build has been restructured to avoid the need for
207 this step.</para></listitem>
208 <listitem><para><emphasis><filename>libgsmd</filename></emphasis>:
209 Unmaintained for many years.
210 Functionality now provided by
211 <filename>ofono</filename> instead.</para></listitem>
212 <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>:
213 Largely unmaintained PIM application suite.
214 It has been moved to <filename>meta-gnome</filename>
215 in <filename>meta-openembedded</filename>.</para></listitem>
216 </itemizedlist>
217 In addition to the previously listed changes, the
218 <filename>meta-demoapps</filename> directory has also been removed
219 because the recipes in it were not being maintained and many
220 had become obsolete or broken.
221 Additionally, these recipes were not parsed in the default configuration.
222 Many of these recipes are already provided in an updated and
223 maintained form within OpenEmbedded community layers such as
224 <filename>meta-oe</filename> and <filename>meta-gnome</filename>.
225 For the remainder, you can now find them in the
226 <filename>meta-extras</filename> repository, which is in the
227 Yocto Project source repositories.
228 </para>
229 </section>
230 </section>
231</section>
232</chapter>
233<!--
234vim: expandtab tw=80 ts=4
235-->
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-bitbake'>
6
7 <title>BitBake</title>
8
9 <para>
10 BitBake is a program written in Python that interprets the metadata used by the OpenEmbedded
11 build system.
12 At some point, developers wonder what actually happens when you enter:
13 <literallayout class='monospaced'>
14 $ bitbake core-image-sato
15 </literallayout>
16 </para>
17
18 <para>
19 This chapter provides an overview of what happens behind the scenes from BitBake's perspective.
20 </para>
21
22 <note>
23 BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships.
24 As such, it has no real knowledge of what the tasks being executed actually do.
25 BitBake just considers a list of tasks with dependencies and handles metadata
26 that consists of variables in a certain format that get passed to the tasks.
27 </note>
28
29 <section id='ref-bitbake-parsing'>
30 <title>Parsing</title>
31
32 <para>
33 BitBake parses configuration files, classes, and <filename>.bb</filename> files.
34 </para>
35
36 <para>
37 The first thing BitBake does is look for the <filename>bitbake.conf</filename> file.
38 This file resides in the
39 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
40 within the <filename>meta/conf/</filename> directory.
41 BitBake finds it by examining its
42 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> environment
43 variable and looking for the <filename>meta/conf/</filename>
44 directory.
45 </para>
46
47 <para>
48 The <filename>bitbake.conf</filename> file lists other configuration
49 files to include from a <filename>conf/</filename>
50 directory below the directories listed in <filename>BBPATH</filename>.
51 In general, the most important configuration file from a user's perspective
52 is <filename>local.conf</filename>, which contains a user's customized
53 settings for the OpenEmbedded build environment.
54 Other notable configuration files are the distribution
55 configuration file (set by the
56 <filename><link linkend='var-DISTRO'>DISTRO</link></filename> variable)
57 and the machine configuration file
58 (set by the
59 <filename><link linkend='var-MACHINE'>MACHINE</link></filename> variable).
60 The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake environment
61 variables are both usually set in
62 the <filename>local.conf</filename> file.
63 Valid distribution
64 configuration files are available in the <filename>meta/conf/distro/</filename> directory
65 and valid machine configuration
66 files in the <filename>meta/conf/machine/</filename> directory.
67 Within the <filename>meta/conf/machine/include/</filename>
68 directory are various <filename>tune-*.inc</filename> configuration files that provide common
69 "tuning" settings specific to and shared between particular architectures and machines.
70 </para>
71
72 <para>
73 After the parsing of the configuration files, some standard classes are included.
74 The <filename>base.bbclass</filename> file is always included.
75 Other classes that are specified in the configuration using the
76 <filename><link linkend='var-INHERIT'>INHERIT</link></filename>
77 variable are also included.
78 Class files are searched for in a <filename>classes</filename> subdirectory
79 under the paths in <filename>BBPATH</filename> in the same way as
80 configuration files.
81 </para>
82
83 <para>
84 After classes are included, the variable
85 <filename><link linkend='var-BBFILES'>BBFILES</link></filename>
86 is set, usually in
87 <filename>local.conf</filename>, and defines the list of places to search for
88 <filename>.bb</filename> files.
89 By default, the <filename>BBFILES</filename> variable specifies the
90 <filename>meta/recipes-*/</filename> directory within Poky.
91 Adding extra content to <filename>BBFILES</filename> is best achieved through the use of
92 BitBake layers as described in the
93 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
94 Creating Layers</ulink>" section of the Yocto Project Development Manual.
95 </para>
96
97 <para>
98 BitBake parses each <filename>.bb</filename> file in <filename>BBFILES</filename> and
99 stores the values of various variables.
100 In summary, for each <filename>.bb</filename>
101 file the configuration plus the base class of variables are set, followed
102 by the data in the <filename>.bb</filename> file
103 itself, followed by any inherit commands that
104 <filename>.bb</filename> file might contain.
105 </para>
106
107 <para>
108 Because parsing <filename>.bb</filename> files is a time
109 consuming process, a cache is kept to speed up subsequent parsing.
110 This cache is invalid if the timestamp of the <filename>.bb</filename>
111 file itself changes, or if the timestamps of any of the include,
112 configuration or class files the <filename>.bb</filename>
113 file depends on changes.
114 </para>
115 </section>
116
117 <section id='ref-bitbake-providers'>
118 <title>Preferences and Providers</title>
119
120 <para>
121 Once all the <filename>.bb</filename> files have been
122 parsed, BitBake starts to build the target (<filename>core-image-sato</filename>
123 in the previous section's example) and looks for providers of that target.
124 Once a provider is selected, BitBake resolves all the dependencies for
125 the target.
126 In the case of <filename>core-image-sato</filename>, it would lead to
127 <filename>packagegroup-core-x11-sato</filename>,
128 which in turn leads to recipes like <filename>matchbox-terminal</filename>,
129 <filename>pcmanfm</filename> and <filename>gthumb</filename>.
130 These recipes in turn depend on <filename>eglibc</filename> and the toolchain.
131 </para>
132
133 <para>
134 Sometimes a target might have multiple providers.
135 A common example is "virtual/kernel", which is provided by each kernel package.
136 Each machine often selects the best kernel provider by using a line similar to the
137 following in the machine configuration file:
138 </para>
139
140 <literallayout class='monospaced'>
141 PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
142 </literallayout>
143
144 <para>
145 The default <filename><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></filename>
146 is the provider with the same name as the target.
147 </para>
148
149 <para>
150 Understanding how providers are chosen is made complicated by the fact
151 that multiple versions might exist.
152 BitBake defaults to the highest version of a provider.
153 Version comparisons are made using the same method as Debian.
154 You can use the
155 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
156 variable to specify a particular version (usually in the distro configuration).
157 You can influence the order by using the
158 <filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></filename>
159 variable.
160 By default, files have a preference of "0".
161 Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
162 package unlikely to be used unless it is explicitly referenced.
163 Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the package is used.
164 <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting.
165 <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental package
166 versions until they have undergone sufficient testing to be considered stable.
167 </para>
168
169 <para>
170 In summary, BitBake has created a list of providers, which is prioritized, for each target.
171 </para>
172 </section>
173
174 <section id='ref-bitbake-dependencies'>
175 <title>Dependencies</title>
176
177 <para>
178 Each target BitBake builds consists of multiple tasks such as
179 <filename>fetch</filename>, <filename>unpack</filename>,
180 <filename>patch</filename>, <filename>configure</filename>,
181 and <filename>compile</filename>.
182 For best performance on multi-core systems, BitBake considers each task as an independent
183 entity with its own set of dependencies.
184 </para>
185
186 <para>
187 Dependencies are defined through several variables.
188 You can find information about variables BitBake uses in the BitBake documentation,
189 which is found in the <filename>bitbake/doc/manual</filename> directory within the
190 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
191 At a basic level, it is sufficient to know that BitBake uses the
192 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename> and
193 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variables when
194 calculating dependencies.
195 </para>
196 </section>
197
198 <section id='ref-bitbake-tasklist'>
199 <title>The Task List</title>
200
201 <para>
202 Based on the generated list of providers and the dependency information,
203 BitBake can now calculate exactly what tasks it needs to run and in what
204 order it needs to run them.
205 The build now starts with BitBake forking off threads up to the limit set in the
206 <filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></filename> variable.
207 BitBake continues to fork threads as long as there are tasks ready to run,
208 those tasks have all their dependencies met, and the thread threshold has not been
209 exceeded.
210 </para>
211
212 <para>
213 It is worth noting that you can greatly speed up the build time by properly setting
214 the <filename>BB_NUMBER_THREADS</filename> variable.
215 See the
216 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
217 section in the Yocto Project Quick Start for more information.
218 </para>
219
220 <para>
221 As each task completes, a timestamp is written to the directory specified by the
222 <filename><link linkend='var-STAMP'>STAMP</link></filename> variable.
223 On subsequent runs, BitBake looks within the <filename>/build/tmp/stamps</filename>
224 directory and does not rerun
225 tasks that are already completed unless a timestamp is found to be invalid.
226 Currently, invalid timestamps are only considered on a per
227 <filename>.bb</filename> file basis.
228 So, for example, if the configure stamp has a timestamp greater than the
229 compile timestamp for a given target, then the compile task would rerun.
230 Running the compile task again, however, has no effect on other providers
231 that depend on that target.
232 This behavior could change or become configurable in future versions of BitBake.
233 </para>
234
235 <note>
236 Some tasks are marked as "nostamp" tasks.
237 No timestamp file is created when these tasks are run.
238 Consequently, "nostamp" tasks are always rerun.
239 </note>
240 </section>
241
242 <section id='ref-bitbake-runtask'>
243 <title>Running a Task</title>
244
245 <para>
246 Tasks can either be a shell task or a Python task.
247 For shell tasks, BitBake writes a shell script to
248 <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script.
249 The generated shell script contains all the exported variables, and the shell functions
250 with all variables expanded.
251 Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
252 Looking at the expanded shell functions in the run file and the output in the log files
253 is a useful debugging technique.
254 </para>
255
256 <para>
257 For Python tasks, BitBake executes the task internally and logs information to the
258 controlling terminal.
259 Future versions of BitBake will write the functions to files similar to the way
260 shell tasks are handled.
261 Logging will be handled in way similar to shell tasks as well.
262 </para>
263
264 <para>
265 Once all the tasks have been completed BitBake exits.
266 </para>
267
268 <para>
269 When running a task, BitBake tightly controls the execution environment
270 of the build tasks to make sure unwanted contamination from the build machine
271 cannot influence the build.
272 Consequently, if you do want something to get passed into the build
273 task's environment, you must take a few steps:
274 <orderedlist>
275 <listitem><para>Tell BitBake to load what you want from the environment
276 into the data store.
277 You can do so through the <filename>BB_ENV_EXTRAWHITE</filename>
278 variable.
279 For example, assume you want to prevent the build system from
280 accessing your <filename>$HOME/.ccache</filename> directory.
281 The following command tells BitBake to load
282 <filename>CCACHE_DIR</filename> from the environment into the data
283 store:
284 <literallayout class='monospaced'>
285 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
286 </literallayout></para></listitem>
287 <listitem><para>Tell BitBake to export what you have loaded into the
288 environment store to the task environment of every running task.
289 Loading something from the environment into the data store
290 (previous step) only makes it available in the datastore.
291 To export it to the task environment of every running task,
292 use a command similar to the following in your
293 <filename>local.conf</filename> or distro configuration file:
294 <literallayout class='monospaced'>
295 export CCACHE_DIR
296 </literallayout></para></listitem>
297 </orderedlist>
298 </para>
299
300 <note>
301 A side effect of the previous steps is that BitBake records the variable
302 as a dependency of the build process in things like the shared state
303 checksums.
304 If doing so results in unnecessary rebuilds of tasks, you can whitelist the
305 variable so that the shared state code ignores the dependency when it creates
306 checksums.
307 For information on this process, see the <filename>BB_HASHBASE_WHITELIST</filename>
308 example in the "<link linkend='checksums'>Checksums (Signatures)</link>" section.
309 </note>
310 </section>
311
312 <section id='ref-bitbake-commandline'>
313 <title>BitBake Command Line</title>
314
315 <para>
316 Following is the BitBake help output:
317 </para>
318
319 <screen>
320$ bitbake --help
321Usage: bitbake [options] [package ...]
322
323Executes the specified task (default is 'build') for a given set of BitBake files.
324It expects that BBFILES is defined, which is a space separated list of files to
325be executed. BBFILES does support wildcards.
326Default BBFILES are the .bb files in the current directory.
327
328Options:
329 --version show program's version number and exit
330 -h, --help show this help message and exit
331 -b BUILDFILE, --buildfile=BUILDFILE
332 execute the task against this .bb file, rather than a
333 package from BBFILES. Does not handle any
334 dependencies.
335 -k, --continue continue as much as possible after an error. While the
336 target that failed, and those that depend on it,
337 cannot be remade, the other dependencies of these
338 targets can be processed all the same.
339 -a, --tryaltconfigs continue with builds by trying to use alternative
340 providers where possible.
341 -f, --force force run of specified cmd, regardless of stamp status
342 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes
343 the specified task for the providee and the packages
344 it depends on, i.e. 'compile' does not implicitly call
345 stage for the dependencies (IOW: use only if you know
346 what you are doing). Depending on the base.bbclass a
347 listtasks tasks is defined and will show available
348 tasks
349 -r PREFILE, --read=PREFILE
350 read the specified file before bitbake.conf
351 -R POSTFILE, --postread=POSTFILE
352 read the specified file after bitbake.conf
353 -v, --verbose output more chit-chat to the terminal
354 -D, --debug Increase the debug level. You can specify this more
355 than once.
356 -n, --dry-run don't execute, just go through the motions
357 -S, --dump-signatures
358 don't execute, just dump out the signature
359 construction information
360 -p, --parse-only quit after parsing the BB files (developers only)
361 -s, --show-versions show current and preferred versions of all packages
362 -e, --environment show the global or per-package environment (this is
363 what used to be bbread)
364 -g, --graphviz emit the dependency trees of the specified packages in
365 the dot syntax
366 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
367 Assume these dependencies don't exist and are already
368 provided (equivalent to ASSUME_PROVIDED). Useful to
369 make dependency graphs more appealing
370 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
371 Show debug logging for the specified logging domains
372 -P, --profile profile the command and print a report
373 -u UI, --ui=UI userinterface to use
374 -t SERVERTYPE, --servertype=SERVERTYPE
375 Choose which server to use, none, process or xmlrpc
376 --revisions-changed Set the exit code depending on whether upstream
377 floating revisions have changed or not
378 </screen>
379 </section>
380
381 <section id='ref-bitbake-fetchers'>
382 <title>Fetchers</title>
383
384 <para>
385 BitBake also contains a set of "fetcher" modules that allow
386 retrieval of source code from various types of sources.
387 For example, BitBake can get source code from a disk with the metadata, from websites,
388 from remote shell accounts or from Source Code Management (SCM) systems
389 like <filename>cvs/subversion/git</filename>.
390 </para>
391
392 <para>
393 Fetchers are usually triggered by entries in
394 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>.
395 You can find information about the options and formats of entries for specific
396 fetchers in the BitBake manual located in the
397 <filename>bitbake/doc/manual</filename> directory of the
398 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
399 </para>
400
401 <para>
402 One useful feature for certain Source Code Manager (SCM) fetchers is the ability to
403 "auto-update" when the upstream SCM changes version.
404 Since this ability requires certain functionality from the SCM, not all
405 systems support it.
406 Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update".
407 This feature works using the <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
408 variable.
409 See the
410 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-srcrev'>Using an External SCM</ulink>" section
411 in the Yocto Project Development Manual for more information.
412 </para>
413
414 </section>
415
416</chapter>
417<!--
418vim: expandtab tw=80 ts=4 spell spelllang=en_gb
419-->
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-classes'>
6<title>Classes</title>
7
8<para>
9 Class files are used to abstract common functionality and share it amongst multiple
10 <filename>.bb</filename> files.
11 Any metadata usually found in a <filename>.bb</filename> file can also be placed in a class
12 file.
13 Class files are identified by the extension <filename>.bbclass</filename> and are usually placed
14 in a <filename>classes/</filename> directory beneath the
15 <filename>meta*/</filename> directory found in the
16 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
17 Class files can also be pointed to by BUILDDIR (e.g. <filename>build/</filename>)in the same way as
18 <filename>.conf</filename> files in the <filename>conf</filename> directory.
19 Class files are searched for in <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
20 using the same method by which <filename>.conf</filename> files are searched.
21</para>
22
23<para>
24 In most cases inheriting the class is enough to enable its features, although
25 for some classes you might need to set variables or override some of the
26 default behaviour.
27</para>
28
29<section id='ref-classes-base'>
30 <title>The base class - <filename>base.bbclass</filename></title>
31
32 <para>
33 The base class is special in that every <filename>.bb</filename>
34 file inherits it automatically.
35 This class contains definitions for standard basic
36 tasks such as fetching, unpacking, configuring (empty by default), compiling
37 (runs any <filename>Makefile</filename> present), installing (empty by default) and packaging
38 (empty by default).
39 These classes are often overridden or extended by other classes
40 such as <filename>autotools.bbclass</filename> or <filename>package.bbclass</filename>.
41 The class also contains some commonly used functions such as <filename>oe_runmake</filename>.
42 </para>
43</section>
44
45<section id='ref-classes-autotools'>
46 <title>Autotooled Packages - <filename>autotools.bbclass</filename></title>
47
48 <para>
49 Autotools (<filename>autoconf</filename>, <filename>automake</filename>,
50 and <filename>libtool</filename>) bring standardization.
51 This class defines a set of tasks (configure, compile etc.) that
52 work for all Autotooled packages.
53 It should usually be enough to define a few standard variables
54 and then simply <filename>inherit autotools</filename>.
55 This class can also work with software that emulates Autotools.
56 For more information, see the
57 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg-autotools'>Autotooled Package</ulink>"
58 section in the Yocto Project Development Manual.
59 </para>
60
61 <para>
62 It's useful to have some idea of how the tasks defined by this class work
63 and what they do behind the scenes.
64 <itemizedlist>
65 <listitem><para><filename>do_configure</filename> &dash; regenerates the
66 configure script (using <filename>autoreconf</filename>) and then launches it
67 with a standard set of arguments used during cross-compilation.
68 You can pass additional parameters to <filename>configure</filename> through the
69 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
70 </para></listitem>
71 <listitem><para><filename>do_compile</filename> &dash; runs <filename>make</filename> with
72 arguments that specify the compiler and linker.
73 You can pass additional arguments through
74 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
75 </para></listitem>
76 <listitem><para><filename>do_install</filename> &dash; runs <filename>make install</filename>
77 and passes a DESTDIR option, which takes its value from the standard
78 <filename><link linkend='var-DESTDIR'>DESTDIR</link></filename> variable.
79 </para></listitem>
80 </itemizedlist>
81 </para>
82</section>
83
84<section id='ref-classes-update-alternatives'>
85 <title>Alternatives - <filename>update-alternatives.bbclass</filename></title>
86
87 <para>
88 Several programs can fulfill the same or similar function and be installed with the same name.
89 For example, the <filename>ar</filename> command is available from the
90 <filename>busybox</filename>, <filename>binutils</filename> and
91 <filename>elfutils</filename> packages.
92 The <filename>update-alternatives.bbclass</filename> class handles renaming the
93 binaries so that multiple packages can be installed without conflicts.
94 The <filename>ar</filename> command still works regardless of which packages are installed
95 or subsequently removed.
96 The class renames the conflicting binary in each package and symlinks the highest
97 priority binary during installation or removal of packages.
98 </para>
99 <para>
100 Four variables control this class:
101 <itemizedlist>
102 <listitem><para><filename>ALTERNATIVE_NAME</filename> &dash; The name of the
103 binary that is replaced (<filename>ar</filename> in this example).</para></listitem>
104 <listitem><para><filename>ALTERNATIVE_LINK</filename> &dash; The path to
105 the resulting binary (<filename>/bin/ar</filename> in this example).</para></listitem>
106 <listitem><para><filename>ALTERNATIVE_PATH</filename> &dash; The path to the
107 real binary (<filename>/usr/bin/ar.binutils</filename> in this example).</para></listitem>
108 <listitem><para><filename>ALTERNATIVE_PRIORITY</filename> &dash; The priority of
109 the binary.
110 The version with the most features should have the highest priority.</para></listitem>
111 </itemizedlist>
112 </para>
113
114 <para>
115 Currently, the OpenEmbedded build system supports only one binary per package.
116 </para>
117</section>
118
119<section id='ref-classes-update-rc.d'>
120 <title>Initscripts - <filename>update-rc.d.bbclass</filename></title>
121
122 <para>
123 This class uses <filename>update-rc.d</filename> to safely install an
124 initialization script on behalf of the package.
125 The OpenEmbedded build system takes care of details such as making sure the script is stopped before
126 a package is removed and started when the package is installed.
127 Three variables control this class:
128 <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
129 <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
130 <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
131 See the variable links for details.
132 </para>
133</section>
134
135<section id='ref-classes-binconfig'>
136 <title>Binary config scripts - <filename>binconfig.bbclass</filename></title>
137
138 <para>
139 Before <filename>pkg-config</filename> had become widespread, libraries shipped shell
140 scripts to give information about the libraries and include paths needed
141 to build software (usually named <filename>LIBNAME-config</filename>).
142 This class assists any recipe using such scripts.
143 </para>
144
145 <para>
146 During staging, BitBake installs such scripts into the
147 <filename>sysroots/</filename> directory.
148 BitBake also changes all paths to point into the <filename>sysroots/</filename>
149 directory so all builds that use the script will use the correct
150 directories for the cross compiling layout.
151 </para>
152</section>
153
154<section id='ref-classes-debian'>
155 <title>Debian renaming - <filename>debian.bbclass</filename></title>
156
157 <para>
158 This class renames packages so that they follow the Debian naming
159 policy (i.e. <filename>eglibc</filename> becomes <filename>libc6</filename>
160 and <filename>eglibc-devel</filename> becomes <filename>libc6-dev</filename>.
161 </para>
162</section>
163
164<section id='ref-classes-pkgconfig'>
165 <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title>
166
167 <para>
168 <filename>pkg-config</filename> brought standardization and this class aims to make its
169 integration smooth for all libraries that make use of it.
170 </para>
171
172 <para>
173 During staging, BitBake installs <filename>pkg-config</filename> data into the
174 <filename>sysroots/</filename> directory.
175 By making use of sysroot functionality within <filename>pkg-config</filename>,
176 this class no longer has to manipulate the files.
177 </para>
178</section>
179
180<section id='ref-classes-src-distribute'>
181 <title>Distribution of sources - <filename>src_distribute_local.bbclass</filename></title>
182
183 <para>
184 Many software licenses require that source files be provided along with the binaries.
185 To simplify this process, two classes were created:
186 <filename>src_distribute.bbclass</filename> and
187 <filename>src_distribute_local.bbclass</filename>.
188 </para>
189
190 <para>
191 The results of these classes are <filename>tmp/deploy/source/</filename>
192 subdirs with sources sorted by
193 <filename><link linkend='var-LICENSE'>LICENSE</link></filename> field.
194 If recipes list few licenses (or have entries like "Bitstream Vera"),
195 the source archive is placed in each license directory.
196 </para>
197
198 <para>
199 This class operates using three modes:
200 <itemizedlist>
201 <listitem><para><emphasis>copy:</emphasis> Copies the files to the
202 distribute directory.</para></listitem>
203 <listitem><para><emphasis>symlink:</emphasis> Symlinks the files to the
204 distribute directory.</para></listitem>
205 <listitem><para><emphasis>move+symlink:</emphasis> Moves the files into
206 the distribute directory and then symlinks them back.</para></listitem>
207 </itemizedlist>
208 </para>
209</section>
210
211<section id='ref-classes-perl'>
212 <title>Perl modules - <filename>cpan.bbclass</filename></title>
213
214 <para>
215 Recipes for Perl modules are simple.
216 These recipes usually only need to point to the source's archive and then inherit the
217 proper <filename>.bbclass</filename> file.
218 Building is split into two methods depending on which method the module authors used.
219 </para>
220
221 <para>
222 Modules that use old <filename>Makefile.PL</filename>-based build system require
223 <filename>cpan.bbclass</filename> in their recipes.
224 </para>
225
226 <para>
227 Modules that use <filename>Build.PL</filename>-based build system require
228 using <filename>cpan_build.bbclass</filename> in their recipes.
229 </para>
230</section>
231
232<section id='ref-classes-distutils'>
233 <title>Python extensions - <filename>distutils.bbclass</filename></title>
234
235 <para>
236 Recipes for Python extensions are simple.
237 These recipes usually only need to point to the source's archive and then inherit
238 the proper <filename>.bbclass</filename> file.
239 Building is split into two methods dependling on which method the module authors used.
240 </para>
241
242 <para>
243 Extensions that use an Autotools-based build system require Autotools and
244 <filename>distutils</filename>-based <filename>.bbclasse</filename> files in their recipes.
245 </para>
246
247 <para>
248 Extensions that use <filename>distutils</filename>-based build systems require
249 <filename>distutils.bbclass</filename> in their recipes.
250 </para>
251</section>
252
253<section id='ref-classes-devshell'>
254 <title>Developer Shell - <filename>devshell.bbclass</filename></title>
255
256 <para>
257 This class adds the <filename>devshell</filename> task.
258 Distribution policy dictates whether to include this class.
259 See the
260 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
261 in the Yocto Project Development Manual for more information about using <filename>devshell</filename>.
262 </para>
263</section>
264
265<section id='ref-classes-packagegroup'>
266 <title>Package Groups - <filename>packagegroup.bbclass</filename></title>
267
268 <para>
269 This class sets default values appropriate for package group recipes (such as
270 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
271 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
272 <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
273 and so forth.
274 It is highly recommended that all package group recipes inherit this class.
275 </para>
276 <para>
277 For information on how to use this class, see the
278 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Tasks</ulink>"
279 section in the Yocto Project Development Manual.
280 </para>
281 <para>
282 Previously, this class was named <filename>task.bbclass</filename>.
283 </para>
284</section>
285
286
287<section id='ref-classes-package'>
288 <title>Packaging - <filename>package*.bbclass</filename></title>
289
290 <para>
291 The packaging classes add support for generating packages from a build's
292 output.
293 The core generic functionality is in <filename>package.bbclass</filename>.
294 The code specific to particular package types is contained in various sub-classes such as
295 <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>,
296 and <filename>package_rpm.bbclass</filename>.
297 Most users will want one or more of these classes.
298 </para>
299
300 <para>
301 You can control the list of resulting package formats by using the
302 <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
303 variable defined in the <filename>local.conf</filename> configuration file,
304 which is located in the <filename>conf</filename> folder of the
305 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
306 When defining the variable, you can specify one or more package types.
307 Since images are generated from packages, a packaging class is
308 needed to enable image generation.
309 The first class listed in this variable is used for image generation.
310 </para>
311
312 <para>
313 The package class you choose can affect build-time performance and has space
314 ramifications.
315 In general, building a package with RPM takes about thirty percent more time as
316 compared to using IPK to build the same or similar package.
317 This comparison takes into account a complete build of the package with all
318 dependencies previously built.
319 The reason for this discrepancy is because the RPM package manager creates and
320 processes more metadata than the IPK package manager.
321 Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename>
322 to "package_ipk" if you are building smaller systems.
323 </para>
324
325 <para>
326 Keep in mind, however, that RPM starts to provide more abilities than IPK due to
327 the fact that it processes more metadata.
328 For example, this information includes individual file types, file checksum generation
329 and evaluation on install, sparse file support, conflict detection and resolution
330 for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks.
331 </para>
332
333 <para>
334 Another consideration for packages built using the RPM package manager is space.
335 For smaller systems, the extra space used for the Berkley Database and the amount
336 of metadata can affect your ability to do on-device upgrades.
337 </para>
338
339 <para>
340 You can find additional information on the effects of the package class at these
341 two Yocto Project mailing list links:
342 <itemizedlist>
343 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
344 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
345 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'>
346 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
347 </itemizedlist>
348 </para>
349</section>
350
351<section id='ref-classes-kernel'>
352 <title>Building kernels - <filename>kernel.bbclass</filename></title>
353
354 <para>
355 This class handles building Linux kernels.
356 The class contains code to build all kernel trees.
357 All needed headers are staged into the
358 <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename>
359 directory to allow out-of-tree module builds using <filename>module.bbclass</filename>.
360 </para>
361
362 <para>
363 This means that each built kernel module is packaged separately and inter-module
364 dependencies are created by parsing the <filename>modinfo</filename> output.
365 If all modules are required, then installing the <filename>kernel-modules</filename>
366 package installs all packages with modules and various other kernel packages
367 such as <filename>kernel-vmlinux</filename>.
368 </para>
369
370 <para>
371 Various other classes are used by the kernel and module classes internally including
372 <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>,
373 <filename>module-base.bbclass</filename>, and <filename>linux-kernel-base.bbclass</filename>.
374 </para>
375</section>
376
377<section id='ref-classes-image'>
378 <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
379
380 <para>
381 These classes add support for creating images in several formats.
382 First, the root filesystem is created from packages using
383 one of the <filename>rootfs_*.bbclass</filename>
384 files (depending on the package format used) and then the image is created.
385 </para>
386
387 <para>
388 The <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
389 variable controls the types of images to generate.
390 </para>
391
392 <para>
393 The <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
394 variable controls the list of packages to install into the image.
395 </para>
396</section>
397
398<section id='ref-classes-sanity'>
399 <title>Host System sanity checks - <filename>sanity.bbclass</filename></title>
400
401 <para>
402 This class checks to see if prerequisite software is present so that
403 users can be notified of potential problems that might affect their build.
404 The class also performs basic user configuration checks from
405 the <filename>local.conf</filename> configuration file to
406 prevent common mistakes that cause build failures.
407 Distribution policy usually determines whether to include this class.
408 </para>
409</section>
410
411<section id='ref-classes-insane'>
412 <title>Generated output quality assurance checks - <filename>insane.bbclass</filename></title>
413
414 <para>
415 This class adds a step to the package generation process that sanity checks the
416 packages generated by the OpenEmbedded build system.
417 A range of checks are performed that check the build's output
418 for common problems that show up during runtime.
419 Distribution policy usually dictates whether to include this class.
420 </para>
421
422 <para>
423 You can configure the sanity checks so that specific test failures either raise a warning or
424 an error message.
425 Typically, failures for new tests generate a warning.
426 Subsequent failures for the same test would then generate an error message
427 once the metadata is in a known and good condition.
428 You use the <filename>WARN_QA</filename> variable to specify tests for which you
429 want to generate a warning message on failure.
430 You use the <filename>ERROR_QA</filename> variable to specify tests for which you
431 want to generate an error message on failure.
432 </para>
433
434 <para>
435 The following list shows the tests you can list with the <filename>WARN_QA</filename>
436 and <filename>ERROR_QA</filename> variables:
437 <itemizedlist>
438 <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
439 Ensures that the binaries were linked with the
440 <filename>LDFLAGS</filename> options provided by the build system.
441 If this test fails, check that the <filename>LDFLAGS</filename> variable
442 is being passed to the linker command.</para></listitem>
443 <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
444 Checks for dynamic library load paths (rpaths) in the binaries that
445 by default on a standard system are searched by the linker (e.g.
446 <filename>/lib</filename> and <filename>/usr/lib</filename>).
447 While these paths will not cause any breakage, they do waste space and
448 are unnecessary.</para></listitem>
449 <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
450 Checks for rpaths in the binaries that contain build system paths such
451 as <filename>TMPDIR</filename>.
452 If this test fails, bad <filename>-rpath</filename> options are being
453 passed to the linker commands and your binaries have potential security
454 issues.</para></listitem>
455 <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
456 Checks that the <filename>.so</filename> symbolic links are in the
457 <filename>-dev</filename> package and not in any of the other packages.
458 In general, these symlinks are only useful for development purposes.
459 Thus, the <filename>-dev</filename> package is the correct location for
460 them.
461 Some very rare cases do exist for dynamically loaded modules where
462 these symlinks are needed instead in the main package.
463 </para></listitem>
464 <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
465 Checks for <filename>.debug</filename> directories in anything but the
466 <filename>-dbg</filename> package.
467 The debug files should all be in the <filename>-dbg</filename> package.
468 Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
469 <listitem><para><emphasis><filename>arch:</filename></emphasis>
470 Checks the Executable and Linkable Format (ELF) type, bit size and endianness
471 of any binaries to ensure it matches the target architecture.
472 This test fails if any binaries don't match the type since there would be an
473 incompatibility.
474 Sometimes software, like bootloaders, might need to bypass this check.
475 </para></listitem>
476 <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
477 Checks that <filename>-dbg</filename> packages only depend on other
478 <filename>-dbg</filename> packages and not on any other types of packages,
479 which would cause a packaging bug.</para></listitem>
480 <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
481 Checks that <filename>-dev</filename> packages only depend on other
482 <filename>-dev</filename> packages and not on any other types of packages,
483 which would be a packaging bug.</para></listitem>
484 <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
485 Checks <filename>.pc</filename> files for any
486 <filename>TMPDIR/WORKDIR</filename> paths.
487 Any <filename>.pc</filename> file containing these paths is incorrect
488 since <filename>pkg-config</filename> itself adds the correct sysroot prefix
489 when the files are accessed.</para></listitem>
490 <listitem><para><emphasis><filename>la:</filename></emphasis>
491 Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
492 paths.
493 Any <filename>.la</filename> file continaing these paths is incorrect since
494 <filename>libtool</filename> adds the correct sysroot prefix when using the
495 files automatically itself.</para></listitem>
496 <listitem><para><emphasis><filename>desktop:</filename></emphasis>
497 Runs the <filename>desktop-file-validate</filename> program against any
498 <filename>.desktop</filename> files to validate their contents against
499 the specification for <filename>.desktop</filename> files.</para></listitem>
500 </itemizedlist>
501 </para>
502</section>
503
504<section id='ref-classes-siteinfo'>
505 <title>Autotools configuration data cache - <filename>siteinfo.bbclass</filename></title>
506
507 <para>
508 Autotools can require tests that must execute on the target hardware.
509 Since this is not possible in general when cross compiling, site information is
510 used to provide cached test results so these tests can be skipped over but
511 still make the correct values available.
512 The <filename><link linkend='structure-meta-site'>meta/site directory</link></filename>
513 contains test results sorted into different categories such as architecture, endianness, and
514 the <filename>libc</filename> used.
515 Site information provides a list of files containing data relevant to
516 the current build in the
517 <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
518 that Autotools automatically picks up.
519 </para>
520
521 <para>
522 The class also provides variables like
523 <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
524 and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
525 that can be used elsewhere in the metadata.
526 </para>
527
528 <para>
529 Because this class is included from <filename>base.bbclass</filename>, it is always active.
530 </para>
531</section>
532
533<section id='ref-classes-useradd'>
534 <title>Adding Users - <filename>useradd.bbclass</filename></title>
535
536 <para>
537 If you have packages that install files that are owned by custom users or groups,
538 you can use this class to specify those packages and associate the users and groups
539 with those packages.
540 The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
541 recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
542 provides a simple exmample that shows how to add three
543 users and groups to two packages.
544 See the <filename>useradd-example.bb</filename> for more information on how to
545 use this class.
546 </para>
547</section>
548
549<section id='ref-classes-externalsrc'>
550 <title>Using External Source - <filename>externalsrc.bbclass</filename></title>
551
552 <para>
553 You can use this class to build software from source code that is external to the
554 OpenEmbedded build system.
555 In other words, your source code resides in an external tree outside of the Yocto Project.
556 Building software from an external source tree means that the normal fetch, unpack, and
557 patch process is not used.
558 </para>
559
560 <para>
561 To use the class, you need to define the
562 <link linkend='var-S'><filename>S</filename></link> variable to point to the directory that contains the source files.
563 You also need to have your recipe inherit the <filename>externalsrc.bbclass</filename> class.
564 </para>
565
566 <para>
567 This class expects the source code to support recipe builds that use the
568 <link linkend='var-B'><filename>B</filename></link> variable to point to the directory in
569 which the OpenEmbedded build system places the generated objects built from the recipes.
570 By default, the <filename>B</filename> directory is set to the following, which is separate from the
571 Source Directory (<filename>S</filename>):
572 <literallayout class='monospaced'>
573 ${WORKDIR}/${BPN}/{PV}/
574 </literallayout>
575 See the glossary entries for the
576 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
577 <link linkend='var-BPN'><filename>BPN</filename></link>,
578 <link linkend='var-PV'><filename>PV</filename></link>,
579 <link linkend='var-S'><filename>S</filename></link>, and
580 <link linkend='var-B'><filename>B</filename></link> for more information.
581 </para>
582
583 <para>
584 You can build object files in the external tree by setting the
585 <filename>B</filename> variable equal to <filename>"${S}"</filename>.
586 However, this practice does not work well if you use the source for more than one variant
587 (i.e., "natives" such as <filename>quilt-native</filename>,
588 or "crosses" such as <filename>gcc-cross</filename>).
589 So, be sure there are no "native", "cross", or "multilib" variants of the recipe.
590 </para>
591
592 <para>
593 If you do want to build different variants of a recipe, you can use the
594 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> variable.
595 When you do, the <link linkend='var-B'><filename>B</filename></link> variable must support the
596 recipe's ability to build variants in different working directories.
597 Most autotools-based recipes support separating these directories.
598 The OpenEmbedded build system defaults to using separate directories for <filename>gcc</filename>
599 and some kernel recipes.
600 Alternatively, you can make sure that separate recipes exist that each
601 use the <filename>BBCLASSEXTEND</filename> variable to build each variant.
602 The separate recipes can inherit a single target recipe.
603 </para>
604
605 <para>
606 For information on how to use this class, see the
607 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building
608 Software from an External Source</ulink>" section in the Yocto Project Development Manual.
609 </para>
610</section>
611
612<section id='ref-classes-others'>
613 <title>Other Classes</title>
614
615 <para>
616 Thus far, this chapter has discussed only the most useful and important
617 classes.
618 However, other classes exist within the <filename>meta/classes</filename> directory
619 in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
620 You can examine the <filename>.bbclass</filename> files directly for more
621 information.
622 </para>
623</section>
624
625<!-- Undocumented classes are:
626 allarch.bbclass
627 archive*.bbclass
628 binconfig.bbclass
629 blacklist.bbclass
630 bootimg.bbclass
631 boot-directdisk.bbclass
632 bugzilla.bbclass
633 buildhistory.bbclass
634 buildstats.bbclass
635 ccache.bbclass
636 chrpath.bbclass
637 cmake.bbclass
638 cml1.bbclass
639 copyleft_compliance.bbclass
640 core-image.bbclass
641 cross.bbclass
642 cross-canadian.bbclass
643 crosssdk.bbclass
644 deploy.bbclass
645 distrodata.bbclass
646 dummy.bbclass
647 gconf.bbclass
648 gettext.bbclass
649 gnomebase.bbclass
650 gnome.bbclass
651 gtk-doc.bbclass
652 gtk-icon-cache.bbclass
653 gzipnative.bbclass
654 icecc.bbclass
655 image-empty.bbclass
656 image-live.bbclass
657 image-vmdk.bbclass
658 image-mklibs.bbclass
659 image-prelink.bbclass
660 image-swab.bbclass
661 imagetest-dummy.bbclass
662 imagetest-qemu.bbclass
663 image_types.bbclass
664 image_types_uboot.bbclass
665 insserv.bbclass
666 kernel-arch.bbclass
667 kernel-yocto.bbclass
668 lib_package.bbclass
669 linux-kernel-base.bbclass
670 license.bbclass
671 logging.bbclass
672 meta.bbclass
673 metadata_scm.bbclass
674 mime.bbclass
675 mirrors.bbclass
676 multilib*.bbclass
677 native.bbclass
678 nativesdk.bbclass
679 oelint.bbclass
680 own-mirrors.bbclass
681 packagedata.bbclass
682 packageinfo.bbclass
683 patch.bbclass
684 perlnative.bbclass
685 pkg_distribute.bbclass
686 pkg_metainfo.bbclass
687 populate_sdk*.bbclass
688 prexport.bbclass
689 primport.bbclass
690 prserv.bbclass
691 python-dir.bbclass
692 pythonnative.bbclass
693 qemu.bbclass
694 qmake*.bbclass
695 qt4*.bbclass
696 recipe_sanity.bbclass
697 relocatable.bbclass
698 rm_work.bbclass
699 scons.bbclass
700 sdl.bbclass
701 setuptools.bbclass
702 sip.bbclass
703 siteconfig.bbclass
704 sourcepkg.bbclass
705 sstate.bbclass
706 staging.bbclass
707 syslinux.bbclass
708 terminal.bbclass
709 tinderclient.bbclass
710 toolchain-scripts.bbclass
711 typecheck.bbclass
712 utility-tasks.bbclass
713 utils.bbclass
714-->
715
716
717</chapter>
718<!--
719vim: expandtab tw=80 ts=4
720-->
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-features'>
6 <title>Reference: Features</title>
7
8 <para>
9 Features provide a mechanism for working out which packages
10 should be included in the generated images.
11 Distributions can select which features they want to support through the
12 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
13 variable, which is set in the <filename>poky.conf</filename> distribution configuration file.
14 Machine features are set in the
15 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
16 variable, which is set in the machine configuration file and
17 specifies the hardware features for a given machine.
18 </para>
19
20 <para>
21 These two variables combine to work out which kernel modules,
22 utilities, and other packages to include.
23 A given distribution can support a selected subset of features so some machine features might not
24 be included if the distribution itself does not support them.
25 </para>
26
27 <para>
28 One method you can use to determine which recipes are checking to see if a
29 particular feature is contained or not is to <filename>grep</filename> through
30 the metadata for the feature.
31 Here is an example that discovers the recipes whose build is potentially
32 changed based on a given feature:
33 <literallayout class='monospaced'>
34 $ cd $HOME/poky
35 $ git grep 'contains.*MACHINE_FEATURES.*&lt;feature&gt;'
36 </literallayout>
37 </para>
38
39 <para>
40 This chapter provides a reference of shipped machine and distro features
41 you can include as part of the image, a reference on image types you can
42 build, and a reference on feature backfilling.
43 </para>
44
45
46 <section id='ref-features-distro'>
47 <title>Distro</title>
48
49 <para>
50 The items below are features you can use with
51 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
52 Features do not have a one-to-one correspondence to packages, and they can
53 go beyond simply controlling the installation of a package or packages.
54 Sometimes a feature can influence how certain recipes are built.
55 For example, a feature might determine whether a particular configure option
56 is specified within <filename>do_configure</filename> for a particular
57 recipe.
58 </para>
59
60 <para>
61 This list only represents features as shipped with the Yocto Project metadata:
62 <itemizedlist>
63 <listitem><para><emphasis>alsa:</emphasis> ALSA support will be included (OSS compatibility
64 kernel modules will be installed if available).</para></listitem>
65 <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only)
66 </para></listitem>
67 <listitem><para><emphasis>ext2:</emphasis> Include tools for supporting for devices with internal
68 HDD/Microdrive for storing files (instead of Flash only devices)
69 </para></listitem>
70 <listitem><para><emphasis>irda:</emphasis> Include Irda support
71 </para></listitem>
72 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard support (e.g. keymaps will be
73 loaded during boot).
74 </para></listitem>
75 <listitem><para><emphasis>pci:</emphasis> Include PCI bus support
76 </para></listitem>
77 <listitem><para><emphasis>pcmcia:</emphasis> Include PCMCIA/CompactFlash support
78 </para></listitem>
79 <listitem><para><emphasis>usbgadget:</emphasis> USB Gadget Device support (for USB
80 networking/serial/storage)
81 </para></listitem>
82 <listitem><para><emphasis>usbhost:</emphasis> USB Host support (allows to connect external
83 keyboard, mouse, storage, network etc)
84 </para></listitem>
85 <listitem><para><emphasis>wifi:</emphasis> WiFi support (integrated only)
86 </para></listitem>
87 <listitem><para><emphasis>cramfs:</emphasis> CramFS support
88 </para></listitem>
89 <listitem><para><emphasis>ipsec:</emphasis> IPSec support
90 </para></listitem>
91 <listitem><para><emphasis>ipv6:</emphasis> IPv6 support
92 </para></listitem>
93 <listitem><para><emphasis>nfs:</emphasis> NFS client support (for mounting NFS exports on
94 device)</para></listitem>
95 <listitem><para><emphasis>ppp:</emphasis> PPP dialup support</para></listitem>
96 <listitem><para><emphasis>smbfs:</emphasis> SMB networks client support (for mounting
97 Samba/Microsoft Windows shares on device)</para></listitem>
98 </itemizedlist>
99 </para>
100 </section>
101
102 <section id='ref-features-machine'>
103 <title>Machine</title>
104
105 <para>
106 The items below are features you can use with
107 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
108 Features do not have a one-to-one correspondence to packages, and they can
109 go beyond simply controlling the installation of a package or packages.
110 Sometimes a feature can influence how certain recipes are built.
111 For example, a feature might determine whether a particular configure option
112 is specified within <filename>do_configure</filename> for a particular
113 recipe.
114 </para>
115
116 <para>
117 This feature list only represents features as shipped with the Yocto Project metadata:
118 <itemizedlist>
119 <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)
120 </para></listitem>
121 <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers
122 </para></listitem>
123 <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)
124 </para></listitem>
125 <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT
126 </para></listitem>
127 <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive
128 </para></listitem>
129 <listitem><para><emphasis>irda:</emphasis> Hardware has Irda support
130 </para></listitem>
131 <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard
132 </para></listitem>
133 <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus
134 </para></listitem>
135 <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets
136 </para></listitem>
137 <listitem><para><emphasis>screen:</emphasis> Hardware has a screen
138 </para></listitem>
139 <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)
140 </para></listitem>
141 <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen
142 </para></listitem>
143 <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable
144 </para></listitem>
145 <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable
146 </para></listitem>
147 <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi
148 </para></listitem>
149 </itemizedlist>
150 </para>
151 </section>
152
153 <section id='ref-features-image'>
154 <title>Images</title>
155
156 <para>
157 The contents of images generated by the OpenEmbedded build system can be controlled by the
158 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
159 and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename>
160 variables that you typically configure in your image recipes.
161 Through these variables you can add several different
162 predefined packages such as development utilities or packages with debug
163 information needed to investigate application problems or profile applications.
164 </para>
165
166 <para>
167 Current list of
168 <filename>IMAGE_FEATURES</filename> contains the following:
169 <itemizedlist>
170 <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot.
171 By default, this screen is provided by <filename>psplash</filename>, which does
172 allow customization.
173 If you prefer to use an alternative splash screen package, you can do so by
174 setting the <filename>SPLASH</filename> variable
175 to a different package name (or names) within the image recipe or at the distro
176 configuration level.</para></listitem>
177 <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal
178 SSH server.
179 </para></listitem>
180 <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server,
181 which is more full-featured than Dropbear.
182 Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server
183 are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
184 precedence and Dropbear will not be installed.</para></listitem>
185 <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem>
186 <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a
187 minimal environment.</para></listitem>
188 <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment.
189 </para></listitem>
190 <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device.
191 </para></listitem>
192 <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as
193 <filename>strace</filename> and <filename>gdb</filename>.
194 </para></listitem>
195 <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as
196 <filename>oprofile</filename>, <filename>exmap</filename>, and
197 <filename>LTTng</filename>.</para></listitem>
198 <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g.
199 touchscreen debugging).</para></listitem>
200 <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem>
201 <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and
202 extra library links) for all packages installed in a given image.</para></listitem>
203 <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development
204 packages (i.e. static libraries containing <filename>*.a</filename> files) for all
205 packages installed in a given image.</para></listitem>
206 <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages
207 installed in a given image.</para></listitem>
208 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages
209 installed in a given image.</para></listitem>
210 </itemizedlist>
211 </para>
212 </section>
213
214 <section id='ref-features-backfill'>
215 <title>Feature Backfilling</title>
216
217 <para>
218 Sometimes it is necessary in the OpenEmbedded build system to extend
219 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
220 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
221 to control functionality that was previously enabled and not able
222 to be disabled.
223 For these cases, we need to add an
224 additional feature item to appear in one of these variables,
225 but we do not want to force developers who have existing values
226 of the variables in their configuration to add the new feature
227 in order to retain the same overall level of functionality.
228 Thus, the OpenEmbedded build system has a mechanism to
229 automatically "backfill" these added features into existing
230 distro or machine configurations.
231 You can see the list of features for which this is done by
232 finding the
233 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
234 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
235 variables in the <filename>meta/conf/bitbake.conf</filename> file.
236 </para>
237
238 <para>
239 Because such features are backfilled by default into all
240 configurations as described in the previous paragraph, developers
241 who wish to disable the new features need to be able to selectively
242 prevent the backfilling from occurring.
243 They can do this by adding the undesired feature or features to the
244 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
245 or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
246 variables for distro features and machine features respectively.
247 </para>
248
249 <para>
250 Here are two examples to help illustrate feature backfilling:
251 <itemizedlist>
252 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
253 Previously, PulseAudio support was enabled within the Qt and
254 GStreamer frameworks.
255 Because of this, the feature is backfilled and thus
256 enabled for all distros through the
257 <filename>DISTRO_FEATURES_BACKFILL</filename>
258 variable in the <filename>meta/conf/bitbake.conf</filename> file.
259 However, your distro needs to disable the feature.
260 You can disable the feature without affecting
261 other existing distro configurations that need PulseAudio support
262 by adding "pulseaudio" to
263 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
264 in your distro's <filename>.conf</filename> file.
265 Adding the feature to this variable when it also
266 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
267 variable prevents the build system from adding the feature to
268 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
269 the feature for that particular distro.</para></listitem>
270 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
271 Previously, real time clock (RTC) support was enabled for all
272 target devices.
273 Because of this, the feature is backfilled and thus enabled
274 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
275 variable in the <filename>meta/conf/bitbake.conf</filename> file.
276 However, your target device does not have this capability.
277 You can disable RTC support for your device without
278 affecting other machines that need RTC support
279 by adding the feature to your machine's
280 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
281 list in the machine's <filename>.conf</filename> file.
282 Adding the feature to this variable when it also
283 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
284 variable prevents the build system from adding the feature to
285 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
286 disabling RTC support for that particular machine.</para></listitem>
287 </itemizedlist>
288 </para>
289 </section>
290</chapter>
291
292<!--
293vim: expandtab tw=80 ts=4 spell spelllang=en_gb
294-->
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-images'>
6 <title>Images</title>
7
8 <para>
9 The OpenEmbedded build process supports several types of images to satisfy different needs.
10 When you issue the <filename>bitbake</filename> command you provide a “top-level†recipe
11 that essentially begins the build for the type of image you want.
12 </para>
13
14 <note>
15 Building an image without GNU General Public License Version 3 (GPLv3) components
16 is only supported for minimal and base images.
17 Furthermore, if you are going to build an image using non-GPLv3 components,
18 you must make the following changes in the <filename>local.conf</filename> file
19 before using the BitBake command to build the minimal or base image:
20 <literallayout class='monospaced'>
21 1. Comment out the EXTRA_IMAGE_FEATURES line
22 2. Set INCOMPATIBLE_LICENSE = "GPLv3"
23 </literallayout>
24 </note>
25
26 <para>
27 From within the <filename>poky</filename> Git repository, use the following command to list
28 the supported images:
29 <literallayout class='monospaced'>
30 $ ls meta*/recipes*/images/*.bb
31 </literallayout>
32 These recipes reside in the <filename>meta/recipes-core/images</filename>,
33 <filename>meta/recipes-extended/images</filename>,
34 <filename>meta/recipes-graphics/images</filename>, and
35 <filename>meta/recipes-sato/images</filename> directories
36 within the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
37 Although the recipe names are somewhat explanatory, here is a list that describes them:
38 </para>
39
40 <itemizedlist>
41 <listitem><para><emphasis><filename>core-image-base</filename>:</emphasis>
42 A console-only image that fully supports the target device hardware.</para></listitem>
43 <listitem><para><emphasis><filename>core-image-minimal</filename>:</emphasis>
44 A small image just capable of allowing a device to boot.</para></listitem>
45 <listitem><para><emphasis><filename>core-image-minimal-dev</filename>:</emphasis>
46 A <filename>core-image-minimal</filename> image suitable for development work
47 using the host.
48 The image includes headers and libraries you can use in a host development
49 environment.
50 </para></listitem>
51 <listitem><para><emphasis><filename>core-image-minimal-initramfs</filename>:</emphasis>
52 A <filename>core-image-minimal</filename> image that has the Minimal RAM-based
53 Initial Root Filesystem (<filename>initramfs</filename>) as part of the kernel,
54 which allows the system to find the first “init†program more efficiently.
55 </para></listitem>
56 <listitem><para><emphasis><filename>core-image-minimal-mtdutils</filename>:</emphasis>
57 A <filename>core-image-minimal</filename> image that has support
58 for the Minimal MTD Utilities, which let the user interact with the
59 MTD subsystem in the kernel to perform operations on flash devices.
60 </para></listitem>
61 <listitem><para><emphasis><filename>core-image-x11</filename>:</emphasis>
62 A very basic X11 image with a terminal.
63 </para></listitem>
64 <listitem><para><emphasis><filename>core-image-basic</filename>:</emphasis>
65 A console-only image with more full-featured Linux system
66 functionality installed.</para></listitem>
67 <listitem><para><emphasis><filename>core-image-lsb</filename>:</emphasis>
68 An image that conforms to the Linux Standard Base (LSB) specification.</para></listitem>
69 <listitem><para><emphasis><filename>core-image-lsb-dev</filename>:</emphasis>
70 A <filename>core-image-lsb</filename> image that is suitable for development work
71 using the host.
72 The image includes headers and libraries you can use in a host development
73 environment.
74 </para></listitem>
75 <listitem><para><emphasis><filename>core-image-lsb-sdk</filename>:</emphasis>
76 A <filename>core-image-lsb</filename> that includes everything in meta-toolchain
77 but also includes development headers and libraries to form a complete standalone SDK.
78 This image is suitable for development using the target.</para></listitem>
79 <listitem><para><emphasis><filename>core-image-clutter</filename>:</emphasis>
80 An image with support for the Open GL-based toolkit Clutter, which enables development of
81 rich and animated graphical user interfaces.</para></listitem>
82 <listitem><para><emphasis><filename>core-image-sato</filename>:</emphasis>
83 An image with Sato support, a mobile environment and visual style that works well
84 with mobile devices.
85 The image supports X11 with a Sato theme and applications such as
86 a terminal, editor, file manager, media player, and so forth.</para></listitem>
87 <listitem><para><emphasis><filename>core-image-sato-dev</filename>:</emphasis>
88 A <filename>core-image-sato</filename> image suitable for development
89 using the host.
90 The image includes libraries needed to build applications on the device itself,
91 testing and profiling tools, and debug symbols.
92 This image was formerly <filename>core-image-sdk</filename>.</para></listitem>
93 <listitem><para><emphasis><filename>core-image-sato-sdk</filename>:</emphasis>
94 A <filename>core-image-sato</filename> image that includes everything in meta-toolchain.
95 The image also includes development headers and libraries to form a complete standalone SDK
96 and is suitable for development using the target.</para></listitem>
97 <listitem><para><emphasis><filename>core-image-rt</filename>:</emphasis>
98 A <filename>core-image-minimal</filename> image plus a real-time test suite and
99 tools appropriate for real-time use.</para></listitem>
100 <listitem><para><emphasis><filename>core-image-rt-sdk</filename>:</emphasis>
101 A <filename>core-image-rt</filename> image that includes everything in
102 <filename>meta-toolchain</filename>.
103 The image also includes development headers and libraries to form a complete
104 stand-alone SDK and is suitable for development using the target.</para></listitem>
105 <listitem><para><emphasis><filename>core-image-gtk-directfb</filename>:</emphasis>
106 An image that uses <filename>gtk+</filename> over <filename>directfb</filename>
107 instead of X11.
108 In order to build, this image requires specific distro configuration that enables
109 <filename>gtk</filename> over <filename>directfb</filename>.</para></listitem>
110 <listitem><para><emphasis><filename>build-appliance-image</filename>:</emphasis>
111 An image you can boot and run using either the
112 <ulink url='http://www.vmware.com/products/player/overview.html'>VMware Player</ulink>
113 or <ulink url='http://www.vmware.com/products/workstation/overview.html'>VMware Workstation</ulink>.
114 For more information on this image, see the
115 <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> page on
116 the Yocto Project website.</para></listitem>
117 </itemizedlist>
118
119 <tip>
120 From the Yocto Project release 1.1 onwards, <filename>-live</filename> and
121 <filename>-directdisk</filename> images have been replaced by a "live"
122 option in <filename>IMAGE_FSTYPES</filename> that will work with any image to produce an
123 image file that can be
124 copied directly to a CD or USB device and run as is.
125 To build a live image, simply add
126 "live" to <filename>IMAGE_FSTYPES</filename> within the <filename>local.conf</filename>
127 file or wherever appropriate and then build the desired image as normal.
128 </tip>
129</chapter>
130<!--
131vim: expandtab tw=80 ts=4
132-->
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 @@
1<?xml version='1.0'?>
2<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">
3
4 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
5
6</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 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title></title><link rel="stylesheet" type="text/css" href="ref-style.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="ref-manual"></a></h1></div><div><div class="authorgroup">
4 <div class="author"><h3 class="author"><span class="firstname">Richard</span> <span class="surname">Purdie</span></h3><div class="affiliation">
5 <span class="orgname">Linux Foundation<br /></span>
6 </div><code class="email">&lt;<a class="email" href="mailto:richard.purdie@linuxfoundation.org">richard.purdie@linuxfoundation.org</a>&gt;</code></div>
7
8 </div></div><div><p class="copyright">Copyright © 2010-2013 Linux Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a id="idm153280"></a>
9 <p>
10 Permission is granted to copy, distribute and/or modify this document under
11 the terms of the <a class="ulink" href="http://creativecommons.org/licenses/by-sa/2.0/uk/" target="_top">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</a> as published by Creative Commons.
12 </p>
13 <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
14 Due to production processes, there could be differences between the Yocto Project
15 documentation bundled in the release tarball and the
16 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/ref-manual/ref-manual.html" target="_top">Yocto Project Reference Manual</a> on
17 the <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project</a> website.
18 For the latest version of this manual, see the manual on the website.
19 </div>
20 </div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><strong>Revision History</strong></th></tr>
21 <tr><td align="left">Revision 4.0+git</td><td align="left">24 November 2010</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 0.9 Release</td></tr>
22 <tr><td align="left">Revision 1.0</td><td align="left">6 April 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0 Release.</td></tr>
23 <tr><td align="left">Revision 1.0.1</td><td align="left">23 May 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.0.1 Release.</td></tr>
24 <tr><td align="left">Revision 1.1</td><td align="left">6 October 2011</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.1 Release.</td></tr>
25 <tr><td align="left">Revision 1.2</td><td align="left">April 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.2 Release.</td></tr>
26 <tr><td align="left">Revision 1.3</td><td align="left">October 2012</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.3 Release.</td></tr>
27 <tr><td align="left">Revision 1.4</td><td align="left">Sometime in 2013</td></tr><tr><td align="left" colspan="2">Released with the Yocto Project 1.4 Release.</td></tr>
28 </table></div></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="chapter"><a href="#intro">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-welcome">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">1.2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">1.3. System Requirements</a></span></dt><dd><dl><dt><span class="section"><a href="#detailed-supported-distros">1.3.1. Supported Linux Distributions</a></span></dt><dt><span class="section"><a href="#required-packages-for-the-host-development-system">1.3.2. Required Packages for the Host Development System</a></span></dt></dl></dd><dt><span class="section"><a href="#intro-getit">1.4. Obtaining the Yocto Project</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">1.5. Development Checkouts</a></span></dt></dl></dd><dt><span class="chapter"><a href="#usingpoky">2. Using the Yocto Project</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-build">2.1. Running a Build</a></span></dt><dd><dl><dt><span class="section"><a href="#build-overview">2.1.1. Build Overview</a></span></dt><dt><span class="section"><a href="#building-an-image-using-gpl-components">2.1.2. Building an Image Using GPL Components</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-install">2.2. Installing and Using the Result</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging">2.3. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">2.3.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">2.3.2. Running Specific Tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">2.3.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">2.3.4. General BitBake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">2.3.5. Building with No Dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">2.3.6. Variables</a></span></dt><dt><span class="section"><a href="#recipe-logging-mechanisms">2.3.7. Recipe Logging Mechanisms</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">2.3.8. Other Tips</a></span></dt></dl></dd><dt><span class="section"><a href="#maintaining-build-output-quality">2.4. Maintaining Build Output Quality</a></span></dt><dd><dl><dt><span class="section"><a href="#enabling-and-disabling-build-history">2.4.1. Enabling and Disabling Build History</a></span></dt><dt><span class="section"><a href="#understanding-what-the-build-history-contains">2.4.2. Understanding What the Build History Contains</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#technical-details">3. Technical Details</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components">3.1. Yocto Project Components</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">3.1.1. BitBake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">3.1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">3.1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">3.1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#shared-state-cache">3.2. Shared State Cache</a></span></dt><dd><dl><dt><span class="section"><a href="#overall-architecture">3.2.1. Overall Architecture</a></span></dt><dt><span class="section"><a href="#checksums">3.2.2. Checksums (Signatures)</a></span></dt><dt><span class="section"><a href="#shared-state">3.2.3. Shared State</a></span></dt><dt><span class="section"><a href="#tips-and-tricks">3.2.4. Tips and Tricks</a></span></dt></dl></dd><dt><span class="section"><a href="#x32">3.3. x32</a></span></dt><dd><dl><dt><span class="section"><a href="#support">3.3.1. Support</a></span></dt><dt><span class="section"><a href="#future-development-and-limitations">3.3.2. Future Development and Limitations</a></span></dt><dt><span class="section"><a href="#using-x32-right-now">3.3.3. Using x32 Right Now</a></span></dt></dl></dd><dt><span class="section"><a href="#licenses">3.4. Licenses</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-configuring-LIC_FILES_CHKSUM">3.4.1. Tracking License Changes</a></span></dt><dt><span class="section"><a href="#enabling-commercially-licensed-recipes">3.4.2. Enabling Commercially Licensed Recipes</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#migration">4. Migrating to a Newer Yocto Project Release</a></span></dt><dd><dl><dt><span class="section"><a href="#moving-to-the-yocto-project-1.3-release">4.1. Moving to the Yocto Project 1.3 Release</a></span></dt><dd><dl><dt><span class="section"><a href="#1.3-local-configuration">4.1.1. Local Configuration</a></span></dt><dt><span class="section"><a href="#1.3-recipes">4.1.2. Recipes</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref-structure">5. Source Directory Structure</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core">5.1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">5.1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">5.1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#handbook">5.1.3. <code class="filename">documentation</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">5.1.4. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-yocto">5.1.5. <code class="filename">meta-yocto/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-yocto-bsp">5.1.6. <code class="filename">meta-yocto-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-hob">5.1.7. <code class="filename">meta-hob/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-skeleton">5.1.8. <code class="filename">meta-skeleton/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">5.1.9. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">5.1.10. <code class="filename">oe-init-build-env</code></a></span></dt><dt><span class="section"><a href="#structure-basic-top-level">5.1.11. <code class="filename">LICENSE, README, and README.hardware</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">5.2. The Build Directory - <code class="filename">build/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-pseudodone">5.2.1. <code class="filename">build/pseudodone</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-local.conf">5.2.2. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-bblayers.conf">5.2.3. <code class="filename">build/conf/bblayers.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-sanity_info">5.2.4. <code class="filename">build/conf/sanity_info</code></a></span></dt><dt><span class="section"><a href="#structure-build-downloads">5.2.5. <code class="filename">build/downloads/</code></a></span></dt><dt><span class="section"><a href="#structure-build-sstate-cache">5.2.6. <code class="filename">build/sstate-cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">5.2.7. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-buildstats">5.2.8. <code class="filename">build/tmp/buildstats/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">5.2.9. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">5.2.10. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">5.2.11. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-rpm">5.2.12. <code class="filename">build/tmp/deploy/rpm/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-licenses">5.2.13. <code class="filename">build/tmp/deploy/licenses/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">5.2.14. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">5.2.15. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-sysroots">5.2.16. <code class="filename">build/tmp/sysroots/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">5.2.17. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-log">5.2.18. <code class="filename">build/tmp/log/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-pkgdata">5.2.19. <code class="filename">build/tmp/pkgdata/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">5.2.20. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">5.3. The Metadata - <code class="filename">meta/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">5.3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">5.3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">5.3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">5.3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-bsp">5.3.5. <code class="filename">meta/recipes-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-connectivity">5.3.6. <code class="filename">meta/recipes-connectivity/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-core">5.3.7. <code class="filename">meta/recipes-core/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-devtools">5.3.8. <code class="filename">meta/recipes-devtools/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-extended">5.3.9. <code class="filename">meta/recipes-extended/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-gnome">5.3.10. <code class="filename">meta/recipes-gnome/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-graphics">5.3.11. <code class="filename">meta/recipes-graphics/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-kernel">5.3.12. <code class="filename">meta/recipes-kernel/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-multimedia">5.3.13. <code class="filename">meta/recipes-multimedia/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-qt">5.3.14. <code class="filename">meta/recipes-qt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-rt">5.3.15. <code class="filename">meta/recipes-rt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-sato">5.3.16. <code class="filename">meta/recipes-sato/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-support">5.3.17. <code class="filename">meta/recipes-support/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">5.3.18. <code class="filename">meta/site/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-txt">5.3.19. <code class="filename">meta/recipes.txt</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ref-bitbake">6. BitBake</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-bitbake-parsing">6.1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">6.2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">6.3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">6.4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">6.5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">6.6. BitBake Command Line</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">6.7. Fetchers</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref-classes">7. Classes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-classes-base">7.1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">7.6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">7.9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">7.10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">7.11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-packagegroup">7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">7.13. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">7.14. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-useradd">7.19. Adding Users - <code class="filename">useradd.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-externalsrc">7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">7.21. Other Classes</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref-images">8. Images</a></span></dt><dt><span class="chapter"><a href="#ref-features">9. Reference: Features</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-features-distro">9.1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">9.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">9.3. Images</a></span></dt><dt><span class="section"><a href="#ref-features-backfill">9.4. Feature Backfilling</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref-variables-glos">10. Variables Glossary</a></span></dt><dd><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ref-varlocality">11. Variable Context</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-configuration">11.1. Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">11.1.1. Distribution (Distro)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">11.1.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">11.1.3. Local</a></span></dt></dl></dd><dt><span class="section"><a href="#ref-varlocality-recipes">11.2. Recipes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-recipe-required">11.2.1. Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">11.2.2. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">11.2.3. Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">11.2.4. Extra Build Information</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#faq">12. FAQ</a></span></dt><dt><span class="chapter"><a href="#resources">13. Contributing to the Yocto Project</a></span></dt><dd><dl><dt><span class="section"><a href="#resources-intro">13.1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">13.2. Tracking Bugs</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">13.3. Mailing lists</a></span></dt><dt><span class="section"><a href="#resources-irc">13.4. Internet Relay Chat (IRC)</a></span></dt><dt><span class="section"><a href="#resources-links">13.5. Links</a></span></dt><dt><span class="section"><a href="#resources-contributions">13.6. Contributions</a></span></dt></dl></dd></dl></div>
29
30
31 <div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a id="intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#intro-welcome">1.1. Introduction</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">1.2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">1.3. System Requirements</a></span></dt><dd><dl><dt><span class="section"><a href="#detailed-supported-distros">1.3.1. Supported Linux Distributions</a></span></dt><dt><span class="section"><a href="#required-packages-for-the-host-development-system">1.3.2. Required Packages for the Host Development System</a></span></dt></dl></dd><dt><span class="section"><a href="#intro-getit">1.4. Obtaining the Yocto Project</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">1.5. Development Checkouts</a></span></dt></dl></div><div class="section" title="1.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-welcome"></a>1.1. Introduction</h2></div></div></div><p>
32 This manual provides reference information for the current release of the Yocto Project.
33 The Yocto Project is an open-source collaboration project focused on embedded Linux
34 developers.
35 Amongst other things, the Yocto Project uses the OpenEmbedded build system, which
36 is based on the Poky project, to construct complete Linux images.
37 You can find complete introductory and getting started information on the Yocto Project
38 by reading the
39 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html" target="_top">Yocto Project Quick Start</a>.
40 For task-based information using the Yocto Project, see the
41 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html" target="_top">Yocto Project Development Manual</a>.
42 You can also find lots of information on the Yocto Project on the
43 <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project website</a>.
44 </p></div><div class="section" title="1.2. Documentation Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-manualoverview"></a>1.2. Documentation Overview</h2></div></div></div><p>
45 This reference manual consists of the following:
46 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>
47 <a class="link" href="#usingpoky" title="Chapter 2. Using the Yocto Project">Using the Yocto Project</a>:</em></span> This chapter
48 provides an overview of the components that make up the Yocto Project
49 followed by information about debugging images created in the Yocto Project.
50 </p></li><li class="listitem"><p><span class="emphasis"><em>
51 <a class="link" href="#technical-details" title="Chapter 3. Technical Details">Technical Details</a>:</em></span>
52 This chapter describes fundamental Yocto Project components as well as an explanation
53 behind how the Yocto Project uses shared state (sstate) cache to speed build time.
54 </p></li><li class="listitem"><p><span class="emphasis"><em>
55 <a class="link" href="#ref-structure" title="Chapter 5. Source Directory Structure">Directory Structure</a>:</em></span>
56 This chapter describes the
57 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">source directory</a> created
58 either by unpacking a released Yocto Project tarball on your host development system,
59 or by cloning the upstream
60 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#poky" target="_top">Poky</a> Git repository.
61 </p></li><li class="listitem"><p><span class="emphasis"><em>
62 <a class="link" href="#ref-bitbake" title="Chapter 6. BitBake">BitBake</a>:</em></span>
63 This chapter provides an overview of the BitBake tool and its role within
64 the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em>
65 <a class="link" href="#ref-classes" title="Chapter 7. Classes">Classes</a>:</em></span>
66 This chapter describes the classes used in the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em>
67 <a class="link" href="#ref-images" title="Chapter 8. Images">Images</a>:</em></span>
68 This chapter describes the standard images that the Yocto Project supports.
69 </p></li><li class="listitem"><p><span class="emphasis"><em>
70 <a class="link" href="#ref-features" title="Chapter 9. Reference: Features">Features</a>:</em></span>
71 This chapter describes mechanisms for creating distribution, machine, and image
72 features during the build process using the OpenEmbedded build system.</p></li><li class="listitem"><p><span class="emphasis"><em>
73 <a class="link" href="#ref-variables-glos" title="Chapter 10. Variables Glossary">Variables Glossary</a>:</em></span>
74 This chapter presents most variables used by the OpenEmbedded build system, which
75 using BitBake.
76 Entries describe the function of the variable and how to apply them.
77 </p></li><li class="listitem"><p><span class="emphasis"><em>
78 <a class="link" href="#ref-varlocality" title="Chapter 11. Variable Context">Variable Context</a>:</em></span>
79 This chapter provides variable locality or context.</p></li><li class="listitem"><p><span class="emphasis"><em>
80 <a class="link" href="#faq" title="Chapter 12. FAQ">FAQ</a>:</em></span>
81 This chapter provides answers for commonly asked questions in the Yocto Project
82 development environment.</p></li><li class="listitem"><p><span class="emphasis"><em>
83 <a class="link" href="#resources" title="Chapter 13. Contributing to the Yocto Project">Contributing to the Yocto Project</a>:</em></span>
84 This chapter provides guidance on how you can contribute back to the Yocto
85 Project.</p></li></ul></div><p>
86 </p></div><div class="section" title="1.3. System Requirements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-requirements"></a>1.3. System Requirements</h2></div></div></div><p>
87 For general Yocto Project system requirements, see the
88 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html#yp-resources" target="_top">What You Need and How You Get It</a>" section
89 in the Yocto Project Quick Start.
90 The remainder of this section provides details on system requirements
91 not covered in the Yocto Project Quick Start.
92 </p><div class="section" title="1.3.1. Supported Linux Distributions"><div class="titlepage"><div><div><h3 class="title"><a id="detailed-supported-distros"></a>1.3.1. Supported Linux Distributions</h3></div></div></div><p>
93 Currently, the Yocto Project is supported on the following distributions:
94 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Ubuntu 10.04.4 LTS</p></li><li class="listitem"><p>Ubuntu 11.10</p></li><li class="listitem"><p>Ubuntu 12.04.1 LTS</p></li><li class="listitem"><p>Ubuntu 12.04.1 LTS</p></li><li class="listitem"><p>Ubuntu 12.10</p></li><li class="listitem"><p>Fedora release 16 (Verne)</p></li><li class="listitem"><p>Fedora release 17 (Beefy Miracle)</p></li><li class="listitem"><p>Fedora release 18 (Spherical Cow)</p></li><li class="listitem"><p>CentOS release 5.6 (Final)</p></li><li class="listitem"><p>CentOS release 5.7 (Final)</p></li><li class="listitem"><p>CentOS release 5.8 (Final)</p></li><li class="listitem"><p>CentOS release 6.3 (Final)</p></li><li class="listitem"><p>Debian GNU/Linux 6.0.6 (squeeze)</p></li><li class="listitem"><p>openSUSE 11.4</p></li><li class="listitem"><p>openSUSE 12.1</p></li><li class="listitem"><p>openSUSE 12.2</p></li></ul></div><p>
95 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
96 For additional information on distributions that support the
97 Yocto Project, see the
98 <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Distribution_Support" target="_top">Distribution Support</a> wiki page.
99 </div></div><div class="section" title="1.3.2. Required Packages for the Host Development System"><div class="titlepage"><div><div><h3 class="title"><a id="required-packages-for-the-host-development-system"></a>1.3.2. Required Packages for the Host Development System</h3></div></div></div><p>
100 The list of packages you need on the host development system can
101 be large when covering all build scenarios using the Yocto Project.
102 This section provides required packages by Linux distribution and
103 further categorized by function.
104 </p><div class="section" title="1.3.2.1. Ubuntu"><div class="titlepage"><div><div><h4 class="title"><a id="ubuntu-packages"></a>1.3.2.1. Ubuntu</h4></div></div></div><p>
105 The following list shows the required packages by function
106 given a supported Ubuntu Linux distribution:
107 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Essentials:</em></span>
108 Packages needed to build an image on a headless
109 system:
110 </p><pre class="literallayout">
111 $ sudo apt-get install gawk wget git-core diffstat unzip texinfo \
112 build-essential chrpath
113 </pre></li><li class="listitem"><p><span class="emphasis"><em>Graphical Extras:</em></span>
114 Packages recommended if the host system has graphics support:
115 </p><pre class="literallayout">
116 $ sudo apt-get install libsdl1.2-dev xterm
117 </pre></li><li class="listitem"><p><span class="emphasis"><em>Documentation:</em></span>
118 Packages needed if you are going to build out the
119 Yocto Project documentation manuals:
120 </p><pre class="literallayout">
121 $ sudo apt-get install make xsltproc docbook-utils fop
122 </pre></li><li class="listitem"><p><span class="emphasis"><em>ADT Installer Extras:</em></span>
123 Packages needed if you are going to be using the
124 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/adt-manual/adt-manual.html#using-the-adt-installer" target="_top">Application Development Toolkit (ADT) Installer</a>:
125 </p><pre class="literallayout">
126 $ sudo apt-get install autoconf automake libtool libglib2.0-dev
127 </pre></li></ul></div><p>
128 </p></div><div class="section" title="1.3.2.2. Fedora Packages"><div class="titlepage"><div><div><h4 class="title"><a id="fedora-packages"></a>1.3.2.2. Fedora Packages</h4></div></div></div><p>
129 The following list shows the required packages by function
130 given a supported Fedora Linux distribution:
131 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Essentials:</em></span>
132 Packages needed to build an image for a headless
133 system:
134 </p><pre class="literallayout">
135 $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \
136 diffutils diffstat git cpp gcc gcc-c++ eglibc-devel texinfo chrpath \
137 ccache
138 </pre></li><li class="listitem"><p><span class="emphasis"><em>Graphical Extras:</em></span>
139 Packages recommended if the host system has graphics support:
140 </p><pre class="literallayout">
141 $ sudo yum install SDL-devel xterm
142 </pre></li><li class="listitem"><p><span class="emphasis"><em>Documentation:</em></span>
143 Packages needed if you are going to build out the
144 Yocto Project documentation manuals:
145 </p><pre class="literallayout">
146 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
147 docbook-dtds docbook-utils fop libxslt
148 </pre></li><li class="listitem"><p><span class="emphasis"><em>ADT Installer Extras:</em></span>
149 Packages needed if you are going to be using the
150 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/adt-manual/adt-manual.html#using-the-adt-installer" target="_top">Application Development Toolkit (ADT) Installer</a>:
151 </p><pre class="literallayout">
152 $ sudo yum install autoconf automake libtool glib2-devel
153 </pre></li></ul></div><p>
154 </p></div><div class="section" title="1.3.2.3. OpenSUSE Packages"><div class="titlepage"><div><div><h4 class="title"><a id="opensuse-packages"></a>1.3.2.3. OpenSUSE Packages</h4></div></div></div><p>
155 The following list shows the required packages by function
156 given a supported OpenSUSE Linux distribution:
157 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Essentials:</em></span>
158 Packages needed to build an image for a headless
159 system:
160 </p><pre class="literallayout">
161 $ sudo zypper install python gcc gcc-c++ git chrpath make wget python-xml \
162 diffstat texinfo python-curses
163 </pre></li><li class="listitem"><p><span class="emphasis"><em>Graphical Extras:</em></span>
164 Packages recommended if the host system has graphics support:
165 </p><pre class="literallayout">
166 $ sudo zypper install libSDL-devel xterm
167 </pre></li><li class="listitem"><p><span class="emphasis"><em>Documentation:</em></span>
168 Packages needed if you are going to build out the
169 Yocto Project documentation manuals:
170 </p><pre class="literallayout">
171 $ sudo zypper install make fop xsltproc
172 </pre></li><li class="listitem"><p><span class="emphasis"><em>ADT Installer Extras:</em></span>
173 Packages needed if you are going to be using the
174 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/adt-manual/adt-manual.html#using-the-adt-installer" target="_top">Application Development Toolkit (ADT) Installer</a>:
175 </p><pre class="literallayout">
176 $ sudo zypper install autoconf automake libtool glib2-devel
177 </pre></li></ul></div><p>
178 </p></div><div class="section" title="1.3.2.4. CentOS Packages"><div class="titlepage"><div><div><h4 class="title"><a id="centos-packages"></a>1.3.2.4. CentOS Packages</h4></div></div></div><p>
179 The following list shows the required packages by function
180 given a supported CentOS Linux distribution:
181 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Essentials:</em></span>
182 Packages needed to build an image for a headless
183 system:
184 </p><pre class="literallayout">
185 $ sudo yum -y install gawk make wget tar bzip2 gzip python unzip perl patch \
186 diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath
187 </pre></li><li class="listitem"><p><span class="emphasis"><em>Graphical Extras:</em></span>
188 Packages recommended if the host system has graphics support:
189 </p><pre class="literallayout">
190 $ sudo yum -y install SDL-devel xterm
191 </pre></li><li class="listitem"><p><span class="emphasis"><em>Documentation:</em></span>
192 Packages needed if you are going to build out the
193 Yocto Project documentation manuals:
194 </p><pre class="literallayout">
195 $ sudo yum -y install make docbook-style-dsssl docbook-style-xsl \
196 docbook-dtds docbook-utils fop libxslt
197 </pre></li><li class="listitem"><p><span class="emphasis"><em>ADT Installer Extras:</em></span>
198 Packages needed if you are going to be using the
199 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/adt-manual/adt-manual.html#using-the-adt-installer" target="_top">Application Development Toolkit (ADT) Installer</a>:
200 </p><pre class="literallayout">
201 $ sudo yum -y install autoconf automake libtool glib2-devel
202 </pre></li></ul></div><p>
203 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Depending on the CentOS version you are using, other requirements
204 and dependencies might exist.
205 For details, you should look at the CentOS sections on the
206 <a class="ulink" href="https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies" target="_top">Poky/GettingStarted/Dependencies</a>
207 wiki page.</div><p>
208 </p></div></div></div><div class="section" title="1.4. Obtaining the Yocto Project"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-getit"></a>1.4. Obtaining the Yocto Project</h2></div></div></div><p>
209 The Yocto Project development team makes the Yocto Project available through a number
210 of methods:
211 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Releases:</em></span> Stable, tested releases are available through
212 <a class="ulink" href="http://downloads.yoctoproject.org/releases/yocto/" target="_top">http://downloads.yoctoproject.org/releases/yocto/</a>.</p></li><li class="listitem"><p><span class="emphasis"><em>Nightly Builds:</em></span> These releases are available at
213 <a class="ulink" href="http://autobuilder.yoctoproject.org/nightly" target="_top">http://autobuilder.yoctoproject.org/nightly</a>.
214 These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and
215 experimental builds.</p></li><li class="listitem"><p><span class="emphasis"><em>Yocto Project Website:</em></span> You can find releases
216 of the Yocto Project and supported BSPs at the
217 <a class="ulink" href="http://www.yoctoproject.org" target="_top">Yocto Project website</a>.
218 Along with these downloads, you can find lots of other information at this site.
219 </p></li></ul></div><p>
220 </p></div><div class="section" title="1.5. Development Checkouts"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="intro-getit-dev"></a>1.5. Development Checkouts</h2></div></div></div><p>
221 Development using the Yocto Project requires a local
222 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
223 You can set up the source directory by downloading a Yocto Project release tarball and unpacking it,
224 or by cloning a copy of the upstream
225 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#poky" target="_top">Poky</a> Git repository.
226 For information on both these methods, see the
227 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#getting-setup" target="_top">Getting Setup</a>"
228 section in the Yocto Project Development Manual.
229 </p></div></div>
230
231 <div class="chapter" title="Chapter 2. Using the Yocto Project"><div class="titlepage"><div><div><h2 class="title"><a id="usingpoky"></a>Chapter 2. Using the Yocto Project</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#usingpoky-build">2.1. Running a Build</a></span></dt><dd><dl><dt><span class="section"><a href="#build-overview">2.1.1. Build Overview</a></span></dt><dt><span class="section"><a href="#building-an-image-using-gpl-components">2.1.2. Building an Image Using GPL Components</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-install">2.2. Installing and Using the Result</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging">2.3. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">2.3.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">2.3.2. Running Specific Tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">2.3.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">2.3.4. General BitBake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">2.3.5. Building with No Dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">2.3.6. Variables</a></span></dt><dt><span class="section"><a href="#recipe-logging-mechanisms">2.3.7. Recipe Logging Mechanisms</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">2.3.8. Other Tips</a></span></dt></dl></dd><dt><span class="section"><a href="#maintaining-build-output-quality">2.4. Maintaining Build Output Quality</a></span></dt><dd><dl><dt><span class="section"><a href="#enabling-and-disabling-build-history">2.4.1. Enabling and Disabling Build History</a></span></dt><dt><span class="section"><a href="#understanding-what-the-build-history-contains">2.4.2. Understanding What the Build History Contains</a></span></dt></dl></dd></dl></div><p>
232 This chapter describes common usage for the Yocto Project.
233 The information is introductory in nature as other manuals in the Yocto Project
234 documentation set provide more details on how to use the Yocto Project.
235 </p><div class="section" title="2.1. Running a Build"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-build"></a>2.1. Running a Build</h2></div></div></div><p>
236 This section provides a summary of the build process and provides information
237 for less obvious aspects of the build process.
238 For general information on how to build an image using the OpenEmbedded build
239 system, see the
240 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html#building-image" target="_top">Building an Image</a>"
241 section of the Yocto Project Quick Start.
242 </p><div class="section" title="2.1.1. Build Overview"><div class="titlepage"><div><div><h3 class="title"><a id="build-overview"></a>2.1.1. Build Overview</h3></div></div></div><p>
243 The first thing you need to do is set up the OpenEmbedded build environment by sourcing
244 the <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">environment setup script</a> as follows:
245 </p><pre class="literallayout">
246 $ source oe-init-build-env [build_dir]
247 </pre><p>
248 </p><p>
249 The <code class="filename">build_dir</code> is optional and specifies the directory the
250 OpenEmbedded build system uses for the build -
251 the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
252 If you do not specify a Build Directory it defaults to <code class="filename">build</code>
253 in your current working directory.
254 A common practice is to use a different Build Directory for different targets.
255 For example, <code class="filename">~/build/x86</code> for a <code class="filename">qemux86</code>
256 target, and <code class="filename">~/build/arm</code> for a <code class="filename">qemuarm</code> target.
257 See <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">oe-init-build-env</a>
258 for more information on this script.
259 </p><p>
260 Once the build environment is set up, you can build a target using:
261 </p><pre class="literallayout">
262 $ bitbake &lt;target&gt;
263 </pre><p>
264 </p><p>
265 The <code class="filename">target</code> is the name of the recipe you want to build.
266 Common targets are the images in <code class="filename">meta/recipes-core/images</code>,
267 <code class="filename">/meta/recipes-sato/images</code>, etc. all found in the
268 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
269 Or, the target can be the name of a recipe for a specific piece of software such as
270 <span class="application">busybox</span>.
271 For more details about the images the OpenEmbedded build system supports, see the
272 "<a class="link" href="#ref-images" title="Chapter 8. Images">Images</a>" chapter.
273 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
274 Building an image without GNU General Public License Version 3 (GPLv3) components
275 is only supported for minimal and base images.
276 See the "<a class="link" href="#ref-images" title="Chapter 8. Images">Images</a>" chapter for more information.
277 </div></div><div class="section" title="2.1.2. Building an Image Using GPL Components"><div class="titlepage"><div><div><h3 class="title"><a id="building-an-image-using-gpl-components"></a>2.1.2. Building an Image Using GPL Components</h3></div></div></div><p>
278 When building an image using GPL components, you need to maintain your original
279 settings and not switch back and forth applying different versions of the GNU
280 General Public License.
281 If you rebuild using different versions of GPL, dependency errors might occur
282 due to some components not being rebuilt.
283 </p></div></div><div class="section" title="2.2. Installing and Using the Result"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-install"></a>2.2. Installing and Using the Result</h2></div></div></div><p>
284 Once an image has been built, it often needs to be installed.
285 The images and kernels built by the OpenEmbedded build system are placed in the
286 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a> in
287 <code class="filename">tmp/deploy/images</code>.
288 For information on how to run pre-built images such as <code class="filename">qemux86</code>
289 and <code class="filename">qemuarm</code>, see the
290 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html#using-pre-built" target="_top">Using Pre-Built Binaries and QEMU</a>"
291 section in the Yocto Project Quick Start.
292 For information about how to install these images, see the documentation for your
293 particular board/machine.
294 </p></div><div class="section" title="2.3. Debugging Build Failures"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-debugging"></a>2.3. Debugging Build Failures</h2></div></div></div><p>
295 The exact method for debugging build failures depends on the nature of the
296 problem and on the system's area from which the bug originates.
297 Standard debugging practices such as comparison against the last
298 known working version with examination of the changes and the re-application of steps
299 to identify the one causing the problem are
300 valid for the Yocto Project just as they are for any other system.
301 Even though it is impossible to detail every possible potential failure,
302 this section provides some general tips to aid in debugging.
303 </p><div class="section" title="2.3.1. Task Failures"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-taskfailures"></a>2.3.1. Task Failures</h3></div></div></div><p>The log file for shell tasks is available in
304 <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>.
305 For example, the <code class="filename">compile</code> task for the QEMU minimal image for the x86
306 machine (<code class="filename">qemux86</code>) might be
307 <code class="filename">tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</code>.
308 To see what BitBake runs to generate that log, look at the corresponding
309 <code class="filename">run.do_taskname.pid</code> file located in the same directory.
310 </p><p>
311 Presently, the output from Python tasks is sent directly to the console.
312 </p></div><div class="section" title="2.3.2. Running Specific Tasks"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-taskrunning"></a>2.3.2. Running Specific Tasks</h3></div></div></div><p>
313 Any given package consists of a set of tasks.
314 The standard BitBake behavior in most cases is: <code class="filename">fetch</code>,
315 <code class="filename">unpack</code>,
316 <code class="filename">patch</code>, <code class="filename">configure</code>,
317 <code class="filename">compile</code>, <code class="filename">install</code>, <code class="filename">package</code>,
318 <code class="filename">package_write</code>, and <code class="filename">build</code>.
319 The default task is <code class="filename">build</code> and any tasks on which it depends
320 build first.
321 Some tasks exist, such as <code class="filename">devshell</code>, that are not part of the
322 default build chain.
323 If you wish to run a task that is not part of the default build chain, you can use the
324 <code class="filename">-c</code> option in BitBake as follows:
325 </p><pre class="literallayout">
326 $ bitbake matchbox-desktop -c devshell
327 </pre><p>
328 </p><p>
329 If you wish to rerun a task, use the <code class="filename">-f</code> force option.
330 For example, the following sequence forces recompilation after changing files in the
331 working directory.
332 </p><pre class="literallayout">
333 $ bitbake matchbox-desktop
334 .
335 .
336 [make some changes to the source code in the working directory]
337 .
338 .
339 $ bitbake matchbox-desktop -c compile -f
340 $ bitbake matchbox-desktop
341 </pre><p>
342 </p><p>
343 This sequence first builds <code class="filename">matchbox-desktop</code> and then recompiles it.
344 The last command reruns all tasks (basically the packaging tasks) after the compile.
345 BitBake recognizes that the <code class="filename">compile</code> task was rerun and therefore
346 understands that the other tasks also need to be run again.
347 </p><p>
348 You can view a list of tasks in a given package by running the
349 <code class="filename">listtasks</code> task as follows:
350 </p><pre class="literallayout">
351 $ bitbake matchbox-desktop -c listtasks
352 </pre><p>
353 The results are in the file <code class="filename">${WORKDIR}/temp/log.do_listtasks</code>.
354 </p></div><div class="section" title="2.3.3. Dependency Graphs"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-dependencies"></a>2.3.3. Dependency Graphs</h3></div></div></div><p>
355 Sometimes it can be hard to see why BitBake wants to build some other packages before a given
356 package you have specified.
357 The <code class="filename">bitbake -g targetname</code> command creates the
358 <code class="filename">depends.dot</code>, <code class="filename">package-depends.dot</code>,
359 and <code class="filename">task-depends.dot</code> files in the current directory.
360 These files show the package and task dependencies and are useful for debugging problems.
361 You can use the <code class="filename">bitbake -g -u depexp targetname</code> command to
362 display the results in a more human-readable form.
363 </p></div><div class="section" title="2.3.4. General BitBake Problems"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-bitbake"></a>2.3.4. General BitBake Problems</h3></div></div></div><p>
364 You can see debug output from BitBake by using the <code class="filename">-D</code> option.
365 The debug output gives more information about what BitBake
366 is doing and the reason behind it.
367 Each <code class="filename">-D</code> option you use increases the logging level.
368 The most common usage is <code class="filename">-DDD</code>.
369 </p><p>
370 The output from <code class="filename">bitbake -DDD -v targetname</code> can reveal why
371 BitBake chose a certain version of a package or why BitBake
372 picked a certain provider.
373 This command could also help you in a situation where you think BitBake did something
374 unexpected.
375 </p></div><div class="section" title="2.3.5. Building with No Dependencies"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-buildfile"></a>2.3.5. Building with No Dependencies</h3></div></div></div><p>
376 If you really want to build a specific <code class="filename">.bb</code> file, you can use
377 the command form <code class="filename">bitbake -b &lt;somepath/somefile.bb&gt;</code>.
378 This command form does not check for dependencies so you should use it
379 only when you know its dependencies already exist.
380 You can also specify fragments of the filename.
381 In this case, BitBake checks for a unique match.
382 </p></div><div class="section" title="2.3.6. Variables"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-variables"></a>2.3.6. Variables</h3></div></div></div><p>
383 The <code class="filename">-e</code> option dumps the resulting environment for
384 either the configuration (no package specified) or for a
385 specific package when specified; or <code class="filename">-b recipename</code>
386 to show the environment from parsing a single recipe file only.
387 </p></div><div class="section" title="2.3.7. Recipe Logging Mechanisms"><div class="titlepage"><div><div><h3 class="title"><a id="recipe-logging-mechanisms"></a>2.3.7. Recipe Logging Mechanisms</h3></div></div></div><p>
388 Best practices exist while writing recipes that both log build progress and
389 act on build conditions such as warnings and errors.
390 Both Python and Bash language bindings exist for the logging mechanism:
391 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Python:</em></span> For Python functions, BitBake
392 supports several loglevels: <code class="filename">bb.fatal</code>,
393 <code class="filename">bb.error</code>, <code class="filename">bb.warn</code>,
394 <code class="filename">bb.note</code>, <code class="filename">bb.plain</code>,
395 and <code class="filename">bb.debug</code>.</p></li><li class="listitem"><p><span class="emphasis"><em>Bash:</em></span> For Bash functions, the same set
396 of loglevels exist and are accessed with a similar syntax:
397 <code class="filename">bbfatal</code>, <code class="filename">bberror</code>,
398 <code class="filename">bbwarn</code>, <code class="filename">bbnote</code>,
399 <code class="filename">bbplain</code>, and <code class="filename">bbdebug</code>.</p></li></ul></div><p>
400 </p><p>
401 For guidance on how logging is handled in both Python and Bash recipes, see the
402 <code class="filename">logging.bbclass</code> file in the
403 <code class="filename">meta/classes</code> folder of the
404 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
405 </p><div class="section" title="2.3.7.1. Logging With Python"><div class="titlepage"><div><div><h4 class="title"><a id="logging-with-python"></a>2.3.7.1. Logging With Python</h4></div></div></div><p>
406 When creating recipes using Python and inserting code that handles build logs
407 keep in mind the goal is to have informative logs while keeping the console as
408 "silent" as possible.
409 Also, if you want status messages in the log use the "debug" loglevel.
410 </p><p>
411 Following is an example written in Python.
412 The code handles logging for a function that determines the number of tasks
413 needed to be run:
414 </p><pre class="literallayout">
415 python do_listtasks() {
416 bb.debug(2, "Starting to figure out the task list")
417 if noteworthy_condition:
418 bb.note("There are 47 tasks to run")
419 bb.debug(2, "Got to point xyz")
420 if warning_trigger:
421 bb.warn("Detected warning_trigger, this might be a problem later.")
422 if recoverable_error:
423 bb.error("Hit recoverable_error, you really need to fix this!")
424 if fatal_error:
425 bb.fatal("fatal_error detected, unable to print the task list")
426 bb.plain("The tasks present are abc")
427 bb.debug(2, "Finished figuring out the tasklist")
428 }
429 </pre><p>
430 </p></div><div class="section" title="2.3.7.2. Logging With Bash"><div class="titlepage"><div><div><h4 class="title"><a id="logging-with-bash"></a>2.3.7.2. Logging With Bash</h4></div></div></div><p>
431 When creating recipes using Bash and inserting code that handles build
432 logs you have the same goals - informative with minimal console output.
433 The syntax you use for recipes written in Bash is similar to that of
434 recipes written in Python described in the previous section.
435 </p><p>
436 Following is an example written in Bash.
437 The code logs the progress of the <code class="filename">do_my_function</code> function.
438 </p><pre class="literallayout">
439 do_my_function() {
440 bbdebug 2 "Running do_my_function"
441 if [ exceptional_condition ]; then
442 bbnote "Hit exceptional_condition"
443 fi
444 bbdebug 2 "Got to point xyz"
445 if [ warning_trigger ]; then
446 bbwarn "Detected warning_trigger, this might cause a problem later."
447 fi
448 if [ recoverable_error ]; then
449 bberror "Hit recoverable_error, correcting"
450 fi
451 if [ fatal_error ]; then
452 bbfatal "fatal_error detected"
453 fi
454 bbdebug 2 "Completed do_my_function"
455 }
456 </pre><p>
457 </p></div></div><div class="section" title="2.3.8. Other Tips"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-debugging-others"></a>2.3.8. Other Tips</h3></div></div></div><p>
458 Here are some other tips that you might find useful:
459 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>When adding new packages, it is worth watching for
460 undesirable items making their way into compiler command lines.
461 For example, you do not want references to local system files like
462 <code class="filename">/usr/lib/</code> or <code class="filename">/usr/include/</code>.
463 </p></li><li class="listitem"><p>If you want to remove the psplash boot splashscreen,
464 add <code class="filename">psplash=false</code> to the kernel command line.
465 Doing so prevents psplash from loading and thus allows you to see the console.
466 It is also possible to switch out of the splashscreen by
467 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
468 </p></li></ul></div><p>
469 </p></div></div><div class="section" title="2.4. Maintaining Build Output Quality"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="maintaining-build-output-quality"></a>2.4. Maintaining Build Output Quality</h2></div></div></div><p>
470 A build's quality can be influenced by many things.
471 For example, if you upgrade a recipe to use a new version of an upstream software
472 package or you experiment with some new configuration options, subtle changes
473 can occur that you might not detect until later.
474 Consider the case where your recipe is using a newer version of an upstream package.
475 In this case, a new version of a piece of software might introduce an optional
476 dependency on another library, which is auto-detected.
477 If that library has already been built when the software is building,
478 then the software will link to the built library and that library will be pulled
479 into your image along with the new software even if you did not want the
480 library.
481 </p><p>
482 The <code class="filename">buildhistory</code> class exists to help you maintain
483 the quality of your build output.
484 You can use the class to highlight unexpected and possibly unwanted
485 changes in the build output.
486 When you enable build history it records information about the contents of
487 each package and image and then commits that information to a local Git
488 repository where you can examine the information.
489 </p><p>
490 The remainder of this section describes the following:
491 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>How you can enable and disable
492 build history</p></li><li class="listitem"><p>How to understand what the build history contains
493 </p></li><li class="listitem"><p>How to limit the information used for build history
494 </p></li><li class="listitem"><p>How to examine the build history from both a
495 command-line and web interface</p></li></ul></div><p>
496 </p><div class="section" title="2.4.1. Enabling and Disabling Build History"><div class="titlepage"><div><div><h3 class="title"><a id="enabling-and-disabling-build-history"></a>2.4.1. Enabling and Disabling Build History</h3></div></div></div><p>
497 Build history is disabled by default.
498 To enable it, add the following statements to the end of your
499 <code class="filename">conf/local.conf</code> file found in the
500 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>:
501 </p><pre class="literallayout">
502 INHERIT += "buildhistory"
503 BUILDHISTORY_COMMIT = "1"
504 </pre><p>
505 Enabling build history as previously described
506 causes the build process to collect build
507 output information and commit it to a local
508 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#git" target="_top">Git</a> repository.
509 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
510 Enabling build history increases your build times slightly,
511 particularly for images, and increases the amount of disk
512 space used during the build.
513 </div><p>
514 </p><p>
515 You can disable build history by removing the previous statements
516 from your <code class="filename">conf/local.conf</code> file.
517 However, you should realize that enabling and disabling
518 build history in this manner can change the
519 <code class="filename">do_package</code> task checksums, which if you
520 are using the OEBasicHash signature generator (the default
521 for many current distro configurations including
522 <code class="filename">DISTRO = "poky"</code> and
523 <code class="filename">DISTRO = ""</code>) will result in the packaging
524 tasks being re-run during the subsequent build.
525 </p><p>
526 To disable the build history functionality without causing the
527 packaging tasks to be re-run, add just this statement to your
528 <code class="filename">conf/local.conf</code> file:
529 </p><pre class="literallayout">
530 BUILDHISTORY_FEATURES = ""
531 </pre><p>
532 </p></div><div class="section" title="2.4.2. Understanding What the Build History Contains"><div class="titlepage"><div><div><h3 class="title"><a id="understanding-what-the-build-history-contains"></a>2.4.2. Understanding What the Build History Contains</h3></div></div></div><p>
533 Build history information is kept in
534 <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">$TMPDIR</code></a><code class="filename">/buildhistory</code>
535 in the Build Directory.
536 The following is an example abbreviated listing:
537 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="540"><tr style="height: 360px"><td align="center"><img src="figures/buildhistory.png" align="middle" width="540" /></td></tr></table><p>
538 </p><div class="section" title="2.4.2.1. Build History Package Information"><div class="titlepage"><div><div><h4 class="title"><a id="build-history-package-information"></a>2.4.2.1. Build History Package Information</h4></div></div></div><p>
539 The history for each package contains a text file that has
540 name-value pairs with information about the package.
541 For example, <code class="filename">buildhistory/packages/core2-poky-linux/busybox/busybox/latest</code>
542 contains the following:
543 </p><pre class="literallayout">
544 PV = 1.19.3
545 PR = r3
546 RDEPENDS = update-rc.d eglibc (&gt;= 2.13)
547 RRECOMMENDS = busybox-syslog busybox-udhcpc
548 PKGSIZE = 564701
549 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
550 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
551 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
552 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
553 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
554 </pre><p>
555 Most of these name-value pairs corresponds to variables used
556 to produce the package.
557 The exceptions are <code class="filename">FILELIST</code>, which is the
558 actual list of files in the package, and
559 <code class="filename">PKGSIZE</code>, which is the total size of files
560 in the package in bytes.
561 </p><p>
562 There is also a file corresponding to the recipe from which the
563 package came (e.g.
564 <code class="filename">buildhistory/packages/core2-poky-linux/busybox/latest</code>):
565 </p><pre class="literallayout">
566 PV = 1.19.3
567 PR = r3
568 DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \
569 virtual/libc update-rc.d-native
570 PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \
571 busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \
572 busybox-staticdev busybox-locale
573 </pre><p>
574 </p></div><div class="section" title="2.4.2.2. Build History Image Information"><div class="titlepage"><div><div><h4 class="title"><a id="build-history-image-information"></a>2.4.2.2. Build History Image Information</h4></div></div></div><p>
575 The files produced for each image are as follows:
576 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>build-id:</em></span>
577 Human-readable information about the build configuration
578 and metadata source revisions.</p></li><li class="listitem"><p><span class="emphasis"><em>*.dot:</em></span>
579 Dependency graphs for the image that are
580 compatible with <code class="filename">graphviz</code>.
581 </p></li><li class="listitem"><p><span class="emphasis"><em>files-in-image.txt:</em></span>
582 A list of files in the image with permissions,
583 owner, group, size, and symlink information.
584 </p></li><li class="listitem"><p><span class="emphasis"><em>image-info.txt:</em></span>
585 A text file containing name-value pairs with information
586 about the image.
587 See the following listing example for more information.
588 </p></li><li class="listitem"><p><span class="emphasis"><em>installed-package-names.txt:</em></span>
589 A list of installed packages by name only.</p></li><li class="listitem"><p><span class="emphasis"><em>installed-package-sizes.txt:</em></span>
590 A list of installed packages ordered by size.
591 </p></li><li class="listitem"><p><span class="emphasis"><em>installed-packages.txt:</em></span>
592 A list of installed packages with fuill package
593 filenames.</p></li></ul></div><p>
594 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
595 Installed package information is able to be gathered and
596 produced even if package management is disabled for the final
597 image.
598 </div><p>
599 </p><p>
600 Here is an example of <code class="filename">image-info.txt</code>:
601 </p><pre class="literallayout">
602 DISTRO = poky
603 DISTRO_VERSION = 1.1+snapshot-20120207
604 USER_CLASSES = image-mklibs image-prelink
605 IMAGE_CLASSES = image_types
606 IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \
607 package-management ssh-server-dropbear package-management
608 IMAGE_LINGUAS = en-us en-gb
609 IMAGE_INSTALL = task-core-boot task-base-extended
610 BAD_RECOMMENDATIONS =
611 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ;
612 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
613 IMAGESIZE = 171816
614 </pre><p>
615 Other than <code class="filename">IMAGESIZE</code>, which is the
616 total size of the files in the image in Kbytes, the
617 name-value pairs are variables that may have influenced the
618 content of the image.
619 This information is often useful when you are trying to determine
620 why a change in the package or file listings has occurred.
621 </p></div><div class="section" title="2.4.2.3. Using Build History to Gather Image Information Only"><div class="titlepage"><div><div><h4 class="title"><a id="using-build-history-to-gather-image-information-only"></a>2.4.2.3. Using Build History to Gather Image Information Only</h4></div></div></div><p>
622 As you can see, build history produces image information,
623 including dependency graphs, so you can see why something
624 was pulled into the image.
625 If you are just interested in this information and not
626 interested in collecting history or any package information,
627 you can enable writing only image information without
628 any history by adding the following
629 to your <code class="filename">conf/local.conf</code> file found in the
630 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>:
631 </p><pre class="literallayout">
632 INHERIT += "buildhistory"
633 BUILDHISTORY_COMMIT = "0"
634 BUILDHISTORY_FEATURES = "image"
635 </pre><p>
636 </p></div><div class="section" title="2.4.2.4. Examining Build History Information"><div class="titlepage"><div><div><h4 class="title"><a id="examining-build-history-information"></a>2.4.2.4. Examining Build History Information</h4></div></div></div><p>
637 You can examine build history output from the command line or
638 from a web interface.
639 </p><p>
640 To see any changes that have occurred (assuming you have
641 <code class="filename">BUILDHISTORY_COMMIT = "1"</code>), you can simply
642 use any Git command that allows you to view the history of
643 a repository.
644 Here is one method:
645 </p><pre class="literallayout">
646 $ git log -p
647 </pre><p>
648 You need to realize, however, that this method does show
649 changes that are not significant (e.g. a package's size
650 changing by a few bytes).
651 </p><p>
652 A command-line tool called <code class="filename">buildhistory-diff</code>
653 does exist though that queries the Git repository and prints just
654 the differences that might be significant in human-readable form.
655 Here is an example:
656 </p><pre class="literallayout">
657 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
658 Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt):
659 /etc/anotherpkg.conf was added
660 /sbin/anotherpkg was added
661 * (installed-package-names.txt):
662 * anotherpkg was added
663 Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt):
664 anotherpkg was added
665 packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
666 * PR changed from "r0" to "r1"
667 * PV changed from "0.1.10" to "0.1.12"
668 packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
669 * PR changed from "r0" to "r1"
670 * PV changed from "0.1.10" to "0.1.12"
671 </pre><p>
672 </p><p>
673 To see changes to the build history using a web interface, follow
674 the instruction in the <code class="filename">README</code> file here.
675 <a class="ulink" href="http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/" target="_top">http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/</a>.
676 </p><p>
677 Here is a sample screenshot of the interface:
678 </p><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="130%"><tr><td align="center"><img src="figures/buildhistory-web.png" align="middle" height="468" /></td></tr></table><p>
679 </p></div></div></div></div>
680
681 <div class="chapter" title="Chapter 3. Technical Details"><div class="titlepage"><div><div><h2 class="title"><a id="technical-details"></a>Chapter 3. Technical Details</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#usingpoky-components">3.1. Yocto Project Components</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">3.1.1. BitBake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">3.1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">3.1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">3.1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#shared-state-cache">3.2. Shared State Cache</a></span></dt><dd><dl><dt><span class="section"><a href="#overall-architecture">3.2.1. Overall Architecture</a></span></dt><dt><span class="section"><a href="#checksums">3.2.2. Checksums (Signatures)</a></span></dt><dt><span class="section"><a href="#shared-state">3.2.3. Shared State</a></span></dt><dt><span class="section"><a href="#tips-and-tricks">3.2.4. Tips and Tricks</a></span></dt></dl></dd><dt><span class="section"><a href="#x32">3.3. x32</a></span></dt><dd><dl><dt><span class="section"><a href="#support">3.3.1. Support</a></span></dt><dt><span class="section"><a href="#future-development-and-limitations">3.3.2. Future Development and Limitations</a></span></dt><dt><span class="section"><a href="#using-x32-right-now">3.3.3. Using x32 Right Now</a></span></dt></dl></dd><dt><span class="section"><a href="#licenses">3.4. Licenses</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-configuring-LIC_FILES_CHKSUM">3.4.1. Tracking License Changes</a></span></dt><dt><span class="section"><a href="#enabling-commercially-licensed-recipes">3.4.2. Enabling Commercially Licensed Recipes</a></span></dt></dl></dd></dl></div><p>
682 This chapter provides technical details for various parts of the Yocto Project.
683 Currently, topics include Yocto Project components and shared state (sstate) cache.
684 </p><div class="section" title="3.1. Yocto Project Components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="usingpoky-components"></a>3.1. Yocto Project Components</h2></div></div></div><p>
685 The BitBake task executor together with various types of configuration files form the
686 OpenEmbedded Core.
687 This section overviews the BitBake task executor and the
688 configuration files by describing what they are used for and how they interact.
689 </p><p>
690 BitBake handles the parsing and execution of the data files.
691 The data itself is of various types:
692 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Recipes:</em></span> Provides details about particular
693 pieces of software</p></li><li class="listitem"><p><span class="emphasis"><em>Class Data:</em></span> An abstraction of common build
694 information (e.g. how to build a Linux kernel).</p></li><li class="listitem"><p><span class="emphasis"><em>Configuration Data:</em></span> Defines machine-specific settings,
695 policy decisions, etc.
696 Configuration data acts as the glue to bind everything together.</p></li></ul></div><p>
697 For more information on data, see the
698 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#yocto-project-terms" target="_top">Yocto Project Terms</a>"
699 section in the Yocto Project Development Manual.
700 </p><p>
701 BitBake knows how to combine multiple data sources together and refers to each data source
702 as a layer.
703 For information on layers, see the
704 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#understanding-and-creating-layers" target="_top">Understanding and
705 Creating Layers</a>" section of the Yocto Project Development Manual.
706 </p><p>
707 Following are some brief details on these core components.
708 For more detailed information on these components see the
709 "<a class="link" href="#ref-structure" title="Chapter 5. Source Directory Structure">Directory Structure</a>" chapter.
710 </p><div class="section" title="3.1.1. BitBake"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-bitbake"></a>3.1.1. BitBake</h3></div></div></div><p>
711 BitBake is the tool at the heart of the OpenEmbedded build system and is responsible
712 for parsing the metadata, generating a list of tasks from it,
713 and then executing those tasks.
714 To see a list of the options BitBake supports, use the following help command:
715 </p><pre class="literallayout">
716 $ bitbake --help
717 </pre><p>
718 </p><p>
719 The most common usage for BitBake is <code class="filename">bitbake &lt;packagename&gt;</code>, where
720 <code class="filename">packagename</code> is the name of the package you want to build
721 (referred to as the "target" in this manual).
722 The target often equates to the first part of a <code class="filename">.bb</code> filename.
723 So, to run the <code class="filename">matchbox-desktop_1.2.3.bb</code> file, you
724 might type the following:
725 </p><pre class="literallayout">
726 $ bitbake matchbox-desktop
727 </pre><p>
728 Several different versions of <code class="filename">matchbox-desktop</code> might exist.
729 BitBake chooses the one selected by the distribution configuration.
730 You can get more details about how BitBake chooses between different
731 target versions and providers in the
732 "<a class="link" href="#ref-bitbake-providers" title="6.2. Preferences and Providers">Preferences and Providers</a>" section.
733 </p><p>
734 BitBake also tries to execute any dependent tasks first.
735 So for example, before building <code class="filename">matchbox-desktop</code>, BitBake
736 would build a cross compiler and <code class="filename">eglibc</code> if they had not already
737 been built.
738 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>This release of the Yocto Project does not support the <code class="filename">glibc</code>
739 GNU version of the Unix standard C library. By default, the OpenEmbedded build system
740 builds with <code class="filename">eglibc</code>.</div><p>
741 </p><p>
742 A useful BitBake option to consider is the <code class="filename">-k</code> or
743 <code class="filename">--continue</code> option.
744 This option instructs BitBake to try and continue processing the job as much
745 as possible even after encountering an error.
746 When an error occurs, the target that
747 failed and those that depend on it cannot be remade.
748 However, when you use this option other dependencies can still be processed.
749 </p></div><div class="section" title="3.1.2. Metadata (Recipes)"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-metadata"></a>3.1.2. Metadata (Recipes)</h3></div></div></div><p>
750 The <code class="filename">.bb</code> files are usually referred to as "recipes."
751 In general, a recipe contains information about a single piece of software.
752 The information includes the location from which to download the source patches
753 (if any are needed), which special configuration options to apply,
754 how to compile the source files, and how to package the compiled output.
755 </p><p>
756 The term "package" can also be used to describe recipes.
757 However, since the same word is used for the packaged output from the OpenEmbedded
758 build system (i.e. <code class="filename">.ipk</code> or <code class="filename">.deb</code> files),
759 this document avoids using the term "package" when referring to recipes.
760 </p></div><div class="section" title="3.1.3. Classes"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-classes"></a>3.1.3. Classes</h3></div></div></div><p>
761 Class files (<code class="filename">.bbclass</code>) contain information that is useful to share
762 between metadata files.
763 An example is the Autotools class, which contains
764 common settings for any application that Autotools uses.
765 The "<a class="link" href="#ref-classes" title="Chapter 7. Classes">Classes</a>" chapter provides details
766 about common classes and how to use them.
767 </p></div><div class="section" title="3.1.4. Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-components-configuration"></a>3.1.4. Configuration</h3></div></div></div><p>
768 The configuration files (<code class="filename">.conf</code>) define various configuration variables
769 that govern the OpenEmbedded build process.
770 These files fall into several areas that define machine configuration options,
771 distribution configuration options, compiler tuning options, general common configuration
772 options and user configuration options (<code class="filename">local.conf</code>, which is found
773 in the <a class="ulink" href="build-directory" target="_top">Build Directory</a>).
774 </p></div></div><div class="section" title="3.2. Shared State Cache"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="shared-state-cache"></a>3.2. Shared State Cache</h2></div></div></div><p>
775 By design, the OpenEmbedded build system builds everything from scratch unless
776 BitBake can determine that parts don't need to be rebuilt.
777 Fundamentally, building from scratch is attractive as it means all parts are
778 built fresh and there is no possibility of stale data causing problems.
779 When developers hit problems, they typically default back to building from scratch
780 so they know the state of things from the start.
781 </p><p>
782 Building an image from scratch is both an advantage and a disadvantage to the process.
783 As mentioned in the previous paragraph, building from scratch ensures that
784 everything is current and starts from a known state.
785 However, building from scratch also takes much longer as it generally means
786 rebuilding things that don't necessarily need rebuilt.
787 </p><p>
788 The Yocto Project implements shared state code that supports incremental builds.
789 The implementation of the shared state code answers the following questions that
790 were fundamental roadblocks within the OpenEmbedded incremental build support system:
791 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">What pieces of the system have changed and what pieces have not changed?</li><li class="listitem">How are changed pieces of software removed and replaced?</li><li class="listitem">How are pre-built components that don't need to be rebuilt from scratch
792 used when they are available?</li></ul></div><p>
793 </p><p>
794 For the first question, the build system detects changes in the "inputs" to a given task by
795 creating a checksum (or signature) of the task's inputs.
796 If the checksum changes, the system assumes the inputs have changed and the task needs to be
797 rerun.
798 For the second question, the shared state (sstate) code tracks which tasks add which output
799 to the build process.
800 This means the output from a given task can be removed, upgraded or otherwise manipulated.
801 The third question is partly addressed by the solution for the second question
802 assuming the build system can fetch the sstate objects from remote locations and
803 install them if they are deemed to be valid.
804 </p><p>
805 The rest of this section goes into detail about the overall incremental build
806 architecture, the checksums (signatures), shared state, and some tips and tricks.
807 </p><div class="section" title="3.2.1. Overall Architecture"><div class="titlepage"><div><div><h3 class="title"><a id="overall-architecture"></a>3.2.1. Overall Architecture</h3></div></div></div><p>
808 When determining what parts of the system need to be built, BitBake
809 uses a per-task basis and does not use a per-recipe basis.
810 You might wonder why using a per-task basis is preferred over a per-recipe basis.
811 To help explain, consider having the IPK packaging backend enabled and then switching to DEB.
812 In this case, <code class="filename">do_install</code> and <code class="filename">do_package</code>
813 output are still valid.
814 However, with a per-recipe approach, the build would not include the
815 <code class="filename">.deb</code> files.
816 Consequently, you would have to invalidate the whole build and rerun it.
817 Rerunning everything is not the best situation.
818 Also in this case, the core must be "taught" much about specific tasks.
819 This methodology does not scale well and does not allow users to easily add new tasks
820 in layers or as external recipes without touching the packaged-staging core.
821 </p></div><div class="section" title="3.2.2. Checksums (Signatures)"><div class="titlepage"><div><div><h3 class="title"><a id="checksums"></a>3.2.2. Checksums (Signatures)</h3></div></div></div><p>
822 The shared state code uses a checksum, which is a unique signature of a task's
823 inputs, to determine if a task needs to be run again.
824 Because it is a change in a task's inputs that triggers a rerun, the process
825 needs to detect all the inputs to a given task.
826 For shell tasks, this turns out to be fairly easy because
827 the build process generates a "run" shell script for each task and
828 it is possible to create a checksum that gives you a good idea of when
829 the task's data changes.
830 </p><p>
831 To complicate the problem, there are things that should not be included in
832 the checksum.
833 First, there is the actual specific build path of a given task -
834 the <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>.
835 It does not matter if the working directory changes because it should not
836 affect the output for target packages.
837 Also, the build process has the objective of making native/cross packages relocatable.
838 The checksum therefore needs to exclude <code class="filename">WORKDIR</code>.
839 The simplistic approach for excluding the working directory is to set
840 <code class="filename">WORKDIR</code> to some fixed value and create the checksum
841 for the "run" script.
842 </p><p>
843 Another problem results from the "run" scripts containing functions that
844 might or might not get called.
845 The incremental build solution contains code that figures out dependencies
846 between shell functions.
847 This code is used to prune the "run" scripts down to the minimum set,
848 thereby alleviating this problem and making the "run" scripts much more
849 readable as a bonus.
850 </p><p>
851 So far we have solutions for shell scripts.
852 What about python tasks?
853 The same approach applies even though these tasks are more difficult.
854 The process needs to figure out what variables a python function accesses
855 and what functions it calls.
856 Again, the incremental build solution contains code that first figures out
857 the variable and function dependencies, and then creates a checksum for the data
858 used as the input to the task.
859 </p><p>
860 Like the <code class="filename">WORKDIR</code> case, situations exist where dependencies
861 should be ignored.
862 For these cases, you can instruct the build process to ignore a dependency
863 by using a line like the following:
864 </p><pre class="literallayout">
865 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
866 </pre><p>
867 This example ensures that the <code class="filename">PACKAGE_ARCHS</code> variable does not
868 depend on the value of <code class="filename">MACHINE</code>, even if it does reference it.
869 </p><p>
870 Equally, there are cases where we need to add dependencies BitBake is not able to find.
871 You can accomplish this by using a line like the following:
872 </p><pre class="literallayout">
873 PACKAGE_ARCHS[vardeps] = "MACHINE"
874 </pre><p>
875 This example explicitly adds the <code class="filename">MACHINE</code> variable as a
876 dependency for <code class="filename">PACKAGE_ARCHS</code>.
877 </p><p>
878 Consider a case with inline python, for example, where BitBake is not
879 able to figure out dependencies.
880 When running in debug mode (i.e. using <code class="filename">-DDD</code>), BitBake
881 produces output when it discovers something for which it cannot figure out
882 dependencies.
883 The Yocto Project team has currently not managed to cover those dependencies
884 in detail and is aware of the need to fix this situation.
885 </p><p>
886 Thus far, this section has limited discussion to the direct inputs into a task.
887 Information based on direct inputs is referred to as the "basehash" in the
888 code.
889 However, there is still the question of a task's indirect inputs - the
890 things that were already built and present in the Build Directory.
891 The checksum (or signature) for a particular task needs to add the hashes
892 of all the tasks on which the particular task depends.
893 Choosing which dependencies to add is a policy decision.
894 However, the effect is to generate a master checksum that combines the basehash
895 and the hashes of the task's dependencies.
896 </p><p>
897 At the code level, there are a variety of ways both the basehash and the
898 dependent task hashes can be influenced.
899 Within the BitBake configuration file, we can give BitBake some extra information
900 to help it construct the basehash.
901 The following statements effectively result in a list of global variable
902 dependency excludes - variables never included in any checksum:
903 </p><pre class="literallayout">
904 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH"
905 BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS"
906 BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER"
907 BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET"
908 </pre><p>
909 The previous example actually excludes
910 <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>
911 since it is actually constructed as a path within
912 <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>, which is on
913 the whitelist.
914 </p><p>
915 The rules for deciding which hashes of dependent tasks to include through
916 dependency chains are more complex and are generally accomplished with a
917 python function.
918 The code in <code class="filename">meta/lib/oe/sstatesig.py</code> shows two examples
919 of this and also illustrates how you can insert your own policy into the system
920 if so desired.
921 This file defines the two basic signature generators <code class="filename">OE-Core</code>
922 uses: "OEBasic" and "OEBasicHash".
923 By default, there is a dummy "noop" signature handler enabled in BitBake.
924 This means that behavior is unchanged from previous versions.
925 <code class="filename">OE-Core</code> uses the "OEBasic" signature handler by default
926 through this setting in the <code class="filename">bitbake.conf</code> file:
927 </p><pre class="literallayout">
928 BB_SIGNATURE_HANDLER ?= "OEBasic"
929 </pre><p>
930 The "OEBasicHash" <code class="filename">BB_SIGNATURE_HANDLER</code> is the same as the
931 "OEBasic" version but adds the task hash to the stamp files.
932 This results in any metadata change that changes the task hash, automatically
933 causing the task to be run again.
934 This removes the need to bump <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a>
935 values and changes to metadata automatically ripple across the build.
936 Currently, this behavior is not the default behavior for <code class="filename">OE-Core</code>
937 but is the default in <code class="filename">poky</code>.
938 </p><p>
939 It is also worth noting that the end result of these signature generators is to
940 make some dependency and hash information available to the build.
941 This information includes:
942 </p><pre class="literallayout">
943 BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe
944 BB_BASEHASH_&lt;filename:taskname&gt; - the base hashes for each dependent task
945 BBHASHDEPS_&lt;filename:taskname&gt; - The task dependencies for each task
946 BB_TASKHASH - the hash of the currently running task
947 </pre><p>
948 </p></div><div class="section" title="3.2.3. Shared State"><div class="titlepage"><div><div><h3 class="title"><a id="shared-state"></a>3.2.3. Shared State</h3></div></div></div><p>
949 Checksums and dependencies, as discussed in the previous section, solve half the
950 problem.
951 The other part of the problem is being able to use checksum information during the build
952 and being able to reuse or rebuild specific components.
953 </p><p>
954 The shared state class (<code class="filename">sstate.bbclass</code>)
955 is a relatively generic implementation of how to "capture" a snapshot of a given task.
956 The idea is that the build process does not care about the source of a task's output.
957 Output could be freshly built or it could be downloaded and unpacked from
958 somewhere - the build process doesn't need to worry about its source.
959 </p><p>
960 There are two types of output, one is just about creating a directory
961 in <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>.
962 A good example is the output of either <code class="filename">do_install</code> or
963 <code class="filename">do_package</code>.
964 The other type of output occurs when a set of data is merged into a shared directory
965 tree such as the sysroot.
966 </p><p>
967 The Yocto Project team has tried to keep the details of the implementation hidden in
968 <code class="filename">sstate.bbclass</code>.
969 From a user's perspective, adding shared state wrapping to a task
970 is as simple as this <code class="filename">do_deploy</code> example taken from
971 <code class="filename">do_deploy.bbclass</code>:
972 </p><pre class="literallayout">
973 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
974 SSTATETASKS += "do_deploy"
975 do_deploy[sstate-name] = "deploy"
976 do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
977 do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
978
979 python do_deploy_setscene () {
980 sstate_setscene(d)
981 }
982 addtask do_deploy_setscene
983 </pre><p>
984 In the example, we add some extra flags to the task, a name field ("deploy"), an
985 input directory where the task sends data, and the output
986 directory where the data from the task should eventually be copied.
987 We also add a <code class="filename">_setscene</code> variant of the task and add the task
988 name to the <code class="filename">SSTATETASKS</code> list.
989 </p><p>
990 If you have a directory whose contents you need to preserve, you can do this with
991 a line like the following:
992 </p><pre class="literallayout">
993 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
994 </pre><p>
995 This method, as well as the following example, also works for multiple directories.
996 </p><pre class="literallayout">
997 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
998 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
999 do_package[sstate-lockfile] = "${PACKAGELOCK}"
1000 </pre><p>
1001 These methods also include the ability to take a lockfile when manipulating
1002 shared state directory structures since some cases are sensitive to file
1003 additions or removals.
1004 </p><p>
1005 Behind the scenes, the shared state code works by looking in
1006 <a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a> and
1007 <a class="link" href="#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a>
1008 for shared state files.
1009 Here is an example:
1010 </p><pre class="literallayout">
1011 SSTATE_MIRRORS ?= "\
1012 file://.* http://someserver.tld/share/sstate/PATH \n \
1013 file://.* file:///some/local/dir/sstate/PATH"
1014 </pre><p>
1015 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1016 The shared state directory (<code class="filename">SSTATE_DIR</code>) is
1017 organized into two-character subdirectories, where the subdirectory
1018 names are based on the first two characters of the hash.
1019 If the shared state directory structure for a mirror has the
1020 same structure as <code class="filename">SSTATE_DIR</code>, you must
1021 specify "PATH" as part of the URI to enable the build system
1022 to map to the appropriate subdirectory.
1023 </div><p>
1024 </p><p>
1025 The shared state package validity can be detected just by looking at the
1026 filename since the filename contains the task checksum (or signature) as
1027 described earlier in this section.
1028 If a valid shared state package is found, the build process downloads it
1029 and uses it to accelerate the task.
1030 </p><p>
1031 The build processes uses the <code class="filename">*_setscene</code> tasks
1032 for the task acceleration phase.
1033 BitBake goes through this phase before the main execution code and tries
1034 to accelerate any tasks for which it can find shared state packages.
1035 If a shared state package for a task is available, the shared state
1036 package is used.
1037 This means the task and any tasks on which it is dependent are not
1038 executed.
1039 </p><p>
1040 As a real world example, the aim is when building an IPK-based image,
1041 only the <code class="filename">do_package_write_ipk</code> tasks would have their
1042 shared state packages fetched and extracted.
1043 Since the sysroot is not used, it would never get extracted.
1044 This is another reason why a task-based approach is preferred over a
1045 recipe-based approach, which would have to install the output from every task.
1046 </p></div><div class="section" title="3.2.4. Tips and Tricks"><div class="titlepage"><div><div><h3 class="title"><a id="tips-and-tricks"></a>3.2.4. Tips and Tricks</h3></div></div></div><p>
1047 The code in the build system that supports incremental builds is not
1048 simple code.
1049 This section presents some tips and tricks that help you work around
1050 issues related to shared state code.
1051 </p><div class="section" title="3.2.4.1. Debugging"><div class="titlepage"><div><div><h4 class="title"><a id="debugging"></a>3.2.4.1. Debugging</h4></div></div></div><p>
1052 When things go wrong, debugging needs to be straightforward.
1053 Because of this, the Yocto Project team included strong debugging
1054 tools:
1055 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Whenever a shared state package is written out, so is a
1056 corresponding <code class="filename">.siginfo</code> file.
1057 This practice results in a pickled python database of all
1058 the metadata that went into creating the hash for a given shared state
1059 package.</p></li><li class="listitem"><p>If BitBake is run with the <code class="filename">--dump-signatures</code>
1060 (or <code class="filename">-S</code>) option, BitBake dumps out
1061 <code class="filename">.siginfo</code> files in
1062 the stamp directory for every task it would have executed instead of
1063 building the specified target package.</p></li><li class="listitem"><p>There is a <code class="filename">bitbake-diffsigs</code> command that
1064 can process these <code class="filename">.siginfo</code> files.
1065 If one file is specified, it will dump out the dependency
1066 information in the file.
1067 If two files are specified, it will compare the two files and dump out
1068 the differences between the two.
1069 This allows the question of "What changed between X and Y?" to be
1070 answered easily.</p></li></ul></div><p>
1071 </p></div><div class="section" title="3.2.4.2. Invalidating Shared State"><div class="titlepage"><div><div><h4 class="title"><a id="invalidating-shared-state"></a>3.2.4.2. Invalidating Shared State</h4></div></div></div><p>
1072 The shared state code uses checksums and shared state
1073 cache to avoid unnecessarily rebuilding tasks.
1074 As with all schemes, this one has some drawbacks.
1075 It is possible that you could make implicit changes that are not factored
1076 into the checksum calculation, but do affect a task's output.
1077 A good example is perhaps when a tool changes its output.
1078 Let's say that the output of <code class="filename">rpmdeps</code> needed to change.
1079 The result of the change should be that all the "package", "package_write_rpm",
1080 and "package_deploy-rpm" shared state cache items would become invalid.
1081 But, because this is a change that is external to the code and therefore implicit,
1082 the associated shared state cache items do not become invalidated.
1083 In this case, the build process would use the cached items rather than running the
1084 task again.
1085 Obviously, these types of implicit changes can cause problems.
1086 </p><p>
1087 To avoid these problems during the build, you need to understand the effects of any
1088 change you make.
1089 Note that any changes you make directly to a function automatically are factored into
1090 the checksum calculation and thus, will invalidate the associated area of sstate cache.
1091 You need to be aware of any implicit changes that are not obvious changes to the
1092 code and could affect the output of a given task.
1093 Once you are aware of such a change, you can take steps to invalidate the cache
1094 and force the task to run.
1095 The step to take is as simple as changing a function's comments in the source code.
1096 For example, to invalidate package shared state files, change the comment statements
1097 of <code class="filename">do_package</code> or the comments of one of the functions it calls.
1098 The change is purely cosmetic, but it causes the checksum to be recalculated and
1099 forces the task to be run again.
1100 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1101 For an example of a commit that makes a cosmetic change to invalidate
1102 a shared state, see this
1103 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54" target="_top">commit</a>.
1104 </div></div></div></div><div class="section" title="3.3. x32"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="x32"></a>3.3. x32</h2></div></div></div><p>
1105 x32 is a new processor-specific Application Binary Interface (psABI) for x86_64.
1106 An ABI defines the calling conventions between functions in a processing environment.
1107 The interface determines what registers are used and what the sizes are for various C data types.
1108 </p><p>
1109 Some processing environments prefer using 32-bit applications even when running
1110 on Intel 64-bit platforms.
1111 Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
1112 The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
1113 leaving the system underutilized.
1114 Now consider the x86_64 psABI.
1115 This ABI is newer and uses 64-bits for data sizes and program pointers.
1116 The extra bits increase the footprint size of the programs, libraries,
1117 and also increases the memory and file system size requirements.
1118 Executing under the x32 psABI enables user programs to utilize CPU and system resources
1119 more efficiently while keeping the memory footprint of the applications low.
1120 Extra bits are used for registers but not for addressing mechanisms.
1121 </p><div class="section" title="3.3.1. Support"><div class="titlepage"><div><div><h3 class="title"><a id="support"></a>3.3.1. Support</h3></div></div></div><p>
1122 While the x32 psABI specifications are not fully finalized, this Yocto Project
1123 release supports current development specifications of x32 psABI.
1124 As of this release of the Yocto Project, x32 psABI support exists as follows:
1125 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>You can create packages and images in x32 psABI format on x86_64 architecture targets.
1126 </p></li><li class="listitem"><p>You can use the x32 psABI support through the <code class="filename">meta-x32</code>
1127 layer on top of the OE-core/Yocto layer.</p></li><li class="listitem"><p>The toolchain from the <code class="filename">experimental/meta-x32</code> layer
1128 is used for building x32 psABI program binaries.</p></li><li class="listitem"><p>You can successfully build many recipes with the x32 toolchain.</p></li><li class="listitem"><p>You can create and boot <code class="filename">core-image-minimal</code> and
1129 <code class="filename">core-image-sato</code> images.</p></li></ul></div><p>
1130 </p></div><div class="section" title="3.3.2. Future Development and Limitations"><div class="titlepage"><div><div><h3 class="title"><a id="future-development-and-limitations"></a>3.3.2. Future Development and Limitations</h3></div></div></div><p>
1131 As of this Yocto Project release, the x32 psABI kernel and library interfaces
1132 specifications are not finalized.
1133 </p><p>
1134 Future Plans for the x32 psABI in the Yocto Project include the following:
1135 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Enhance and fix the few remaining recipes so they
1136 work with and support x32 toolchains.</p></li><li class="listitem"><p>Enhance RPM Package Manager (RPM) support for x32 binaries.</p></li><li class="listitem"><p>Support larger images.</p></li><li class="listitem"><p>Integrate x32 recipes, toolchain, and kernel changes from
1137 <code class="filename">experimental/meta-x32</code> into OE-core.</p></li></ul></div><p>
1138 </p></div><div class="section" title="3.3.3. Using x32 Right Now"><div class="titlepage"><div><div><h3 class="title"><a id="using-x32-right-now"></a>3.3.3. Using x32 Right Now</h3></div></div></div><p>
1139 Despite the fact the x32 psABI support is in development state for this release of the
1140 Yocto Project, you can follow these steps to use the x32 spABI:
1141 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Add the <code class="filename">experimental/meta-x32</code> layer to your local
1142 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
1143 You can find the <code class="filename">experimental/meta-x32</code> source repository at
1144 <a class="ulink" href="http://git.yoctoproject.org" target="_top">http://git.yoctoproject.org</a>.</p></li><li class="listitem"><p>Edit your <code class="filename">conf/bblayers.conf</code> file so that it includes
1145 the <code class="filename">meta-x32</code>.
1146 Here is an example:
1147 </p><pre class="literallayout">
1148 BBLAYERS ?= " \
1149 /home/nitin/prj/poky.git/meta \
1150 /home/nitin/prj/poky.git/meta-yocto \
1151 /home/nitin/prj/poky.git/meta-yocto-bsp \
1152 /home/nitin/prj/meta-x32.git \
1153 "
1154 BBLAYERS_NON_REMOVABLE ?= " \
1155 /home/nitin/prj/poky.git/meta \
1156 /home/nitin/prj/poky.git/meta-yocto \
1157 "
1158 </pre></li><li class="listitem"><p>Enable the x32 psABI tuning file for <code class="filename">x86_64</code>
1159 machines by editing the <code class="filename">conf/local.conf</code> like this:
1160 </p><pre class="literallayout">
1161 MACHINE = "qemux86-64"
1162 DEFAULTTUNE = "x86-64-x32"
1163 baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
1164 or 'INVALID'), True) or 'lib'}"
1165 #MACHINE = "atom-pc"
1166 #DEFAULTTUNE = "core2-64-x32"
1167 </pre></li><li class="listitem"><p>As usual, use BitBake to build an image that supports the x32 psABI.
1168 Here is an example:
1169 </p><pre class="literallayout">
1170 $ bitake core-image-sato
1171 </pre></li><li class="listitem"><p>As usual, run your image using QEMU:
1172 </p><pre class="literallayout">
1173 $ runqemu qemux86-64 core-image-sato
1174 </pre></li></ul></div><p>
1175 </p></div></div><div class="section" title="3.4. Licenses"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="licenses"></a>3.4. Licenses</h2></div></div></div><p>
1176 This section describes the mechanism by which the OpenEmbedded build system
1177 tracks changes to licensing text.
1178 The section also describes how to enable commercially licensed recipes,
1179 which by default are disabled.
1180 </p><p>
1181 For information that can help you maintain compliance with various open
1182 source licensing during the lifecycle of the product, see the
1183 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#maintaining-open-source-license-compliance-during-your-products-lifecycle" target="_top">Maintaining Open Source License Compliance During Your Project's Lifecycle</a>" section
1184 in the Yocto Project Development Manual.
1185 </p><div class="section" title="3.4.1. Tracking License Changes"><div class="titlepage"><div><div><h3 class="title"><a id="usingpoky-configuring-LIC_FILES_CHKSUM"></a>3.4.1. Tracking License Changes</h3></div></div></div><p>
1186 The license of an upstream project might change in the future.
1187 In order to prevent these changes going unnoticed, the
1188 <code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a></code>
1189 variable tracks changes to the license text. The checksums are validated at the end of the
1190 configure step, and if the checksums do not match, the build will fail.
1191 </p><div class="section" title="3.4.1.1. Specifying the LIC_FILES_CHKSUM Variable"><div class="titlepage"><div><div><h4 class="title"><a id="usingpoky-specifying-LIC_FILES_CHKSUM"></a>3.4.1.1. Specifying the <code class="filename">LIC_FILES_CHKSUM</code> Variable</h4></div></div></div><p>
1192 The <code class="filename">LIC_FILES_CHKSUM</code>
1193 variable contains checksums of the license text in the source code for the recipe.
1194 Following is an example of how to specify <code class="filename">LIC_FILES_CHKSUM</code>:
1195 </p><pre class="literallayout">
1196 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
1197 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
1198 file://licfile2.txt;endline=50;md5=zzzz \
1199 ..."
1200 </pre><p>
1201 </p><p>
1202 The build system uses the
1203 <code class="filename"><a class="link" href="#var-S" title="S">S</a></code> variable as the
1204 default directory used when searching files listed in
1205 <code class="filename">LIC_FILES_CHKSUM</code>.
1206 The previous example employs the default directory.
1207 </p><p>
1208 You can also use relative paths as shown in the following example:
1209 </p><pre class="literallayout">
1210 LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
1211 md5=bb14ed3c4cda583abc85401304b5cd4e"
1212 LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
1213 </pre><p>
1214 </p><p>
1215 In this example, the first line locates a file in
1216 <code class="filename">${S}/src/ls.c</code>.
1217 The second line refers to a file in
1218 <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, which is the parent
1219 of <code class="filename"><a class="link" href="#var-S" title="S">S</a></code>.
1220 </p><p>
1221 Note that this variable is mandatory for all recipes, unless the
1222 <code class="filename">LICENSE</code> variable is set to "CLOSED".
1223 </p></div><div class="section" title="3.4.1.2. Explanation of Syntax"><div class="titlepage"><div><div><h4 class="title"><a id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax"></a>3.4.1.2. Explanation of Syntax</h4></div></div></div><p>
1224 As mentioned in the previous section, the
1225 <code class="filename">LIC_FILES_CHKSUM</code> variable lists all the
1226 important files that contain the license text for the source code.
1227 It is possible to specify a checksum for an entire file, or a specific section of a
1228 file (specified by beginning and ending line numbers with the "beginline" and "endline"
1229 parameters, respectively).
1230 The latter is useful for source files with a license notice header,
1231 README documents, and so forth.
1232 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
1233 first line of the file.
1234 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
1235 ends with the last line of the file.
1236 </p><p>
1237 The "md5" parameter stores the md5 checksum of the license text.
1238 If the license text changes in any way as compared to this parameter
1239 then a mismatch occurs.
1240 This mismatch triggers a build failure and notifies the developer.
1241 Notification allows the developer to review and address the license text changes.
1242 Also note that if a mismatch occurs during the build, the correct md5
1243 checksum is placed in the build log and can be easily copied to the recipe.
1244 </p><p>
1245 There is no limit to how many files you can specify using the
1246 <code class="filename">LIC_FILES_CHKSUM</code> variable.
1247 Generally, however, every project requires a few specifications for license tracking.
1248 Many projects have a "COPYING" file that stores the license information for all the source
1249 code files.
1250 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
1251 </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
1252 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
1253 error and displays the correct "md5" parameter value during the build.
1254 The correct parameter is also captured in the build log.
1255 </div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
1256 If the whole file contains only license text, you do not need to use the "beginline" and
1257 "endline" parameters.
1258 </div></div></div><div class="section" title="3.4.2. Enabling Commercially Licensed Recipes"><div class="titlepage"><div><div><h3 class="title"><a id="enabling-commercially-licensed-recipes"></a>3.4.2. Enabling Commercially Licensed Recipes</h3></div></div></div><p>
1259 By default, the OpenEmbedded build system disables
1260 components that have commercial or other special licensing
1261 requirements.
1262 Such requirements are defined on a
1263 recipe-by-recipe basis through the <code class="filename">LICENSE_FLAGS</code> variable
1264 definition in the affected recipe.
1265 For instance, the
1266 <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code>
1267 recipe contains the following statement:
1268 </p><pre class="literallayout">
1269 LICENSE_FLAGS = "commercial"
1270 </pre><p>
1271 Here is a slightly more complicated example that contains both an
1272 explicit recipe name and version (after variable expansion):
1273 </p><pre class="literallayout">
1274 LICENSE_FLAGS = "license_${PN}_${PV}"
1275 </pre><p>
1276 In order for a component restricted by a <code class="filename">LICENSE_FLAGS</code>
1277 definition to be enabled and included in an image, it
1278 needs to have a matching entry in the global
1279 <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, which is a variable
1280 typically defined in your <code class="filename">local.conf</code> file.
1281 For example, to enable
1282 the <code class="filename">$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</code>
1283 package, you could add either the string
1284 "commercial_gst-plugins-ugly" or the more general string
1285 "commercial" to <code class="filename">LICENSE_FLAGS_WHITELIST</code>.
1286 See the
1287 "<a class="link" href="#license-flag-matching" title="3.4.2.1. License Flag Matching">License Flag Matching</a>" section
1288 for a full explanation of how <code class="filename">LICENSE_FLAGS</code> matching works.
1289 Here is the example:
1290 </p><pre class="literallayout">
1291 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
1292 </pre><p>
1293 Likewise, to additionally enable the package built from the recipe containing
1294 <code class="filename">LICENSE_FLAGS = "license_${PN}_${PV}"</code>, and assuming
1295 that the actual recipe name was <code class="filename">emgd_1.10.bb</code>,
1296 the following string would enable that package as well as
1297 the original <code class="filename">gst-plugins-ugly</code> package:
1298 </p><pre class="literallayout">
1299 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
1300 </pre><p>
1301 As a convenience, you do not need to specify the complete license string
1302 in the whitelist for every package.
1303 you can use an abbreviated form, which consists
1304 of just the first portion or portions of the license string before
1305 the initial underscore character or characters.
1306 A partial string will match
1307 any license that contains the given string as the first
1308 portion of its license.
1309 For example, the following
1310 whitelist string will also match both of the packages
1311 previously mentioned as well as any other packages that have
1312 licenses starting with "commercial" or "license".
1313 </p><pre class="literallayout">
1314 LICENSE_FLAGS_WHITELIST = "commercial license"
1315 </pre><p>
1316 </p><div class="section" title="3.4.2.1. License Flag Matching"><div class="titlepage"><div><div><h4 class="title"><a id="license-flag-matching"></a>3.4.2.1. License Flag Matching</h4></div></div></div><p>
1317 The definition of 'matching' in reference to a
1318 recipe's <code class="filename">LICENSE_FLAGS</code> setting is simple.
1319 However, some things exist that you should know about in order to
1320 correctly and effectively use it.
1321 </p><p>
1322 Before a flag
1323 defined by a particular recipe is tested against the
1324 contents of the <code class="filename">LICENSE_FLAGS_WHITELIST</code> variable, the
1325 string <code class="filename">_${PN}</code> (with
1326 <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> expanded of course) is
1327 appended to the flag, thus automatically making each
1328 <code class="filename">LICENSE_FLAGS</code> value recipe-specific.
1329 That string is
1330 then matched against the whitelist.
1331 So if you specify <code class="filename">LICENSE_FLAGS = "commercial"</code> in recipe
1332 "foo" for example, the string <code class="filename">"commercial_foo"</code>
1333 would normally be what is specified in the whitelist in order for it to
1334 match.
1335 </p><p>
1336 You can broaden the match by
1337 putting any "_"-separated beginning subset of a
1338 <code class="filename">LICENSE_FLAGS</code> flag in the whitelist, which will also
1339 match.
1340 For example, simply specifying "commercial" in
1341 the whitelist would match any expanded <code class="filename">LICENSE_FLAGS</code>
1342 definition starting with "commercial" such as
1343 "commercial_foo" and "commercial_bar", which are the
1344 strings that would be automatically generated for
1345 hypothetical "foo" and "bar" recipes assuming those
1346 recipes had simply specified the following:
1347 </p><pre class="literallayout">
1348 LICENSE_FLAGS = "commercial"
1349 </pre><p>
1350 </p><p>
1351 Broadening the match allows for a range of specificity for the items
1352 in the whitelist, from more general to perfectly
1353 specific.
1354 So you have the choice of exhaustively
1355 enumerating each license flag in the whitelist to
1356 allow only those specific recipes into the image, or
1357 of using a more general string to pick up anything
1358 matching just the first component or components of the specified
1359 string.
1360 </p><p>
1361 This scheme works even if the flag already
1362 has <code class="filename">_${PN}</code> appended - the extra <code class="filename">_${PN}</code> is
1363 redundant, but does not affect the outcome.
1364 For example, a license flag of "commercial_1.2_foo" would
1365 turn into "commercial_1.2_foo_foo" and would match
1366 both the general "commercial" and the specific
1367 "commercial_1.2_foo", as expected.
1368 The flag would also match
1369 "commercial_1.2_foo_foo" and "commercial_1.2", which
1370 does not make much sense regarding use in the whitelist.
1371 </p><p>
1372 For a versioned string, you could instead specify
1373 "commercial_foo_1.2", which would turn into
1374 "commercial_foo_1.2_foo".
1375 And, as expected, this flag allows
1376 you to pick up this package along with
1377 anything else "commercial" when you specify "commercial"
1378 in the whitelist.
1379 Or, the flag allows you to pick up this package along with anything "commercial_foo"
1380 regardless of version when you use "commercial_foo" in the whitelist.
1381 Finally, you can be completely specific about the package and version and specify
1382 "commercial_foo_1.2" package and version.
1383 </p></div><div class="section" title="3.4.2.2. Other Variables Related to Commercial Licenses"><div class="titlepage"><div><div><h4 class="title"><a id="other-variables-related-to-commercial-licenses"></a>3.4.2.2. Other Variables Related to Commercial Licenses</h4></div></div></div><p>
1384 Other helpful variables related to commercial
1385 license handling exist and are defined in the
1386 <code class="filename">$HOME/poky/meta/conf/distro/include/default-distrovars.inc</code> file:
1387 </p><pre class="literallayout">
1388 COMMERCIAL_AUDIO_PLUGINS ?= ""
1389 COMMERCIAL_VIDEO_PLUGINS ?= ""
1390 COMMERCIAL_QT = ""
1391 </pre><p>
1392 If you want to enable these components, you can do so by making sure you have
1393 the following statements in your <code class="filename">local.conf</code> configuration file:
1394 </p><pre class="literallayout">
1395 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
1396 gst-plugins-ugly-mpegaudioparse"
1397 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
1398 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
1399 COMMERCIAL_QT ?= "qmmp"
1400 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
1401 </pre><p>
1402 Of course, you could also create a matching whitelist
1403 for those components using the more general "commercial"
1404 in the whitelist, but that would also enable all the
1405 other packages with <code class="filename">LICENSE_FLAGS</code> containing
1406 "commercial", which you may or may not want:
1407 </p><pre class="literallayout">
1408 LICENSE_FLAGS_WHITELIST = "commercial"
1409 </pre><p>
1410 </p><p>
1411 Specifying audio and video plug-ins as part of the
1412 <code class="filename">COMMERCIAL_AUDIO_PLUGINS</code> and
1413 <code class="filename">COMMERCIAL_VIDEO_PLUGINS</code> statements
1414 or commercial qt components as part of
1415 the <code class="filename">COMMERCIAL_QT</code> statement (along
1416 with the enabling <code class="filename">LICENSE_FLAGS_WHITELIST</code>) includes the
1417 plug-ins or components into built images, thus adding
1418 support for media formats or components.
1419 </p></div></div></div></div>
1420
1421 <div class="chapter" title="Chapter 4. Migrating to a Newer Yocto Project Release"><div class="titlepage"><div><div><h2 class="title"><a id="migration"></a>Chapter 4. Migrating to a Newer Yocto Project Release</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#moving-to-the-yocto-project-1.3-release">4.1. Moving to the Yocto Project 1.3 Release</a></span></dt><dd><dl><dt><span class="section"><a href="#1.3-local-configuration">4.1.1. Local Configuration</a></span></dt><dt><span class="section"><a href="#1.3-recipes">4.1.2. Recipes</a></span></dt></dl></dd></dl></div><p>
1422 This chapter provides information you can use to migrate work to a
1423 newer Yocto Project release. You can find the same information in the
1424 release notes for a given release.
1425 </p><div class="section" title="4.1. Moving to the Yocto Project 1.3 Release"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="moving-to-the-yocto-project-1.3-release"></a>4.1. Moving to the Yocto Project 1.3 Release</h2></div></div></div><p>
1426 This section provides migration information for moving to the
1427 Yocto Project 1.3 Release.
1428 </p><div class="section" title="4.1.1. Local Configuration"><div class="titlepage"><div><div><h3 class="title"><a id="1.3-local-configuration"></a>4.1.1. Local Configuration</h3></div></div></div><p>
1429 Differences include changes for
1430 <a class="link" href="#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a>
1431 and <code class="filename">bblayers.conf</code>.
1432 </p><div class="section" title="4.1.1.1. SSTATE_MIRRORS"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-sstate-mirrors"></a>4.1.1.1. SSTATE_MIRRORS</h4></div></div></div><p>
1433 The shared state cache (sstate-cache) as pointed to by
1434 <a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a> by default
1435 now has two-character subdirectories to prevent there being an issue with too
1436 many files in the same directory.
1437 Also, native sstate-cache packages will go into a subdirectory named using
1438 the distro ID string.
1439 If you copy the newly structured sstate-cache to a mirror location
1440 (either local or remote) and then point to it in
1441 <a class="link" href="#var-SSTATE_MIRRORS" title="SSTATE_MIRRORS"><code class="filename">SSTATE_MIRRORS</code></a>,
1442 you need to append "PATH" to the end of the mirror URL so that
1443 the path used by BitBake before the mirror substitution is
1444 appended to the path used to access the mirror.
1445 Here is an example:
1446 </p><pre class="literallayout">
1447 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
1448 </pre><p>
1449 </p></div><div class="section" title="4.1.1.2. bblayers.conf"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-bblayers-conf"></a>4.1.1.2. bblayers.conf</h4></div></div></div><p>
1450 The <code class="filename">meta-yocto</code> layer has been split into
1451 two parts: <code class="filename">meta-yocto</code> and
1452 <code class="filename">meta-yocto-bsp</code>, corresponding to the
1453 Poky reference distro configuration and the reference
1454 hardware Board Support Packages (BSPs), respectively.
1455 When running BitBake or Hob for the first time after upgrading,
1456 your <code class="filename">conf/bblayers.conf</code> file will be
1457 updated to handle this change and you will be asked to
1458 re-run/restart for the changes to take effect.
1459 </p></div></div><div class="section" title="4.1.2. Recipes"><div class="titlepage"><div><div><h3 class="title"><a id="1.3-recipes"></a>4.1.2. Recipes</h3></div></div></div><p>
1460 Differences include changes for the following:
1461 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Python function whitespace</p></li><li class="listitem"><p><code class="filename">proto=</code> in <code class="filename">SRC_URI</code></p></li><li class="listitem"><p><code class="filename">nativesdk</code></p></li><li class="listitem"><p>Task recipes</p></li><li class="listitem"><p><code class="filename">IMAGE_FEATURES</code></p></li><li class="listitem"><p>Removed recipes</p></li></ul></div><p>
1462 </p><div class="section" title="4.1.2.1. Python Function Whitespace"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-python-function-whitespace"></a>4.1.2.1. Python Function Whitespace</h4></div></div></div><p>
1463 All Python functions must now use four spaces for indentation.
1464 Previously, an inconsistent mix of spaces and tabs existed,
1465 which made extending these functions using
1466 <code class="filename">_append</code> or <code class="filename">_prepend</code>
1467 complicated given that Python treats whitespace as
1468 syntactically significant.
1469 If you are defining or extending any Python functions (e.g.
1470 <code class="filename">populate_packages</code>, <code class="filename">do_unpack</code>,
1471 <code class="filename">do_patch</code> and so forth) in custom recipes
1472 or classes, you need to ensure you are using consistent
1473 four-space indentation.
1474 </p></div><div class="section" title="4.1.2.2. proto= in SRC_URI"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-proto=-in-src-uri"></a>4.1.2.2. proto= in SRC_URI</h4></div></div></div><p>
1475 Any use of <code class="filename">proto=</code> in
1476 <a class="link" href="#var-SRC_URI" title="SRC_URI"><code class="filename">SRC_URI</code></a>
1477 needs to be changed to <code class="filename">protocol=</code>.
1478 In particular, this applies to the following URIs:
1479 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">svn://</code></p></li><li class="listitem"><p><code class="filename">bzr://</code></p></li><li class="listitem"><p><code class="filename">hg://</code></p></li><li class="listitem"><p><code class="filename">osc://</code></p></li></ul></div><p>
1480 Other URIs were already using <code class="filename">protocol=</code>.
1481 This change improves consistency.
1482 </p></div><div class="section" title="4.1.2.3. nativesdk"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-nativesdk"></a>4.1.2.3. nativesdk</h4></div></div></div><p>
1483 The suffix <code class="filename">nativesdk</code> is now implemented
1484 as a prefix, which simplifies a lot of the packaging code for
1485 <code class="filename">nativesdk</code> recipes.
1486 All custom <code class="filename">nativesdk</code> recipes and any
1487 references need to be updated to use
1488 <code class="filename">nativesdk-*</code> instead of
1489 <code class="filename">*-nativesdk</code>.
1490 </p></div><div class="section" title="4.1.2.4. Task Recipes"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-task-recipes"></a>4.1.2.4. Task Recipes</h4></div></div></div><p>
1491 "Task" recipes are now known as "Package groups" and have
1492 been renamed from <code class="filename">task-*.bb</code> to
1493 <code class="filename">packagegroup-*.bb</code>.
1494 Existing references to the previous <code class="filename">task-*</code>
1495 names should work in most cases as there is an automatic
1496 upgrade path for most packages.
1497 However, you should update references in your own recipes and
1498 configurations as they could be removed in future releases.
1499 You should also rename any custom <code class="filename">task-*</code>
1500 recipes to <code class="filename">packagegroup-*</code>, and change
1501 them to inherit <code class="filename">packagegroup</code> instead of
1502 <code class="filename">task</code>, as well as taking the opportunity
1503 to remove anything now handled by
1504 <code class="filename">packagegroup.bbclass</code>, such as providing
1505 <code class="filename">-dev</code> and <code class="filename">-dbg</code>
1506 packages, setting
1507 <a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM"><code class="filename">LIC_FILES_CHKSUM</code></a>,
1508 and so forth.
1509 See the
1510 "<a class="link" href="#ref-classes-packagegroup" title="7.12. Package Groups - packagegroup.bbclass">Package Groups - packagegroup.bbclass</a>"
1511 section for further details.
1512 </p></div><div class="section" title="4.1.2.5. IMAGE_FEATURES"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-image-features"></a>4.1.2.5. IMAGE_FEATURES</h4></div></div></div><p>
1513 Image recipes that previously included "apps-console-core"
1514 in <a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES"><code class="filename">IMAGE_FEATURES</code></a>
1515 should now include "splash" instead to enable the boot-up
1516 splash screen.
1517 Retaining "apps-console-core" will still include the splash
1518 screen generates a warning.
1519 The "apps-x11-core" and "apps-x11-games"
1520 <code class="filename">IMAGE_FEATURES</code> features have been removed.
1521 </p></div><div class="section" title="4.1.2.6. Removed Recipes"><div class="titlepage"><div><div><h4 class="title"><a id="migration-1.3-removed-recipes"></a>4.1.2.6. Removed Recipes</h4></div></div></div><p>
1522 The following recipes have been removed.
1523 For most of them, it is unlikely that you would have any
1524 references to them in your own metadata.
1525 However, you should check your metadata against this list to be sure:
1526 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">libx11-trim</code></em></span>:
1527 Replaced by <code class="filename">libx11</code>, which has a negligible
1528 size difference with modern Xorg.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">xserver-xorg-lite</code></em></span>:
1529 Use <code class="filename">xserver-xorg</code>, which has a negligible
1530 size difference when DRI and GLX modules are not installed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">xserver-kdrive</code></em></span>:
1531 Effectively unmaintained for many years.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">mesa-xlib</code></em></span>:
1532 No longer serves any purpose.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">galago</code></em></span>:
1533 Replaced by telepathy.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">gail</code></em></span>:
1534 Functionality was integrated into GTK+ 2.13.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">eggdbus</code></em></span>:
1535 No longer needed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">gcc-*-intermediate</code></em></span>:
1536 The build has been restructured to avoid the need for
1537 this step.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">libgsmd</code></em></span>:
1538 Unmaintained for many years.
1539 Functionality now provided by
1540 <code class="filename">ofono</code> instead.</p></li><li class="listitem"><p><span class="emphasis"><em>contacts, dates, tasks, eds-tools</em></span>:
1541 Largely unmaintained PIM application suite.
1542 It has been moved to <code class="filename">meta-gnome</code>
1543 in <code class="filename">meta-openembedded</code>.</p></li></ul></div><p>
1544 In addition to the previously listed changes, the
1545 <code class="filename">meta-demoapps</code> directory has also been removed
1546 because the recipes in it were not being maintained and many
1547 had become obsolete or broken.
1548 Additionally, these recipes were not parsed in the default configuration.
1549 Many of these recipes are already provided in an updated and
1550 maintained form within OpenEmbedded community layers such as
1551 <code class="filename">meta-oe</code> and <code class="filename">meta-gnome</code>.
1552 For the remainder, you can now find them in the
1553 <code class="filename">meta-extras</code> repository, which is in the
1554 Yocto Project source repositories.
1555 </p></div></div></div></div>
1556
1557 <div class="chapter" title="Chapter 5. Source Directory Structure"><div class="titlepage"><div><div><h2 class="title"><a id="ref-structure"></a>Chapter 5. Source Directory Structure</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#structure-core">5.1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">5.1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">5.1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#handbook">5.1.3. <code class="filename">documentation</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">5.1.4. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-yocto">5.1.5. <code class="filename">meta-yocto/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-yocto-bsp">5.1.6. <code class="filename">meta-yocto-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-hob">5.1.7. <code class="filename">meta-hob/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-skeleton">5.1.8. <code class="filename">meta-skeleton/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">5.1.9. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">5.1.10. <code class="filename">oe-init-build-env</code></a></span></dt><dt><span class="section"><a href="#structure-basic-top-level">5.1.11. <code class="filename">LICENSE, README, and README.hardware</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">5.2. The Build Directory - <code class="filename">build/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-pseudodone">5.2.1. <code class="filename">build/pseudodone</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-local.conf">5.2.2. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-bblayers.conf">5.2.3. <code class="filename">build/conf/bblayers.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-conf-sanity_info">5.2.4. <code class="filename">build/conf/sanity_info</code></a></span></dt><dt><span class="section"><a href="#structure-build-downloads">5.2.5. <code class="filename">build/downloads/</code></a></span></dt><dt><span class="section"><a href="#structure-build-sstate-cache">5.2.6. <code class="filename">build/sstate-cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">5.2.7. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-buildstats">5.2.8. <code class="filename">build/tmp/buildstats/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">5.2.9. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">5.2.10. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">5.2.11. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-rpm">5.2.12. <code class="filename">build/tmp/deploy/rpm/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-licenses">5.2.13. <code class="filename">build/tmp/deploy/licenses/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">5.2.14. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">5.2.15. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-sysroots">5.2.16. <code class="filename">build/tmp/sysroots/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">5.2.17. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-log">5.2.18. <code class="filename">build/tmp/log/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-pkgdata">5.2.19. <code class="filename">build/tmp/pkgdata/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">5.2.20. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">5.3. The Metadata - <code class="filename">meta/</code></a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">5.3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">5.3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">5.3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">5.3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-bsp">5.3.5. <code class="filename">meta/recipes-bsp/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-connectivity">5.3.6. <code class="filename">meta/recipes-connectivity/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-core">5.3.7. <code class="filename">meta/recipes-core/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-devtools">5.3.8. <code class="filename">meta/recipes-devtools/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-extended">5.3.9. <code class="filename">meta/recipes-extended/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-gnome">5.3.10. <code class="filename">meta/recipes-gnome/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-graphics">5.3.11. <code class="filename">meta/recipes-graphics/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-kernel">5.3.12. <code class="filename">meta/recipes-kernel/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-multimedia">5.3.13. <code class="filename">meta/recipes-multimedia/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-qt">5.3.14. <code class="filename">meta/recipes-qt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-rt">5.3.15. <code class="filename">meta/recipes-rt/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-sato">5.3.16. <code class="filename">meta/recipes-sato/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-support">5.3.17. <code class="filename">meta/recipes-support/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">5.3.18. <code class="filename">meta/site/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-recipes-txt">5.3.19. <code class="filename">meta/recipes.txt</code></a></span></dt></dl></dd></dl></div><p>
1558 The <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> consists of several components.
1559 Understanding them and knowing where they are located is key to using the Yocto Project well.
1560 This chapter describes the Source Directory and gives information about the various
1561 files and directories.
1562</p><p>
1563 For information on how to establish a local Source Directory on your development system, see the
1564 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#getting-setup" target="_top">Getting Set Up</a>"
1565 section in the Yocto Project Development Manual.
1566</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1567 The OpenEmbedded build system does not support file or directory names that
1568 contain spaces.
1569 Be sure that the Source Directory you use does not contain these types
1570 of names.
1571</div><div class="section" title="5.1. Top level core components"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-core"></a>5.1. Top level core components</h2></div></div></div><div class="section" title="5.1.1. bitbake/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-bitbake"></a>5.1.1. <code class="filename">bitbake/</code></h3></div></div></div><p>
1572 The <a class="ulink" href="source-directory" target="_top">Source Directory</a>
1573 includes a copy of BitBake for ease of use.
1574 The copy usually matches the current stable BitBake release from the BitBake project.
1575 BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks
1576 defined by that data.
1577 Failures are usually from the metadata and not from BitBake itself.
1578 Consequently, most users do not need to worry about BitBake.
1579 </p><p>
1580 When you run the <code class="filename">bitbake</code> command, the wrapper script in
1581 <code class="filename">scripts/</code> is executed to run the main BitBake executable,
1582 which resides in the <code class="filename">bitbake/bin/</code> directory.
1583 Sourcing the <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">oe-init-build-env</a>
1584 script places the <code class="filename">scripts</code> and <code class="filename">bitbake/bin</code>
1585 directories (in that order) into the shell's <code class="filename">PATH</code> environment
1586 variable.
1587 </p><p>
1588 For more information on BitBake, see the BitBake documentation
1589 inculded in the <code class="filename">bitbake/doc/manual</code> directory of the
1590 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
1591 </p></div><div class="section" title="5.1.2. build/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-build"></a>5.1.2. <code class="filename">build/</code></h3></div></div></div><p>
1592 This directory contains user configuration files and the output
1593 generated by the OpenEmbedded build system in its standard configuration where
1594 the source tree is combined with the output.
1595 The <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>
1596 is created initially when you <code class="filename">source</code>
1597 the OpenEmbedded build environment setup script <code class="filename">oe-init-build-env</code>.
1598 </p><p>
1599 It is also possible to place output and configuration
1600 files in a directory separate from the
1601 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>
1602 by providing a directory name when you <code class="filename">source</code>
1603 the setup script.
1604 For information on separating output from your local Source Directory files, see <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">oe-init-build-env</a>.
1605 </p></div><div class="section" title="5.1.3. documentation"><div class="titlepage"><div><div><h3 class="title"><a id="handbook"></a>5.1.3. <code class="filename">documentation</code></h3></div></div></div><p>
1606 This directory holds the source for the Yocto Project documentation
1607 as well as templates and tools that allow you to generate PDF and HTML
1608 versions of the manuals.
1609 Each manual is contained in a sub-folder.
1610 For example, the files for this manual reside in
1611 <code class="filename">ref-manual</code>.
1612 </p></div><div class="section" title="5.1.4. meta/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta"></a>5.1.4. <code class="filename">meta/</code></h3></div></div></div><p>
1613 This directory contains the OpenEmbedded Core metadata.
1614 The directory holds recipes, common classes, and machine
1615 configuration for emulated targets (qemux86, qemuarm,
1616 and so on.)
1617 </p></div><div class="section" title="5.1.5. meta-yocto/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta-yocto"></a>5.1.5. <code class="filename">meta-yocto/</code></h3></div></div></div><p>
1618 This directory contains the configuration for the Poky
1619 reference distribution.
1620 </p></div><div class="section" title="5.1.6. meta-yocto-bsp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-meta-yocto-bsp"></a>5.1.6. <code class="filename">meta-yocto-bsp/</code></h3></div></div></div><p>
1621 This directory contains the Yocto Project reference
1622 hardware BSPs.
1623 </p></div><div class="section" title="5.1.7. meta-hob/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-hob"></a>5.1.7. <code class="filename">meta-hob/</code></h3></div></div></div><p>
1624 This directory contains template recipes used by the
1625 <a class="ulink" href="http://www.yoctoproject.org/projects/hob" target="_top">Hob</a>
1626 build UI.
1627 </p></div><div class="section" title="5.1.8. meta-skeleton/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-skeleton"></a>5.1.8. <code class="filename">meta-skeleton/</code></h3></div></div></div><p>
1628 This directory contains template recipes for BSP and kernel development.
1629 </p></div><div class="section" title="5.1.9. scripts/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-scripts"></a>5.1.9. <code class="filename">scripts/</code></h3></div></div></div><p>
1630 This directory contains various integration scripts that implement
1631 extra functionality in the Yocto Project environment (e.g. QEMU scripts).
1632 The <a class="link" href="#structure-core-script" title="5.1.10. oe-init-build-env">oe-init-build-env</a> script appends this
1633 directory to the shell's <code class="filename">PATH</code> environment variable.
1634 </p><p>
1635 The <code class="filename">scripts</code> directory has useful scripts that assist contributing
1636 back to the Yocto Project, such as <code class="filename">create_pull_request</code> and
1637 <code class="filename">send_pull_request</code>.
1638 </p></div><div class="section" title="5.1.10. oe-init-build-env"><div class="titlepage"><div><div><h3 class="title"><a id="structure-core-script"></a>5.1.10. <code class="filename">oe-init-build-env</code></h3></div></div></div><p>
1639 This script sets up the OpenEmbedded build environment.
1640 Running this script with the <code class="filename">source</code> command in
1641 a shell makes changes to <code class="filename">PATH</code> and sets other core BitBake variables based on the
1642 current working directory.
1643 You need to run this script before running BitBake commands.
1644 The script uses other scripts within the <code class="filename">scripts</code> directory to do
1645 the bulk of the work.
1646 </p><p>
1647 By default, running this script without a Build Directory argument creates the
1648 <code class="filename">build</code> directory.
1649 If you provide a Build Directory argument when you <code class="filename">source</code>
1650 the script, you direct OpenEmbedded build system to create a
1651 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a> of your choice.
1652 For example, the following command creates a Build Directory named
1653 <code class="filename">mybuilds</code> that is outside of the
1654 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>:
1655 </p><pre class="literallayout">
1656 $ source oe-init-build-env ~/mybuilds
1657 </pre><p>
1658 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1659 The OpenEmbedded build system does not support file or directory names that
1660 contain spaces.
1661 If you attempt to run the <code class="filename">oe-init-build-env</code> script
1662 from a Source Directory that contains spaces in either the filenames
1663 or directory names, the script returns an error indicating no such
1664 file or directory.
1665 Be sure to use a Source Directory free of names containing spaces.
1666 </div><p>
1667 </p></div><div class="section" title="5.1.11. LICENSE, README, and README.hardware"><div class="titlepage"><div><div><h3 class="title"><a id="structure-basic-top-level"></a>5.1.11. <code class="filename">LICENSE, README, and README.hardware</code></h3></div></div></div><p>
1668 These files are standard top-level files.
1669 </p></div></div><div class="section" title="5.2. The Build Directory - build/"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-build"></a>5.2. The Build Directory - <code class="filename">build/</code></h2></div></div></div><div class="section" title="5.2.1. build/pseudodone"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-pseudodone"></a>5.2.1. <code class="filename">build/pseudodone</code></h3></div></div></div><p>
1670 This tag file indicates that the initial pseudo binary was created.
1671 The file is built the first time BitBake is invoked.
1672 </p></div><div class="section" title="5.2.2. build/conf/local.conf"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-local.conf"></a>5.2.2. <code class="filename">build/conf/local.conf</code></h3></div></div></div><p>
1673 This file contains all the local user configuration for your build environment.
1674 If there is no <code class="filename">local.conf</code> present, it is created from
1675 <code class="filename">local.conf.sample</code>.
1676 The <code class="filename">local.conf</code> file contains documentation on the various configuration options.
1677 Any variable set here overrides any variable set elsewhere within the environment unless
1678 that variable is hard-coded within a file (e.g. by using '=' instead of '?=').
1679 Some variables are hard-coded for various reasons but these variables are
1680 relatively rare.
1681 </p><p>
1682 Edit this file to set the <code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code>
1683 for which you want to build, which package types you wish to use
1684 (<a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES"><code class="filename">PACKAGE_CLASSES</code></a>),
1685 where you want to downloaded files
1686 (<code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code>),
1687 and how you want your host machine to use resources
1688 (<a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS"><code class="filename">BB_NUMBER_THREADS</code></a> and
1689 <a class="link" href="#var-PARALLEL_MAKE" title="PARALLEL_MAKE"><code class="filename">PARALLEL_MAKE</code></a>).
1690 </p></div><div class="section" title="5.2.3. build/conf/bblayers.conf"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-bblayers.conf"></a>5.2.3. <code class="filename">build/conf/bblayers.conf</code></h3></div></div></div><p>
1691 This file defines layers, which are directory trees, traversed (or walked) by BitBake.
1692 If <code class="filename">bblayers.conf</code>
1693 is not present, it is created from <code class="filename">bblayers.conf.sample</code> when
1694 you <code class="filename">source</code> the environment setup script.
1695 </p><p>
1696 The <code class="filename">bblayers.conf</code> file uses the
1697 <a class="link" href="#var-BBLAYERS" title="BBLAYERS"><code class="filename">BBLAYERS</code></a> variable to
1698 list the layers BitBake tries to find.
1699 The file uses the
1700 <a class="link" href="#var-BBLAYERS_NON_REMOVABLE" title="BBLAYERS_NON_REMOVABLE"><code class="filename">BBLAYERS_NON_REMOVABLE</code></a>
1701 variable to list layers that must not be removed.
1702 </p></div><div class="section" title="5.2.4. build/conf/sanity_info"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-conf-sanity_info"></a>5.2.4. <code class="filename">build/conf/sanity_info</code></h3></div></div></div><p>
1703 This file is created during the build to indicate the state of the sanity checks.
1704 </p></div><div class="section" title="5.2.5. build/downloads/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-downloads"></a>5.2.5. <code class="filename">build/downloads/</code></h3></div></div></div><p>
1705 This directory is used for the upstream source tarballs.
1706 The directory can be reused by multiple builds or moved to another location.
1707 You can control the location of this directory through the
1708 <code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code> variable.
1709 </p></div><div class="section" title="5.2.6. build/sstate-cache/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-sstate-cache"></a>5.2.6. <code class="filename">build/sstate-cache/</code></h3></div></div></div><p>
1710 This directory is used for the shared state cache.
1711 The directory can be reused by multiple builds or moved to another location.
1712 You can control the location of this directory through the
1713 <code class="filename"><a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR">SSTATE_DIR</a></code> variable.
1714 </p></div><div class="section" title="5.2.7. build/tmp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp"></a>5.2.7. <code class="filename">build/tmp/</code></h3></div></div></div><p>
1715 This directory receives all the OpenEmbedded build system's output.
1716 BitBake creates this directory if it does not exist.
1717 As a last resort, to clean up a build and start it from scratch (other than the downloads),
1718 you can remove everything in the <code class="filename">tmp</code> directory or get rid of the
1719 directory completely.
1720 If you do, you should also completely remove the <code class="filename">build/sstate-cache</code>
1721 directory as well.
1722 </p></div><div class="section" title="5.2.8. build/tmp/buildstats/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-buildstats"></a>5.2.8. <code class="filename">build/tmp/buildstats/</code></h3></div></div></div><p>
1723 This directory stores the build statistics.
1724 </p></div><div class="section" title="5.2.9. build/tmp/cache/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-cache"></a>5.2.9. <code class="filename">build/tmp/cache/</code></h3></div></div></div><p>
1725 When BitBake parses the metadata, it creates a cache file of the result that can
1726 be used when subsequently running commands.
1727 These results are stored here on a per-machine basis.
1728 </p></div><div class="section" title="5.2.10. build/tmp/deploy/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy"></a>5.2.10. <code class="filename">build/tmp/deploy/</code></h3></div></div></div><p>
1729 This directory contains any 'end result' output from the OpenEmbedded build process.
1730 </p></div><div class="section" title="5.2.11. build/tmp/deploy/deb/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-deb"></a>5.2.11. <code class="filename">build/tmp/deploy/deb/</code></h3></div></div></div><p>
1731 This directory receives any <code class="filename">.deb</code> packages produced by
1732 the build process.
1733 The packages are sorted into feeds for different architecture types.
1734 </p></div><div class="section" title="5.2.12. build/tmp/deploy/rpm/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-rpm"></a>5.2.12. <code class="filename">build/tmp/deploy/rpm/</code></h3></div></div></div><p>
1735 This directory receives any <code class="filename">.rpm</code> packages produced by
1736 the build process.
1737 The packages are sorted into feeds for different architecture types.
1738 </p></div><div class="section" title="5.2.13. build/tmp/deploy/licenses/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-licenses"></a>5.2.13. <code class="filename">build/tmp/deploy/licenses/</code></h3></div></div></div><p>
1739 This directory receives package licensing information.
1740 For example, the directory contains sub-directories for <code class="filename">bash</code>,
1741 <code class="filename">busybox</code>, and <code class="filename">eglibc</code> (among others) that in turn
1742 contain appropriate <code class="filename">COPYING</code> license files with other licensing information.
1743 </p></div><div class="section" title="5.2.14. build/tmp/deploy/images/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-images"></a>5.2.14. <code class="filename">build/tmp/deploy/images/</code></h3></div></div></div><p>
1744 This directory receives complete filesystem images.
1745 If you want to flash the resulting image from a build onto a device, look here for the image.
1746 </p><p>
1747 Be careful when deleting files in this directory.
1748 You can safely delete old images from this directory (e.g.
1749 <code class="filename">core-image-*</code>, <code class="filename">hob-image-*</code>,
1750 etc.).
1751 However, the kernel (<code class="filename">*zImage*</code>, <code class="filename">*uImage*</code>, etc.),
1752 bootloader and other supplementary files might be deployed here prior to building an
1753 image.
1754 Because these files, however, are not directly produced from the image, if you
1755 delete them they will not be automatically re-created when you build the image again.
1756 </p><p>
1757 If you do accidentally delete files here, you will need to force them to be
1758 re-created.
1759 In order to do that, you will need to know the target that produced them.
1760 For example, these commands rebuild and re-create the kernel files:
1761 </p><pre class="literallayout">
1762 $ bitbake -c clean virtual/kernel
1763 $ bitbake virtual/kernel
1764 </pre><p>
1765 </p></div><div class="section" title="5.2.15. build/tmp/deploy/ipk/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-deploy-ipk"></a>5.2.15. <code class="filename">build/tmp/deploy/ipk/</code></h3></div></div></div><p>
1766 This directory receives <code class="filename">.ipk</code> packages produced by
1767 the build process.</p></div><div class="section" title="5.2.16. build/tmp/sysroots/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-sysroots"></a>5.2.16. <code class="filename">build/tmp/sysroots/</code></h3></div></div></div><p>
1768 This directory contains shared header files and libraries as well as other shared
1769 data.
1770 Packages that need to share output with other packages do so within this directory.
1771 The directory is subdivided by architecture so multiple builds can run within
1772 the one Build Directory.
1773 </p></div><div class="section" title="5.2.17. build/tmp/stamps/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-stamps"></a>5.2.17. <code class="filename">build/tmp/stamps/</code></h3></div></div></div><p>
1774 This directory holds information that BitBake uses for accounting purposes
1775 to track what tasks have run and when they have run.
1776 The directory is sub-divided by architecture, package name, and
1777 version.
1778 Following is an example:
1779 </p><pre class="literallayout">
1780 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
1781 </pre><p>
1782 Although the files in the directory are empty of data,
1783 BitBake uses the filenames and timestamps for tracking purposes.
1784 </p></div><div class="section" title="5.2.18. build/tmp/log/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-log"></a>5.2.18. <code class="filename">build/tmp/log/</code></h3></div></div></div><p>
1785 This directory contains general logs that are not otherwise placed using the
1786 package's <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>.
1787 Examples of logs are the output from the <code class="filename">check_pkg</code> or
1788 <code class="filename">distro_check</code> tasks.
1789 Running a build does not necessarily mean this directory is created.
1790 </p></div><div class="section" title="5.2.19. build/tmp/pkgdata/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-pkgdata"></a>5.2.19. <code class="filename">build/tmp/pkgdata/</code></h3></div></div></div><p>
1791 This directory contains intermediate packaging data that is used later in the packaging process.
1792 For more information, see the "<a class="link" href="#ref-classes-package" title="7.13. Packaging - package*.bbclass">Packaging - package*.bbclass</a>" section.
1793 </p></div><div class="section" title="5.2.20. build/tmp/work/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-build-tmp-work"></a>5.2.20. <code class="filename">build/tmp/work/</code></h3></div></div></div><p>
1794 This directory contains architecture-specific work sub-directories
1795 for packages built by BitBake.
1796 All tasks execute from the appropriate work directory.
1797 For example, the source for a particular package is unpacked,
1798 patched, configured and compiled all within its own work directory.
1799 Within the work directory, organization is based on the package group
1800 and version for which the source is being compiled
1801 as defined by the
1802 <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>.
1803 </p><p>
1804 It is worth considering the structure of a typical work directory.
1805 As an example, consider the <code class="filename">linux-yocto-kernel-3.0</code>
1806 on the machine <code class="filename">qemux86</code>
1807 built within the Yocto Project.
1808 For this package, a work directory of
1809 <code class="filename">tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+&lt;.....&gt;</code>,
1810 referred to as the
1811 <code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>, is created.
1812 Within this directory, the source is unpacked to
1813 <code class="filename">linux-qemux86-standard-build</code> and then patched by Quilt
1814 (see the
1815 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#using-a-quilt-workflow" target="_top">Modifying Package
1816 Source Code with Quilt</a>" section in the Yocto Project Development Manual.
1817 Within the <code class="filename">linux-qemux86-standard-build</code> directory,
1818 standard Quilt directories <code class="filename">linux-3.0/patches</code>
1819 and <code class="filename">linux-3.0/.pc</code> are created,
1820 and standard Quilt commands can be used.
1821 </p><p>
1822 There are other directories generated within <code class="filename">WORKDIR</code>.
1823 The most important directory is <code class="filename">WORKDIR/temp/</code>,
1824 which has log files for each task (<code class="filename">log.do_*.pid</code>)
1825 and contains the scripts BitBake runs for each task
1826 (<code class="filename">run.do_*.pid</code>).
1827 The <code class="filename">WORKDIR/image/</code> directory is where "make
1828 install" places its output that is then split into sub-packages
1829 within <code class="filename">WORKDIR/packages-split/</code>.
1830 </p></div></div><div class="section" title="5.3. The Metadata - meta/"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="structure-meta"></a>5.3. The Metadata - <code class="filename">meta/</code></h2></div></div></div><p>
1831 As mentioned previously, metadata is the core of the Yocto Project.
1832 Metadata has several important subdivisions:
1833 </p><div class="section" title="5.3.1. meta/classes/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-classes"></a>5.3.1. <code class="filename">meta/classes/</code></h3></div></div></div><p>
1834 This directory contains the <code class="filename">*.bbclass</code> files.
1835 Class files are used to abstract common code so it can be reused by multiple
1836 packages.
1837 Every package inherits the <code class="filename">base.bbclass</code> file.
1838 Examples of other important classes are <code class="filename">autotools.bbclass</code>, which
1839 in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
1840 Another example is <code class="filename">kernel.bbclass</code> that contains common code and functions
1841 for working with the Linux kernel.
1842 Functions like image generation or packaging also have their specific class files
1843 such as <code class="filename">image.bbclass</code>, <code class="filename">rootfs_*.bbclass</code> and
1844 <code class="filename">package*.bbclass</code>.
1845 </p></div><div class="section" title="5.3.2. meta/conf/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf"></a>5.3.2. <code class="filename">meta/conf/</code></h3></div></div></div><p>
1846 This directory contains the core set of configuration files that start from
1847 <code class="filename">bitbake.conf</code> and from which all other configuration
1848 files are included.
1849 See the include statements at the end of the file and you will note that even
1850 <code class="filename">local.conf</code> is loaded from there.
1851 While <code class="filename">bitbake.conf</code> sets up the defaults, you can often override
1852 these by using the (<code class="filename">local.conf</code>) file, machine file or
1853 the distribution configuration file.
1854 </p></div><div class="section" title="5.3.3. meta/conf/machine/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf-machine"></a>5.3.3. <code class="filename">meta/conf/machine/</code></h3></div></div></div><p>
1855 This directory contains all the machine configuration files.
1856 If you set <code class="filename">MACHINE="qemux86"</code>,
1857 the OpenEmbedded build system looks for a <code class="filename">qemux86.conf</code> file in this
1858 directory.
1859 The <code class="filename">include</code> directory contains various data common to multiple machines.
1860 If you want to add support for a new machine to the Yocto Project, look in this directory.
1861 </p></div><div class="section" title="5.3.4. meta/conf/distro/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-conf-distro"></a>5.3.4. <code class="filename">meta/conf/distro/</code></h3></div></div></div><p>
1862 Any distribution-specific configuration is controlled from this directory.
1863 For the Yocto Project, the <code class="filename">defaultsetup.conf</code> is the main file here.
1864 This directory includes the versions and the
1865 <code class="filename">SRCDATE</code> definitions for applications that are configured here.
1866 An example of an alternative configuration might be <code class="filename">poky-bleeding.conf</code>.
1867 Although this file mainly inherits its configuration from Poky.
1868 </p></div><div class="section" title="5.3.5. meta/recipes-bsp/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-bsp"></a>5.3.5. <code class="filename">meta/recipes-bsp/</code></h3></div></div></div><p>
1869 This directory contains anything linking to specific hardware or hardware
1870 configuration information such as "u-boot" and "grub".
1871 </p></div><div class="section" title="5.3.6. meta/recipes-connectivity/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-connectivity"></a>5.3.6. <code class="filename">meta/recipes-connectivity/</code></h3></div></div></div><p>
1872 This directory contains libraries and applications related to communication with other devices.
1873 </p></div><div class="section" title="5.3.7. meta/recipes-core/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-core"></a>5.3.7. <code class="filename">meta/recipes-core/</code></h3></div></div></div><p>
1874 This directory contains what is needed to build a basic working Linux image
1875 including commonly used dependencies.
1876 </p></div><div class="section" title="5.3.8. meta/recipes-devtools/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-devtools"></a>5.3.8. <code class="filename">meta/recipes-devtools/</code></h3></div></div></div><p>
1877 This directory contains tools that are primarily used by the build system.
1878 The tools, however, can also be used on targets.
1879 </p></div><div class="section" title="5.3.9. meta/recipes-extended/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-extended"></a>5.3.9. <code class="filename">meta/recipes-extended/</code></h3></div></div></div><p>
1880 This directory contains non-essential applications that add features compared to the
1881 alternatives in core.
1882 You might need this directory for full tool functionality or for Linux Standard Base (LSB)
1883 compliance.
1884 </p></div><div class="section" title="5.3.10. meta/recipes-gnome/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-gnome"></a>5.3.10. <code class="filename">meta/recipes-gnome/</code></h3></div></div></div><p>
1885 This directory contains all things related to the GTK+ application framework.
1886 </p></div><div class="section" title="5.3.11. meta/recipes-graphics/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-graphics"></a>5.3.11. <code class="filename">meta/recipes-graphics/</code></h3></div></div></div><p>
1887 This directory contains X and other graphically related system libraries
1888 </p></div><div class="section" title="5.3.12. meta/recipes-kernel/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-kernel"></a>5.3.12. <code class="filename">meta/recipes-kernel/</code></h3></div></div></div><p>
1889 This directory contains the kernel and generic applications and libraries that
1890 have strong kernel dependencies.
1891 </p></div><div class="section" title="5.3.13. meta/recipes-multimedia/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-multimedia"></a>5.3.13. <code class="filename">meta/recipes-multimedia/</code></h3></div></div></div><p>
1892 This directory contains codecs and support utilities for audio, images and video.
1893 </p></div><div class="section" title="5.3.14. meta/recipes-qt/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-qt"></a>5.3.14. <code class="filename">meta/recipes-qt/</code></h3></div></div></div><p>
1894 This directory contains all things related to the Qt application framework.
1895 </p></div><div class="section" title="5.3.15. meta/recipes-rt/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-rt"></a>5.3.15. <code class="filename">meta/recipes-rt/</code></h3></div></div></div><p>
1896 This directory contains package and image recipes for using and testing
1897 the <code class="filename">PREEMPT_RT</code> kernel.
1898 </p></div><div class="section" title="5.3.16. meta/recipes-sato/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-sato"></a>5.3.16. <code class="filename">meta/recipes-sato/</code></h3></div></div></div><p>
1899 This directory contains the Sato demo/reference UI/UX and its associated applications
1900 and configuration data.
1901 </p></div><div class="section" title="5.3.17. meta/recipes-support/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-support"></a>5.3.17. <code class="filename">meta/recipes-support/</code></h3></div></div></div><p>
1902 This directory contains recipes that used by other recipes, but that are not directly
1903 included in images (i.e. dependencies of other recipes).
1904 </p></div><div class="section" title="5.3.18. meta/site/"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-site"></a>5.3.18. <code class="filename">meta/site/</code></h3></div></div></div><p>
1905 This directory contains a list of cached results for various architectures.
1906 Because certain "autoconf" test results cannot be determined when cross-compiling due to
1907 the tests not able to run on a live system, the information in this directory is
1908 passed to "autoconf" for the various architectures.
1909 </p></div><div class="section" title="5.3.19. meta/recipes.txt"><div class="titlepage"><div><div><h3 class="title"><a id="structure-meta-recipes-txt"></a>5.3.19. <code class="filename">meta/recipes.txt</code></h3></div></div></div><p>
1910 This file is a description of the contents of <code class="filename">recipes-*</code>.
1911 </p></div></div></div>
1912
1913 <div class="chapter" title="Chapter 6. BitBake"><div class="titlepage"><div><div><h2 class="title"><a id="ref-bitbake"></a>Chapter 6. BitBake</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#ref-bitbake-parsing">6.1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">6.2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">6.3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">6.4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">6.5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">6.6. BitBake Command Line</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">6.7. Fetchers</a></span></dt></dl></div><p>
1914 BitBake is a program written in Python that interprets the metadata used by the OpenEmbedded
1915 build system.
1916 At some point, developers wonder what actually happens when you enter:
1917 </p><pre class="literallayout">
1918 $ bitbake core-image-sato
1919 </pre><p>
1920 </p><p>
1921 This chapter provides an overview of what happens behind the scenes from BitBake's perspective.
1922 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
1923 BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships.
1924 As such, it has no real knowledge of what the tasks being executed actually do.
1925 BitBake just considers a list of tasks with dependencies and handles metadata
1926 that consists of variables in a certain format that get passed to the tasks.
1927 </div><div class="section" title="6.1. Parsing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-parsing"></a>6.1. Parsing</h2></div></div></div><p>
1928 BitBake parses configuration files, classes, and <code class="filename">.bb</code> files.
1929 </p><p>
1930 The first thing BitBake does is look for the <code class="filename">bitbake.conf</code> file.
1931 This file resides in the
1932 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>
1933 within the <code class="filename">meta/conf/</code> directory.
1934 BitBake finds it by examining its
1935 <a class="link" href="#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a> environment
1936 variable and looking for the <code class="filename">meta/conf/</code>
1937 directory.
1938 </p><p>
1939 The <code class="filename">bitbake.conf</code> file lists other configuration
1940 files to include from a <code class="filename">conf/</code>
1941 directory below the directories listed in <code class="filename">BBPATH</code>.
1942 In general, the most important configuration file from a user's perspective
1943 is <code class="filename">local.conf</code>, which contains a user's customized
1944 settings for the OpenEmbedded build environment.
1945 Other notable configuration files are the distribution
1946 configuration file (set by the
1947 <code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code> variable)
1948 and the machine configuration file
1949 (set by the
1950 <code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code> variable).
1951 The <code class="filename">DISTRO</code> and <code class="filename">MACHINE</code> BitBake environment
1952 variables are both usually set in
1953 the <code class="filename">local.conf</code> file.
1954 Valid distribution
1955 configuration files are available in the <code class="filename">meta/conf/distro/</code> directory
1956 and valid machine configuration
1957 files in the <code class="filename">meta/conf/machine/</code> directory.
1958 Within the <code class="filename">meta/conf/machine/include/</code>
1959 directory are various <code class="filename">tune-*.inc</code> configuration files that provide common
1960 "tuning" settings specific to and shared between particular architectures and machines.
1961 </p><p>
1962 After the parsing of the configuration files, some standard classes are included.
1963 The <code class="filename">base.bbclass</code> file is always included.
1964 Other classes that are specified in the configuration using the
1965 <code class="filename"><a class="link" href="#var-INHERIT" title="INHERIT">INHERIT</a></code>
1966 variable are also included.
1967 Class files are searched for in a <code class="filename">classes</code> subdirectory
1968 under the paths in <code class="filename">BBPATH</code> in the same way as
1969 configuration files.
1970 </p><p>
1971 After classes are included, the variable
1972 <code class="filename"><a class="link" href="#var-BBFILES" title="BBFILES">BBFILES</a></code>
1973 is set, usually in
1974 <code class="filename">local.conf</code>, and defines the list of places to search for
1975 <code class="filename">.bb</code> files.
1976 By default, the <code class="filename">BBFILES</code> variable specifies the
1977 <code class="filename">meta/recipes-*/</code> directory within Poky.
1978 Adding extra content to <code class="filename">BBFILES</code> is best achieved through the use of
1979 BitBake layers as described in the
1980 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#understanding-and-creating-layers" target="_top">Understanding and
1981 Creating Layers</a>" section of the Yocto Project Development Manual.
1982 </p><p>
1983 BitBake parses each <code class="filename">.bb</code> file in <code class="filename">BBFILES</code> and
1984 stores the values of various variables.
1985 In summary, for each <code class="filename">.bb</code>
1986 file the configuration plus the base class of variables are set, followed
1987 by the data in the <code class="filename">.bb</code> file
1988 itself, followed by any inherit commands that
1989 <code class="filename">.bb</code> file might contain.
1990 </p><p>
1991 Because parsing <code class="filename">.bb</code> files is a time
1992 consuming process, a cache is kept to speed up subsequent parsing.
1993 This cache is invalid if the timestamp of the <code class="filename">.bb</code>
1994 file itself changes, or if the timestamps of any of the include,
1995 configuration or class files the <code class="filename">.bb</code>
1996 file depends on changes.
1997 </p></div><div class="section" title="6.2. Preferences and Providers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-providers"></a>6.2. Preferences and Providers</h2></div></div></div><p>
1998 Once all the <code class="filename">.bb</code> files have been
1999 parsed, BitBake starts to build the target (<code class="filename">core-image-sato</code>
2000 in the previous section's example) and looks for providers of that target.
2001 Once a provider is selected, BitBake resolves all the dependencies for
2002 the target.
2003 In the case of <code class="filename">core-image-sato</code>, it would lead to
2004 <code class="filename">packagegroup-core-x11-sato</code>,
2005 which in turn leads to recipes like <code class="filename">matchbox-terminal</code>,
2006 <code class="filename">pcmanfm</code> and <code class="filename">gthumb</code>.
2007 These recipes in turn depend on <code class="filename">eglibc</code> and the toolchain.
2008 </p><p>
2009 Sometimes a target might have multiple providers.
2010 A common example is "virtual/kernel", which is provided by each kernel package.
2011 Each machine often selects the best kernel provider by using a line similar to the
2012 following in the machine configuration file:
2013 </p><pre class="literallayout">
2014 PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
2015 </pre><p>
2016 The default <code class="filename"><a class="link" href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">PREFERRED_PROVIDER</a></code>
2017 is the provider with the same name as the target.
2018 </p><p>
2019 Understanding how providers are chosen is made complicated by the fact
2020 that multiple versions might exist.
2021 BitBake defaults to the highest version of a provider.
2022 Version comparisons are made using the same method as Debian.
2023 You can use the
2024 <code class="filename"><a class="link" href="#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></code>
2025 variable to specify a particular version (usually in the distro configuration).
2026 You can influence the order by using the
2027 <code class="filename"><a class="link" href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></code>
2028 variable.
2029 By default, files have a preference of "0".
2030 Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "-1" makes the
2031 package unlikely to be used unless it is explicitly referenced.
2032 Setting the <code class="filename">DEFAULT_PREFERENCE</code> to "1" makes it likely the package is used.
2033 <code class="filename">PREFERRED_VERSION</code> overrides any <code class="filename">DEFAULT_PREFERENCE</code> setting.
2034 <code class="filename">DEFAULT_PREFERENCE</code> is often used to mark newer and more experimental package
2035 versions until they have undergone sufficient testing to be considered stable.
2036 </p><p>
2037 In summary, BitBake has created a list of providers, which is prioritized, for each target.
2038 </p></div><div class="section" title="6.3. Dependencies"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-dependencies"></a>6.3. Dependencies</h2></div></div></div><p>
2039 Each target BitBake builds consists of multiple tasks such as
2040 <code class="filename">fetch</code>, <code class="filename">unpack</code>,
2041 <code class="filename">patch</code>, <code class="filename">configure</code>,
2042 and <code class="filename">compile</code>.
2043 For best performance on multi-core systems, BitBake considers each task as an independent
2044 entity with its own set of dependencies.
2045 </p><p>
2046 Dependencies are defined through several variables.
2047 You can find information about variables BitBake uses in the BitBake documentation,
2048 which is found in the <code class="filename">bitbake/doc/manual</code> directory within the
2049 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
2050 At a basic level, it is sufficient to know that BitBake uses the
2051 <code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></code> and
2052 <code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variables when
2053 calculating dependencies.
2054 </p></div><div class="section" title="6.4. The Task List"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-tasklist"></a>6.4. The Task List</h2></div></div></div><p>
2055 Based on the generated list of providers and the dependency information,
2056 BitBake can now calculate exactly what tasks it needs to run and in what
2057 order it needs to run them.
2058 The build now starts with BitBake forking off threads up to the limit set in the
2059 <code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a></code> variable.
2060 BitBake continues to fork threads as long as there are tasks ready to run,
2061 those tasks have all their dependencies met, and the thread threshold has not been
2062 exceeded.
2063 </p><p>
2064 It is worth noting that you can greatly speed up the build time by properly setting
2065 the <code class="filename">BB_NUMBER_THREADS</code> variable.
2066 See the
2067 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/yocto-project-qs/yocto-project-qs.html#building-image" target="_top">Building an Image</a>"
2068 section in the Yocto Project Quick Start for more information.
2069 </p><p>
2070 As each task completes, a timestamp is written to the directory specified by the
2071 <code class="filename"><a class="link" href="#var-STAMP" title="STAMP">STAMP</a></code> variable.
2072 On subsequent runs, BitBake looks within the <code class="filename">/build/tmp/stamps</code>
2073 directory and does not rerun
2074 tasks that are already completed unless a timestamp is found to be invalid.
2075 Currently, invalid timestamps are only considered on a per
2076 <code class="filename">.bb</code> file basis.
2077 So, for example, if the configure stamp has a timestamp greater than the
2078 compile timestamp for a given target, then the compile task would rerun.
2079 Running the compile task again, however, has no effect on other providers
2080 that depend on that target.
2081 This behavior could change or become configurable in future versions of BitBake.
2082 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2083 Some tasks are marked as "nostamp" tasks.
2084 No timestamp file is created when these tasks are run.
2085 Consequently, "nostamp" tasks are always rerun.
2086 </div></div><div class="section" title="6.5. Running a Task"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-runtask"></a>6.5. Running a Task</h2></div></div></div><p>
2087 Tasks can either be a shell task or a Python task.
2088 For shell tasks, BitBake writes a shell script to
2089 <code class="filename">${WORKDIR}/temp/run.do_taskname.pid</code> and then executes the script.
2090 The generated shell script contains all the exported variables, and the shell functions
2091 with all variables expanded.
2092 Output from the shell script goes to the file <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>.
2093 Looking at the expanded shell functions in the run file and the output in the log files
2094 is a useful debugging technique.
2095 </p><p>
2096 For Python tasks, BitBake executes the task internally and logs information to the
2097 controlling terminal.
2098 Future versions of BitBake will write the functions to files similar to the way
2099 shell tasks are handled.
2100 Logging will be handled in way similar to shell tasks as well.
2101 </p><p>
2102 Once all the tasks have been completed BitBake exits.
2103 </p><p>
2104 When running a task, BitBake tightly controls the execution environment
2105 of the build tasks to make sure unwanted contamination from the build machine
2106 cannot influence the build.
2107 Consequently, if you do want something to get passed into the build
2108 task's environment, you must take a few steps:
2109 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Tell BitBake to load what you want from the environment
2110 into the data store.
2111 You can do so through the <code class="filename">BB_ENV_EXTRAWHITE</code>
2112 variable.
2113 For example, assume you want to prevent the build system from
2114 accessing your <code class="filename">$HOME/.ccache</code> directory.
2115 The following command tells BitBake to load
2116 <code class="filename">CCACHE_DIR</code> from the environment into the data
2117 store:
2118 </p><pre class="literallayout">
2119 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
2120 </pre></li><li class="listitem"><p>Tell BitBake to export what you have loaded into the
2121 environment store to the task environment of every running task.
2122 Loading something from the environment into the data store
2123 (previous step) only makes it available in the datastore.
2124 To export it to the task environment of every running task,
2125 use a command similar to the following in your
2126 <code class="filename">local.conf</code> or distro configuration file:
2127 </p><pre class="literallayout">
2128 export CCACHE_DIR
2129 </pre></li></ol></div><p>
2130 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2131 A side effect of the previous steps is that BitBake records the variable
2132 as a dependency of the build process in things like the shared state
2133 checksums.
2134 If doing so results in unnecessary rebuilds of tasks, you can whitelist the
2135 variable so that the shared state code ignores the dependency when it creates
2136 checksums.
2137 For information on this process, see the <code class="filename">BB_HASHBASE_WHITELIST</code>
2138 example in the "<a class="link" href="#checksums" title="3.2.2. Checksums (Signatures)">Checksums (Signatures)</a>" section.
2139 </div></div><div class="section" title="6.6. BitBake Command Line"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-commandline"></a>6.6. BitBake Command Line</h2></div></div></div><p>
2140 Following is the BitBake help output:
2141 </p><pre class="screen">
2142$ bitbake --help
2143Usage: bitbake [options] [package ...]
2144
2145Executes the specified task (default is 'build') for a given set of BitBake files.
2146It expects that BBFILES is defined, which is a space separated list of files to
2147be executed. BBFILES does support wildcards.
2148Default BBFILES are the .bb files in the current directory.
2149
2150Options:
2151 --version show program's version number and exit
2152 -h, --help show this help message and exit
2153 -b BUILDFILE, --buildfile=BUILDFILE
2154 execute the task against this .bb file, rather than a
2155 package from BBFILES. Does not handle any
2156 dependencies.
2157 -k, --continue continue as much as possible after an error. While the
2158 target that failed, and those that depend on it,
2159 cannot be remade, the other dependencies of these
2160 targets can be processed all the same.
2161 -a, --tryaltconfigs continue with builds by trying to use alternative
2162 providers where possible.
2163 -f, --force force run of specified cmd, regardless of stamp status
2164 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes
2165 the specified task for the providee and the packages
2166 it depends on, i.e. 'compile' does not implicitly call
2167 stage for the dependencies (IOW: use only if you know
2168 what you are doing). Depending on the base.bbclass a
2169 listtasks tasks is defined and will show available
2170 tasks
2171 -r PREFILE, --read=PREFILE
2172 read the specified file before bitbake.conf
2173 -R POSTFILE, --postread=POSTFILE
2174 read the specified file after bitbake.conf
2175 -v, --verbose output more chit-chat to the terminal
2176 -D, --debug Increase the debug level. You can specify this more
2177 than once.
2178 -n, --dry-run don't execute, just go through the motions
2179 -S, --dump-signatures
2180 don't execute, just dump out the signature
2181 construction information
2182 -p, --parse-only quit after parsing the BB files (developers only)
2183 -s, --show-versions show current and preferred versions of all packages
2184 -e, --environment show the global or per-package environment (this is
2185 what used to be bbread)
2186 -g, --graphviz emit the dependency trees of the specified packages in
2187 the dot syntax
2188 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
2189 Assume these dependencies don't exist and are already
2190 provided (equivalent to ASSUME_PROVIDED). Useful to
2191 make dependency graphs more appealing
2192 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
2193 Show debug logging for the specified logging domains
2194 -P, --profile profile the command and print a report
2195 -u UI, --ui=UI userinterface to use
2196 -t SERVERTYPE, --servertype=SERVERTYPE
2197 Choose which server to use, none, process or xmlrpc
2198 --revisions-changed Set the exit code depending on whether upstream
2199 floating revisions have changed or not
2200 </pre></div><div class="section" title="6.7. Fetchers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-bitbake-fetchers"></a>6.7. Fetchers</h2></div></div></div><p>
2201 BitBake also contains a set of "fetcher" modules that allow
2202 retrieval of source code from various types of sources.
2203 For example, BitBake can get source code from a disk with the metadata, from websites,
2204 from remote shell accounts or from Source Code Management (SCM) systems
2205 like <code class="filename">cvs/subversion/git</code>.
2206 </p><p>
2207 Fetchers are usually triggered by entries in
2208 <code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code>.
2209 You can find information about the options and formats of entries for specific
2210 fetchers in the BitBake manual located in the
2211 <code class="filename">bitbake/doc/manual</code> directory of the
2212 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
2213 </p><p>
2214 One useful feature for certain Source Code Manager (SCM) fetchers is the ability to
2215 "auto-update" when the upstream SCM changes version.
2216 Since this ability requires certain functionality from the SCM, not all
2217 systems support it.
2218 Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update".
2219 This feature works using the <code class="filename"><a class="link" href="#var-SRCREV" title="SRCREV">SRCREV</a></code>
2220 variable.
2221 See the
2222 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#platdev-appdev-srcrev" target="_top">Using an External SCM</a>" section
2223 in the Yocto Project Development Manual for more information.
2224 </p></div></div>
2225
2226 <div class="chapter" title="Chapter 7. Classes"><div class="titlepage"><div><div><h2 class="title"><a id="ref-classes"></a>Chapter 7. Classes</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#ref-classes-base">7.1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">7.6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">7.9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">7.10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">7.11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-packagegroup">7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">7.13. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">7.14. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-useradd">7.19. Adding Users - <code class="filename">useradd.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-externalsrc">7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">7.21. Other Classes</a></span></dt></dl></div><p>
2227 Class files are used to abstract common functionality and share it amongst multiple
2228 <code class="filename">.bb</code> files.
2229 Any metadata usually found in a <code class="filename">.bb</code> file can also be placed in a class
2230 file.
2231 Class files are identified by the extension <code class="filename">.bbclass</code> and are usually placed
2232 in a <code class="filename">classes/</code> directory beneath the
2233 <code class="filename">meta*/</code> directory found in the
2234 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
2235 Class files can also be pointed to by BUILDDIR (e.g. <code class="filename">build/</code>)in the same way as
2236 <code class="filename">.conf</code> files in the <code class="filename">conf</code> directory.
2237 Class files are searched for in <a class="link" href="#var-BBPATH" title="BBPATH"><code class="filename">BBPATH</code></a>
2238 using the same method by which <code class="filename">.conf</code> files are searched.
2239</p><p>
2240 In most cases inheriting the class is enough to enable its features, although
2241 for some classes you might need to set variables or override some of the
2242 default behaviour.
2243</p><div class="section" title="7.1. The base class - base.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-base"></a>7.1. The base class - <code class="filename">base.bbclass</code></h2></div></div></div><p>
2244 The base class is special in that every <code class="filename">.bb</code>
2245 file inherits it automatically.
2246 This class contains definitions for standard basic
2247 tasks such as fetching, unpacking, configuring (empty by default), compiling
2248 (runs any <code class="filename">Makefile</code> present), installing (empty by default) and packaging
2249 (empty by default).
2250 These classes are often overridden or extended by other classes
2251 such as <code class="filename">autotools.bbclass</code> or <code class="filename">package.bbclass</code>.
2252 The class also contains some commonly used functions such as <code class="filename">oe_runmake</code>.
2253 </p></div><div class="section" title="7.2. Autotooled Packages - autotools.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-autotools"></a>7.2. Autotooled Packages - <code class="filename">autotools.bbclass</code></h2></div></div></div><p>
2254 Autotools (<code class="filename">autoconf</code>, <code class="filename">automake</code>,
2255 and <code class="filename">libtool</code>) bring standardization.
2256 This class defines a set of tasks (configure, compile etc.) that
2257 work for all Autotooled packages.
2258 It should usually be enough to define a few standard variables
2259 and then simply <code class="filename">inherit autotools</code>.
2260 This class can also work with software that emulates Autotools.
2261 For more information, see the
2262 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#usingpoky-extend-addpkg-autotools" target="_top">Autotooled Package</a>"
2263 section in the Yocto Project Development Manual.
2264 </p><p>
2265 It's useful to have some idea of how the tasks defined by this class work
2266 and what they do behind the scenes.
2267 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">do_configure</code> †regenerates the
2268 configure script (using <code class="filename">autoreconf</code>) and then launches it
2269 with a standard set of arguments used during cross-compilation.
2270 You can pass additional parameters to <code class="filename">configure</code> through the
2271 <code class="filename"><a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></code> variable.
2272 </p></li><li class="listitem"><p><code class="filename">do_compile</code> †runs <code class="filename">make</code> with
2273 arguments that specify the compiler and linker.
2274 You can pass additional arguments through
2275 the <code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></code> variable.
2276 </p></li><li class="listitem"><p><code class="filename">do_install</code> †runs <code class="filename">make install</code>
2277 and passes a DESTDIR option, which takes its value from the standard
2278 <code class="filename"><a class="link" href="#var-DESTDIR" title="DESTDIR">DESTDIR</a></code> variable.
2279 </p></li></ul></div><p>
2280 </p></div><div class="section" title="7.3. Alternatives - update-alternatives.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-update-alternatives"></a>7.3. Alternatives - <code class="filename">update-alternatives.bbclass</code></h2></div></div></div><p>
2281 Several programs can fulfill the same or similar function and be installed with the same name.
2282 For example, the <code class="filename">ar</code> command is available from the
2283 <code class="filename">busybox</code>, <code class="filename">binutils</code> and
2284 <code class="filename">elfutils</code> packages.
2285 The <code class="filename">update-alternatives.bbclass</code> class handles renaming the
2286 binaries so that multiple packages can be installed without conflicts.
2287 The <code class="filename">ar</code> command still works regardless of which packages are installed
2288 or subsequently removed.
2289 The class renames the conflicting binary in each package and symlinks the highest
2290 priority binary during installation or removal of packages.
2291 </p><p>
2292 Four variables control this class:
2293 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">ALTERNATIVE_NAME</code> †The name of the
2294 binary that is replaced (<code class="filename">ar</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_LINK</code> †The path to
2295 the resulting binary (<code class="filename">/bin/ar</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_PATH</code> †The path to the
2296 real binary (<code class="filename">/usr/bin/ar.binutils</code> in this example).</p></li><li class="listitem"><p><code class="filename">ALTERNATIVE_PRIORITY</code> †The priority of
2297 the binary.
2298 The version with the most features should have the highest priority.</p></li></ul></div><p>
2299 </p><p>
2300 Currently, the OpenEmbedded build system supports only one binary per package.
2301 </p></div><div class="section" title="7.4. Initscripts - update-rc.d.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-update-rc.d"></a>7.4. Initscripts - <code class="filename">update-rc.d.bbclass</code></h2></div></div></div><p>
2302 This class uses <code class="filename">update-rc.d</code> to safely install an
2303 initialization script on behalf of the package.
2304 The OpenEmbedded build system takes care of details such as making sure the script is stopped before
2305 a package is removed and started when the package is installed.
2306 Three variables control this class:
2307 <code class="filename"><a class="link" href="#var-INITSCRIPT_PACKAGES" title="INITSCRIPT_PACKAGES">INITSCRIPT_PACKAGES</a></code>,
2308 <code class="filename"><a class="link" href="#var-INITSCRIPT_NAME" title="INITSCRIPT_NAME">INITSCRIPT_NAME</a></code> and
2309 <code class="filename"><a class="link" href="#var-INITSCRIPT_PARAMS" title="INITSCRIPT_PARAMS">INITSCRIPT_PARAMS</a></code>.
2310 See the variable links for details.
2311 </p></div><div class="section" title="7.5. Binary config scripts - binconfig.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-binconfig"></a>7.5. Binary config scripts - <code class="filename">binconfig.bbclass</code></h2></div></div></div><p>
2312 Before <code class="filename">pkg-config</code> had become widespread, libraries shipped shell
2313 scripts to give information about the libraries and include paths needed
2314 to build software (usually named <code class="filename">LIBNAME-config</code>).
2315 This class assists any recipe using such scripts.
2316 </p><p>
2317 During staging, BitBake installs such scripts into the
2318 <code class="filename">sysroots/</code> directory.
2319 BitBake also changes all paths to point into the <code class="filename">sysroots/</code>
2320 directory so all builds that use the script will use the correct
2321 directories for the cross compiling layout.
2322 </p></div><div class="section" title="7.6. Debian renaming - debian.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-debian"></a>7.6. Debian renaming - <code class="filename">debian.bbclass</code></h2></div></div></div><p>
2323 This class renames packages so that they follow the Debian naming
2324 policy (i.e. <code class="filename">eglibc</code> becomes <code class="filename">libc6</code>
2325 and <code class="filename">eglibc-devel</code> becomes <code class="filename">libc6-dev</code>.
2326 </p></div><div class="section" title="7.7. Pkg-config - pkgconfig.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-pkgconfig"></a>7.7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></h2></div></div></div><p>
2327 <code class="filename">pkg-config</code> brought standardization and this class aims to make its
2328 integration smooth for all libraries that make use of it.
2329 </p><p>
2330 During staging, BitBake installs <code class="filename">pkg-config</code> data into the
2331 <code class="filename">sysroots/</code> directory.
2332 By making use of sysroot functionality within <code class="filename">pkg-config</code>,
2333 this class no longer has to manipulate the files.
2334 </p></div><div class="section" title="7.8. Distribution of sources - src_distribute_local.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-src-distribute"></a>7.8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></h2></div></div></div><p>
2335 Many software licenses require that source files be provided along with the binaries.
2336 To simplify this process, two classes were created:
2337 <code class="filename">src_distribute.bbclass</code> and
2338 <code class="filename">src_distribute_local.bbclass</code>.
2339 </p><p>
2340 The results of these classes are <code class="filename">tmp/deploy/source/</code>
2341 subdirs with sources sorted by
2342 <code class="filename"><a class="link" href="#var-LICENSE" title="LICENSE">LICENSE</a></code> field.
2343 If recipes list few licenses (or have entries like "Bitstream Vera"),
2344 the source archive is placed in each license directory.
2345 </p><p>
2346 This class operates using three modes:
2347 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>copy:</em></span> Copies the files to the
2348 distribute directory.</p></li><li class="listitem"><p><span class="emphasis"><em>symlink:</em></span> Symlinks the files to the
2349 distribute directory.</p></li><li class="listitem"><p><span class="emphasis"><em>move+symlink:</em></span> Moves the files into
2350 the distribute directory and then symlinks them back.</p></li></ul></div><p>
2351 </p></div><div class="section" title="7.9. Perl modules - cpan.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-perl"></a>7.9. Perl modules - <code class="filename">cpan.bbclass</code></h2></div></div></div><p>
2352 Recipes for Perl modules are simple.
2353 These recipes usually only need to point to the source's archive and then inherit the
2354 proper <code class="filename">.bbclass</code> file.
2355 Building is split into two methods depending on which method the module authors used.
2356 </p><p>
2357 Modules that use old <code class="filename">Makefile.PL</code>-based build system require
2358 <code class="filename">cpan.bbclass</code> in their recipes.
2359 </p><p>
2360 Modules that use <code class="filename">Build.PL</code>-based build system require
2361 using <code class="filename">cpan_build.bbclass</code> in their recipes.
2362 </p></div><div class="section" title="7.10. Python extensions - distutils.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-distutils"></a>7.10. Python extensions - <code class="filename">distutils.bbclass</code></h2></div></div></div><p>
2363 Recipes for Python extensions are simple.
2364 These recipes usually only need to point to the source's archive and then inherit
2365 the proper <code class="filename">.bbclass</code> file.
2366 Building is split into two methods dependling on which method the module authors used.
2367 </p><p>
2368 Extensions that use an Autotools-based build system require Autotools and
2369 <code class="filename">distutils</code>-based <code class="filename">.bbclasse</code> files in their recipes.
2370 </p><p>
2371 Extensions that use <code class="filename">distutils</code>-based build systems require
2372 <code class="filename">distutils.bbclass</code> in their recipes.
2373 </p></div><div class="section" title="7.11. Developer Shell - devshell.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-devshell"></a>7.11. Developer Shell - <code class="filename">devshell.bbclass</code></h2></div></div></div><p>
2374 This class adds the <code class="filename">devshell</code> task.
2375 Distribution policy dictates whether to include this class.
2376 See the
2377 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#platdev-appdev-devshell" target="_top">Using a Development Shell</a>" section
2378 in the Yocto Project Development Manual for more information about using <code class="filename">devshell</code>.
2379 </p></div><div class="section" title="7.12. Package Groups - packagegroup.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-packagegroup"></a>7.12. Package Groups - <code class="filename">packagegroup.bbclass</code></h2></div></div></div><p>
2380 This class sets default values appropriate for package group recipes (such as
2381 <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>,
2382 <code class="filename"><a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></code>,
2383 <code class="filename"><a class="link" href="#var-ALLOW_EMPTY" title="ALLOW_EMPTY">ALLOW_EMPTY</a></code>,
2384 and so forth.
2385 It is highly recommended that all package group recipes inherit this class.
2386 </p><p>
2387 For information on how to use this class, see the
2388 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks" target="_top">Customizing Images Using Custom Package Tasks</a>"
2389 section in the Yocto Project Development Manual.
2390 </p><p>
2391 Previously, this class was named <code class="filename">task.bbclass</code>.
2392 </p></div><div class="section" title="7.13. Packaging - package*.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-package"></a>7.13. Packaging - <code class="filename">package*.bbclass</code></h2></div></div></div><p>
2393 The packaging classes add support for generating packages from a build's
2394 output.
2395 The core generic functionality is in <code class="filename">package.bbclass</code>.
2396 The code specific to particular package types is contained in various sub-classes such as
2397 <code class="filename">package_deb.bbclass</code>, <code class="filename">package_ipk.bbclass</code>,
2398 and <code class="filename">package_rpm.bbclass</code>.
2399 Most users will want one or more of these classes.
2400 </p><p>
2401 You can control the list of resulting package formats by using the
2402 <code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></code>
2403 variable defined in the <code class="filename">local.conf</code> configuration file,
2404 which is located in the <code class="filename">conf</code> folder of the
2405 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
2406 When defining the variable, you can specify one or more package types.
2407 Since images are generated from packages, a packaging class is
2408 needed to enable image generation.
2409 The first class listed in this variable is used for image generation.
2410 </p><p>
2411 The package class you choose can affect build-time performance and has space
2412 ramifications.
2413 In general, building a package with RPM takes about thirty percent more time as
2414 compared to using IPK to build the same or similar package.
2415 This comparison takes into account a complete build of the package with all
2416 dependencies previously built.
2417 The reason for this discrepancy is because the RPM package manager creates and
2418 processes more metadata than the IPK package manager.
2419 Consequently, you might consider setting <code class="filename">PACKAGE_CLASSES</code>
2420 to "package_ipk" if you are building smaller systems.
2421 </p><p>
2422 Keep in mind, however, that RPM starts to provide more abilities than IPK due to
2423 the fact that it processes more metadata.
2424 For example, this information includes individual file types, file checksum generation
2425 and evaluation on install, sparse file support, conflict detection and resolution
2426 for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks.
2427 </p><p>
2428 Another consideration for packages built using the RPM package manager is space.
2429 For smaller systems, the extra space used for the Berkley Database and the amount
2430 of metadata can affect your ability to do on-device upgrades.
2431 </p><p>
2432 You can find additional information on the effects of the package class at these
2433 two Yocto Project mailing list links:
2434 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html" target="_top">
2435 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</a></p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html" target="_top">
2436 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</a></p></li></ul></div><p>
2437 </p></div><div class="section" title="7.14. Building kernels - kernel.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-kernel"></a>7.14. Building kernels - <code class="filename">kernel.bbclass</code></h2></div></div></div><p>
2438 This class handles building Linux kernels.
2439 The class contains code to build all kernel trees.
2440 All needed headers are staged into the
2441 <code class="filename"><a class="link" href="#var-STAGING_KERNEL_DIR" title="STAGING_KERNEL_DIR">STAGING_KERNEL_DIR</a></code>
2442 directory to allow out-of-tree module builds using <code class="filename">module.bbclass</code>.
2443 </p><p>
2444 This means that each built kernel module is packaged separately and inter-module
2445 dependencies are created by parsing the <code class="filename">modinfo</code> output.
2446 If all modules are required, then installing the <code class="filename">kernel-modules</code>
2447 package installs all packages with modules and various other kernel packages
2448 such as <code class="filename">kernel-vmlinux</code>.
2449 </p><p>
2450 Various other classes are used by the kernel and module classes internally including
2451 <code class="filename">kernel-arch.bbclass</code>, <code class="filename">module_strip.bbclass</code>,
2452 <code class="filename">module-base.bbclass</code>, and <code class="filename">linux-kernel-base.bbclass</code>.
2453 </p></div><div class="section" title="7.15. Creating images - image.bbclass and rootfs*.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-image"></a>7.15. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></h2></div></div></div><p>
2454 These classes add support for creating images in several formats.
2455 First, the root filesystem is created from packages using
2456 one of the <code class="filename">rootfs_*.bbclass</code>
2457 files (depending on the package format used) and then the image is created.
2458 </p><p>
2459 The <code class="filename"><a class="link" href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></code>
2460 variable controls the types of images to generate.
2461 </p><p>
2462 The <code class="filename"><a class="link" href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></code>
2463 variable controls the list of packages to install into the image.
2464 </p></div><div class="section" title="7.16. Host System sanity checks - sanity.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-sanity"></a>7.16. Host System sanity checks - <code class="filename">sanity.bbclass</code></h2></div></div></div><p>
2465 This class checks to see if prerequisite software is present so that
2466 users can be notified of potential problems that might affect their build.
2467 The class also performs basic user configuration checks from
2468 the <code class="filename">local.conf</code> configuration file to
2469 prevent common mistakes that cause build failures.
2470 Distribution policy usually determines whether to include this class.
2471 </p></div><div class="section" title="7.17. Generated output quality assurance checks - insane.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-insane"></a>7.17. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></h2></div></div></div><p>
2472 This class adds a step to the package generation process that sanity checks the
2473 packages generated by the OpenEmbedded build system.
2474 A range of checks are performed that check the build's output
2475 for common problems that show up during runtime.
2476 Distribution policy usually dictates whether to include this class.
2477 </p><p>
2478 You can configure the sanity checks so that specific test failures either raise a warning or
2479 an error message.
2480 Typically, failures for new tests generate a warning.
2481 Subsequent failures for the same test would then generate an error message
2482 once the metadata is in a known and good condition.
2483 You use the <code class="filename">WARN_QA</code> variable to specify tests for which you
2484 want to generate a warning message on failure.
2485 You use the <code class="filename">ERROR_QA</code> variable to specify tests for which you
2486 want to generate an error message on failure.
2487 </p><p>
2488 The following list shows the tests you can list with the <code class="filename">WARN_QA</code>
2489 and <code class="filename">ERROR_QA</code> variables:
2490 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">ldflags:</code></em></span>
2491 Ensures that the binaries were linked with the
2492 <code class="filename">LDFLAGS</code> options provided by the build system.
2493 If this test fails, check that the <code class="filename">LDFLAGS</code> variable
2494 is being passed to the linker command.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">useless-rpaths:</code></em></span>
2495 Checks for dynamic library load paths (rpaths) in the binaries that
2496 by default on a standard system are searched by the linker (e.g.
2497 <code class="filename">/lib</code> and <code class="filename">/usr/lib</code>).
2498 While these paths will not cause any breakage, they do waste space and
2499 are unnecessary.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">rpaths:</code></em></span>
2500 Checks for rpaths in the binaries that contain build system paths such
2501 as <code class="filename">TMPDIR</code>.
2502 If this test fails, bad <code class="filename">-rpath</code> options are being
2503 passed to the linker commands and your binaries have potential security
2504 issues.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-so:</code></em></span>
2505 Checks that the <code class="filename">.so</code> symbolic links are in the
2506 <code class="filename">-dev</code> package and not in any of the other packages.
2507 In general, these symlinks are only useful for development purposes.
2508 Thus, the <code class="filename">-dev</code> package is the correct location for
2509 them.
2510 Some very rare cases do exist for dynamically loaded modules where
2511 these symlinks are needed instead in the main package.
2512 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-files:</code></em></span>
2513 Checks for <code class="filename">.debug</code> directories in anything but the
2514 <code class="filename">-dbg</code> package.
2515 The debug files should all be in the <code class="filename">-dbg</code> package.
2516 Thus, anything packaged elsewhere is incorrect packaging.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">arch:</code></em></span>
2517 Checks the Executable and Linkable Format (ELF) type, bit size and endianness
2518 of any binaries to ensure it matches the target architecture.
2519 This test fails if any binaries don't match the type since there would be an
2520 incompatibility.
2521 Sometimes software, like bootloaders, might need to bypass this check.
2522 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">debug-deps:</code></em></span>
2523 Checks that <code class="filename">-dbg</code> packages only depend on other
2524 <code class="filename">-dbg</code> packages and not on any other types of packages,
2525 which would cause a packaging bug.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">dev-deps:</code></em></span>
2526 Checks that <code class="filename">-dev</code> packages only depend on other
2527 <code class="filename">-dev</code> packages and not on any other types of packages,
2528 which would be a packaging bug.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">pkgconfig:</code></em></span>
2529 Checks <code class="filename">.pc</code> files for any
2530 <code class="filename">TMPDIR/WORKDIR</code> paths.
2531 Any <code class="filename">.pc</code> file containing these paths is incorrect
2532 since <code class="filename">pkg-config</code> itself adds the correct sysroot prefix
2533 when the files are accessed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">la:</code></em></span>
2534 Checks <code class="filename">.la</code> files for any <code class="filename">TMPDIR</code>
2535 paths.
2536 Any <code class="filename">.la</code> file continaing these paths is incorrect since
2537 <code class="filename">libtool</code> adds the correct sysroot prefix when using the
2538 files automatically itself.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">desktop:</code></em></span>
2539 Runs the <code class="filename">desktop-file-validate</code> program against any
2540 <code class="filename">.desktop</code> files to validate their contents against
2541 the specification for <code class="filename">.desktop</code> files.</p></li></ul></div><p>
2542 </p></div><div class="section" title="7.18. Autotools configuration data cache - siteinfo.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-siteinfo"></a>7.18. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></h2></div></div></div><p>
2543 Autotools can require tests that must execute on the target hardware.
2544 Since this is not possible in general when cross compiling, site information is
2545 used to provide cached test results so these tests can be skipped over but
2546 still make the correct values available.
2547 The <code class="filename"><a class="link" href="#structure-meta-site" title="5.3.18. meta/site/">meta/site directory</a></code>
2548 contains test results sorted into different categories such as architecture, endianness, and
2549 the <code class="filename">libc</code> used.
2550 Site information provides a list of files containing data relevant to
2551 the current build in the
2552 <code class="filename"><a class="link" href="#var-CONFIG_SITE" title="CONFIG_SITE">CONFIG_SITE</a></code> variable
2553 that Autotools automatically picks up.
2554 </p><p>
2555 The class also provides variables like
2556 <code class="filename"><a class="link" href="#var-SITEINFO_ENDIANNESS" title="SITEINFO_ENDIANNESS">SITEINFO_ENDIANNESS</a></code>
2557 and <code class="filename"><a class="link" href="#var-SITEINFO_BITS" title="SITEINFO_BITS">SITEINFO_BITS</a></code>
2558 that can be used elsewhere in the metadata.
2559 </p><p>
2560 Because this class is included from <code class="filename">base.bbclass</code>, it is always active.
2561 </p></div><div class="section" title="7.19. Adding Users - useradd.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-useradd"></a>7.19. Adding Users - <code class="filename">useradd.bbclass</code></h2></div></div></div><p>
2562 If you have packages that install files that are owned by custom users or groups,
2563 you can use this class to specify those packages and associate the users and groups
2564 with those packages.
2565 The <code class="filename">meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</code>
2566 recipe in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>
2567 provides a simple exmample that shows how to add three
2568 users and groups to two packages.
2569 See the <code class="filename">useradd-example.bb</code> for more information on how to
2570 use this class.
2571 </p></div><div class="section" title="7.20. Using External Source - externalsrc.bbclass"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-externalsrc"></a>7.20. Using External Source - <code class="filename">externalsrc.bbclass</code></h2></div></div></div><p>
2572 You can use this class to build software from source code that is external to the
2573 OpenEmbedded build system.
2574 In other words, your source code resides in an external tree outside of the Yocto Project.
2575 Building software from an external source tree means that the normal fetch, unpack, and
2576 patch process is not used.
2577 </p><p>
2578 To use the class, you need to define the
2579 <a class="link" href="#var-S" title="S"><code class="filename">S</code></a> variable to point to the directory that contains the source files.
2580 You also need to have your recipe inherit the <code class="filename">externalsrc.bbclass</code> class.
2581 </p><p>
2582 This class expects the source code to support recipe builds that use the
2583 <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> variable to point to the directory in
2584 which the OpenEmbedded build system places the generated objects built from the recipes.
2585 By default, the <code class="filename">B</code> directory is set to the following, which is separate from the
2586 Source Directory (<code class="filename">S</code>):
2587 </p><pre class="literallayout">
2588 ${WORKDIR}/${BPN}/{PV}/
2589 </pre><p>
2590 See the glossary entries for the
2591 <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>,
2592 <a class="link" href="#var-BPN" title="BPN"><code class="filename">BPN</code></a>,
2593 <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a>,
2594 <a class="link" href="#var-S" title="S"><code class="filename">S</code></a>, and
2595 <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> for more information.
2596 </p><p>
2597 You can build object files in the external tree by setting the
2598 <code class="filename">B</code> variable equal to <code class="filename">"${S}"</code>.
2599 However, this practice does not work well if you use the source for more than one variant
2600 (i.e., "natives" such as <code class="filename">quilt-native</code>,
2601 or "crosses" such as <code class="filename">gcc-cross</code>).
2602 So, be sure there are no "native", "cross", or "multilib" variants of the recipe.
2603 </p><p>
2604 If you do want to build different variants of a recipe, you can use the
2605 <a class="link" href="#var-BBCLASSEXTEND" title="BBCLASSEXTEND"><code class="filename">BBCLASSEXTEND</code></a> variable.
2606 When you do, the <a class="link" href="#var-B" title="B"><code class="filename">B</code></a> variable must support the
2607 recipe's ability to build variants in different working directories.
2608 Most autotools-based recipes support separating these directories.
2609 The OpenEmbedded build system defaults to using separate directories for <code class="filename">gcc</code>
2610 and some kernel recipes.
2611 Alternatively, you can make sure that separate recipes exist that each
2612 use the <code class="filename">BBCLASSEXTEND</code> variable to build each variant.
2613 The separate recipes can inherit a single target recipe.
2614 </p><p>
2615 For information on how to use this class, see the
2616 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#building-software-from-an-external-source" target="_top">Building
2617 Software from an External Source</a>" section in the Yocto Project Development Manual.
2618 </p></div><div class="section" title="7.21. Other Classes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-classes-others"></a>7.21. Other Classes</h2></div></div></div><p>
2619 Thus far, this chapter has discussed only the most useful and important
2620 classes.
2621 However, other classes exist within the <code class="filename">meta/classes</code> directory
2622 in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
2623 You can examine the <code class="filename">.bbclass</code> files directly for more
2624 information.
2625 </p></div></div>
2626
2627 <div class="chapter" title="Chapter 8. Images"><div class="titlepage"><div><div><h2 class="title"><a id="ref-images"></a>Chapter 8. Images</h2></div></div></div><p>
2628 The OpenEmbedded build process supports several types of images to satisfy different needs.
2629 When you issue the <code class="filename">bitbake</code> command you provide a “top-level†recipe
2630 that essentially begins the build for the type of image you want.
2631 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
2632 Building an image without GNU General Public License Version 3 (GPLv3) components
2633 is only supported for minimal and base images.
2634 Furthermore, if you are going to build an image using non-GPLv3 components,
2635 you must make the following changes in the <code class="filename">local.conf</code> file
2636 before using the BitBake command to build the minimal or base image:
2637 <pre class="literallayout">
2638 1. Comment out the EXTRA_IMAGE_FEATURES line
2639 2. Set INCOMPATIBLE_LICENSE = "GPLv3"
2640 </pre></div><p>
2641 From within the <code class="filename">poky</code> Git repository, use the following command to list
2642 the supported images:
2643 </p><pre class="literallayout">
2644 $ ls meta*/recipes*/images/*.bb
2645 </pre><p>
2646 These recipes reside in the <code class="filename">meta/recipes-core/images</code>,
2647 <code class="filename">meta/recipes-extended/images</code>,
2648 <code class="filename">meta/recipes-graphics/images</code>, and
2649 <code class="filename">meta/recipes-sato/images</code> directories
2650 within the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">source directory</a>.
2651 Although the recipe names are somewhat explanatory, here is a list that describes them:
2652 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-base</code>:</em></span>
2653 A console-only image that fully supports the target device hardware.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal</code>:</em></span>
2654 A small image just capable of allowing a device to boot.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-dev</code>:</em></span>
2655 A <code class="filename">core-image-minimal</code> image suitable for development work
2656 using the host.
2657 The image includes headers and libraries you can use in a host development
2658 environment.
2659 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-initramfs</code>:</em></span>
2660 A <code class="filename">core-image-minimal</code> image that has the Minimal RAM-based
2661 Initial Root Filesystem (<code class="filename">initramfs</code>) as part of the kernel,
2662 which allows the system to find the first “init†program more efficiently.
2663 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-minimal-mtdutils</code>:</em></span>
2664 A <code class="filename">core-image-minimal</code> image that has support
2665 for the Minimal MTD Utilities, which let the user interact with the
2666 MTD subsystem in the kernel to perform operations on flash devices.
2667 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-x11</code>:</em></span>
2668 A very basic X11 image with a terminal.
2669 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-basic</code>:</em></span>
2670 A console-only image with more full-featured Linux system
2671 functionality installed.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb</code>:</em></span>
2672 An image that conforms to the Linux Standard Base (LSB) specification.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-dev</code>:</em></span>
2673 A <code class="filename">core-image-lsb</code> image that is suitable for development work
2674 using the host.
2675 The image includes headers and libraries you can use in a host development
2676 environment.
2677 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-lsb-sdk</code>:</em></span>
2678 A <code class="filename">core-image-lsb</code> that includes everything in meta-toolchain
2679 but also includes development headers and libraries to form a complete standalone SDK.
2680 This image is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-clutter</code>:</em></span>
2681 An image with support for the Open GL-based toolkit Clutter, which enables development of
2682 rich and animated graphical user interfaces.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato</code>:</em></span>
2683 An image with Sato support, a mobile environment and visual style that works well
2684 with mobile devices.
2685 The image supports X11 with a Sato theme and applications such as
2686 a terminal, editor, file manager, media player, and so forth.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-dev</code>:</em></span>
2687 A <code class="filename">core-image-sato</code> image suitable for development
2688 using the host.
2689 The image includes libraries needed to build applications on the device itself,
2690 testing and profiling tools, and debug symbols.
2691 This image was formerly <code class="filename">core-image-sdk</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-sato-sdk</code>:</em></span>
2692 A <code class="filename">core-image-sato</code> image that includes everything in meta-toolchain.
2693 The image also includes development headers and libraries to form a complete standalone SDK
2694 and is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt</code>:</em></span>
2695 A <code class="filename">core-image-minimal</code> image plus a real-time test suite and
2696 tools appropriate for real-time use.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-rt-sdk</code>:</em></span>
2697 A <code class="filename">core-image-rt</code> image that includes everything in
2698 <code class="filename">meta-toolchain</code>.
2699 The image also includes development headers and libraries to form a complete
2700 stand-alone SDK and is suitable for development using the target.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">core-image-gtk-directfb</code>:</em></span>
2701 An image that uses <code class="filename">gtk+</code> over <code class="filename">directfb</code>
2702 instead of X11.
2703 In order to build, this image requires specific distro configuration that enables
2704 <code class="filename">gtk</code> over <code class="filename">directfb</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">build-appliance-image</code>:</em></span>
2705 An image you can boot and run using either the
2706 <a class="ulink" href="http://www.vmware.com/products/player/overview.html" target="_top">VMware Player</a>
2707 or <a class="ulink" href="http://www.vmware.com/products/workstation/overview.html" target="_top">VMware Workstation</a>.
2708 For more information on this image, see the
2709 <a class="ulink" href="http://www.yoctoproject.org/documentation/build-appliance" target="_top">Build Appliance</a> page on
2710 the Yocto Project website.</p></li></ul></div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
2711 From the Yocto Project release 1.1 onwards, <code class="filename">-live</code> and
2712 <code class="filename">-directdisk</code> images have been replaced by a "live"
2713 option in <code class="filename">IMAGE_FSTYPES</code> that will work with any image to produce an
2714 image file that can be
2715 copied directly to a CD or USB device and run as is.
2716 To build a live image, simply add
2717 "live" to <code class="filename">IMAGE_FSTYPES</code> within the <code class="filename">local.conf</code>
2718 file or wherever appropriate and then build the desired image as normal.
2719 </div></div>
2720
2721 <div class="chapter" title="Chapter 9. Reference: Features"><div class="titlepage"><div><div><h2 class="title"><a id="ref-features"></a>Chapter 9. Reference: Features</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#ref-features-distro">9.1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">9.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">9.3. Images</a></span></dt><dt><span class="section"><a href="#ref-features-backfill">9.4. Feature Backfilling</a></span></dt></dl></div><p>
2722 Features provide a mechanism for working out which packages
2723 should be included in the generated images.
2724 Distributions can select which features they want to support through the
2725 <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>
2726 variable, which is set in the <code class="filename">poky.conf</code> distribution configuration file.
2727 Machine features are set in the
2728 <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>
2729 variable, which is set in the machine configuration file and
2730 specifies the hardware features for a given machine.
2731 </p><p>
2732 These two variables combine to work out which kernel modules,
2733 utilities, and other packages to include.
2734 A given distribution can support a selected subset of features so some machine features might not
2735 be included if the distribution itself does not support them.
2736 </p><p>
2737 One method you can use to determine which recipes are checking to see if a
2738 particular feature is contained or not is to <code class="filename">grep</code> through
2739 the metadata for the feature.
2740 Here is an example that discovers the recipes whose build is potentially
2741 changed based on a given feature:
2742 </p><pre class="literallayout">
2743 $ cd $HOME/poky
2744 $ git grep 'contains.*MACHINE_FEATURES.*&lt;feature&gt;'
2745 </pre><p>
2746 </p><p>
2747 This chapter provides a reference of shipped machine and distro features
2748 you can include as part of the image, a reference on image types you can
2749 build, and a reference on feature backfilling.
2750 </p><div class="section" title="9.1. Distro"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-distro"></a>9.1. Distro</h2></div></div></div><p>
2751 The items below are features you can use with
2752 <a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>.
2753 Features do not have a one-to-one correspondence to packages, and they can
2754 go beyond simply controlling the installation of a package or packages.
2755 Sometimes a feature can influence how certain recipes are built.
2756 For example, a feature might determine whether a particular configure option
2757 is specified within <code class="filename">do_configure</code> for a particular
2758 recipe.
2759 </p><p>
2760 This list only represents features as shipped with the Yocto Project metadata:
2761 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> ALSA support will be included (OSS compatibility
2762 kernel modules will be installed if available).</p></li><li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Include bluetooth support (integrated BT only)
2763 </p></li><li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Include tools for supporting for devices with internal
2764 HDD/Microdrive for storing files (instead of Flash only devices)
2765 </p></li><li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Include Irda support
2766 </p></li><li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Include keyboard support (e.g. keymaps will be
2767 loaded during boot).
2768 </p></li><li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Include PCI bus support
2769 </p></li><li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Include PCMCIA/CompactFlash support
2770 </p></li><li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> USB Gadget Device support (for USB
2771 networking/serial/storage)
2772 </p></li><li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> USB Host support (allows to connect external
2773 keyboard, mouse, storage, network etc)
2774 </p></li><li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> WiFi support (integrated only)
2775 </p></li><li class="listitem"><p><span class="emphasis"><em>cramfs:</em></span> CramFS support
2776 </p></li><li class="listitem"><p><span class="emphasis"><em>ipsec:</em></span> IPSec support
2777 </p></li><li class="listitem"><p><span class="emphasis"><em>ipv6:</em></span> IPv6 support
2778 </p></li><li class="listitem"><p><span class="emphasis"><em>nfs:</em></span> NFS client support (for mounting NFS exports on
2779 device)</p></li><li class="listitem"><p><span class="emphasis"><em>ppp:</em></span> PPP dialup support</p></li><li class="listitem"><p><span class="emphasis"><em>smbfs:</em></span> SMB networks client support (for mounting
2780 Samba/Microsoft Windows shares on device)</p></li></ul></div><p>
2781 </p></div><div class="section" title="9.2. Machine"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-machine"></a>9.2. Machine</h2></div></div></div><p>
2782 The items below are features you can use with
2783 <a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a>.
2784 Features do not have a one-to-one correspondence to packages, and they can
2785 go beyond simply controlling the installation of a package or packages.
2786 Sometimes a feature can influence how certain recipes are built.
2787 For example, a feature might determine whether a particular configure option
2788 is specified within <code class="filename">do_configure</code> for a particular
2789 recipe.
2790 </p><p>
2791 This feature list only represents features as shipped with the Yocto Project metadata:
2792 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>acpi:</em></span> Hardware has ACPI (x86/x86_64 only)
2793 </p></li><li class="listitem"><p><span class="emphasis"><em>alsa:</em></span> Hardware has ALSA audio drivers
2794 </p></li><li class="listitem"><p><span class="emphasis"><em>apm:</em></span> Hardware uses APM (or APM emulation)
2795 </p></li><li class="listitem"><p><span class="emphasis"><em>bluetooth:</em></span> Hardware has integrated BT
2796 </p></li><li class="listitem"><p><span class="emphasis"><em>ext2:</em></span> Hardware HDD or Microdrive
2797 </p></li><li class="listitem"><p><span class="emphasis"><em>irda:</em></span> Hardware has Irda support
2798 </p></li><li class="listitem"><p><span class="emphasis"><em>keyboard:</em></span> Hardware has a keyboard
2799 </p></li><li class="listitem"><p><span class="emphasis"><em>pci:</em></span> Hardware has a PCI bus
2800 </p></li><li class="listitem"><p><span class="emphasis"><em>pcmcia:</em></span> Hardware has PCMCIA or CompactFlash sockets
2801 </p></li><li class="listitem"><p><span class="emphasis"><em>screen:</em></span> Hardware has a screen
2802 </p></li><li class="listitem"><p><span class="emphasis"><em>serial:</em></span> Hardware has serial support (usually RS232)
2803 </p></li><li class="listitem"><p><span class="emphasis"><em>touchscreen:</em></span> Hardware has a touchscreen
2804 </p></li><li class="listitem"><p><span class="emphasis"><em>usbgadget:</em></span> Hardware is USB gadget device capable
2805 </p></li><li class="listitem"><p><span class="emphasis"><em>usbhost:</em></span> Hardware is USB Host capable
2806 </p></li><li class="listitem"><p><span class="emphasis"><em>wifi:</em></span> Hardware has integrated WiFi
2807 </p></li></ul></div><p>
2808 </p></div><div class="section" title="9.3. Images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-image"></a>9.3. Images</h2></div></div></div><p>
2809 The contents of images generated by the OpenEmbedded build system can be controlled by the
2810 <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code>
2811 and <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES</a></code>
2812 variables that you typically configure in your image recipes.
2813 Through these variables you can add several different
2814 predefined packages such as development utilities or packages with debug
2815 information needed to investigate application problems or profile applications.
2816 </p><p>
2817 Current list of
2818 <code class="filename">IMAGE_FEATURES</code> contains the following:
2819 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>splash:</em></span> Enables showing a splash screen during boot.
2820 By default, this screen is provided by <code class="filename">psplash</code>, which does
2821 allow customization.
2822 If you prefer to use an alternative splash screen package, you can do so by
2823 setting the <code class="filename">SPLASH</code> variable
2824 to a different package name (or names) within the image recipe or at the distro
2825 configuration level.</p></li><li class="listitem"><p><span class="emphasis"><em>ssh-server-dropbear:</em></span> Installs the Dropbear minimal
2826 SSH server.
2827 </p></li><li class="listitem"><p><span class="emphasis"><em>ssh-server-openssh:</em></span> Installs the OpenSSH SSH server,
2828 which is more full-featured than Dropbear.
2829 Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server
2830 are present in <code class="filename">IMAGE_FEATURES</code>, then OpenSSH will take
2831 precedence and Dropbear will not be installed.</p></li><li class="listitem"><p><span class="emphasis"><em>x11:</em></span> Installs the X server</p></li><li class="listitem"><p><span class="emphasis"><em>x11-base:</em></span> Installs the X server with a
2832 minimal environment.</p></li><li class="listitem"><p><span class="emphasis"><em>x11-sato:</em></span> Installs the OpenedHand Sato environment.
2833 </p></li><li class="listitem"><p><span class="emphasis"><em>tools-sdk:</em></span> Installs a full SDK that runs on the device.
2834 </p></li><li class="listitem"><p><span class="emphasis"><em>tools-debug:</em></span> Installs debugging tools such as
2835 <code class="filename">strace</code> and <code class="filename">gdb</code>.
2836 </p></li><li class="listitem"><p><span class="emphasis"><em>tools-profile:</em></span> Installs profiling tools such as
2837 <code class="filename">oprofile</code>, <code class="filename">exmap</code>, and
2838 <code class="filename">LTTng</code>.</p></li><li class="listitem"><p><span class="emphasis"><em>tools-testapps:</em></span> Installs device testing tools (e.g.
2839 touchscreen debugging).</p></li><li class="listitem"><p><span class="emphasis"><em>nfs-server:</em></span> Installs an NFS server.</p></li><li class="listitem"><p><span class="emphasis"><em>dev-pkgs:</em></span> Installs development packages (headers and
2840 extra library links) for all packages installed in a given image.</p></li><li class="listitem"><p><span class="emphasis"><em>staticdev-pkgs:</em></span> Installs static development
2841 packages (i.e. static libraries containing <code class="filename">*.a</code> files) for all
2842 packages installed in a given image.</p></li><li class="listitem"><p><span class="emphasis"><em>dbg-pkgs:</em></span> Installs debug symbol packages for all packages
2843 installed in a given image.</p></li><li class="listitem"><p><span class="emphasis"><em>doc-pkgs:</em></span> Installs documentation packages for all packages
2844 installed in a given image.</p></li></ul></div><p>
2845 </p></div><div class="section" title="9.4. Feature Backfilling"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-features-backfill"></a>9.4. Feature Backfilling</h2></div></div></div><p>
2846 Sometimes it is necessary in the OpenEmbedded build system to extend
2847 <a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a>
2848 or <a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>
2849 to control functionality that was previously enabled and not able
2850 to be disabled.
2851 For these cases, we need to add an
2852 additional feature item to appear in one of these variables,
2853 but we do not want to force developers who have existing values
2854 of the variables in their configuration to add the new feature
2855 in order to retain the same overall level of functionality.
2856 Thus, the OpenEmbedded build system has a mechanism to
2857 automatically "backfill" these added features into existing
2858 distro or machine configurations.
2859 You can see the list of features for which this is done by
2860 finding the
2861 <a class="link" href="#var-DISTRO_FEATURES_BACKFILL" title="DISTRO_FEATURES_BACKFILL"><code class="filename">DISTRO_FEATURES_BACKFILL</code></a>
2862 and <a class="link" href="#var-MACHINE_FEATURES_BACKFILL" title="MACHINE_FEATURES_BACKFILL"><code class="filename">MACHINE_FEATURES_BACKFILL</code></a>
2863 variables in the <code class="filename">meta/conf/bitbake.conf</code> file.
2864 </p><p>
2865 Because such features are backfilled by default into all
2866 configurations as described in the previous paragraph, developers
2867 who wish to disable the new features need to be able to selectively
2868 prevent the backfilling from occurring.
2869 They can do this by adding the undesired feature or features to the
2870 <a class="link" href="#var-DISTRO_FEATURES_BACKFILL_CONSIDERED" title="DISTRO_FEATURES_BACKFILL_CONSIDERED"><code class="filename">DISTRO_FEATURES_BACKFILL_CONSIDERED</code></a>
2871 or <a class="link" href="#var-MACHINE_FEATURES_BACKFILL_CONSIDERED" title="MACHINE_FEATURES_BACKFILL_CONSIDERED"><code class="filename">MACHINE_FEATURES_BACKFILL_CONSIDERED</code></a>
2872 variables for distro features and machine features respectively.
2873 </p><p>
2874 Here are two examples to help illustrate feature backfilling:
2875 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>The "pulseaudio" distro feature option</em></span>:
2876 Previously, PulseAudio support was enabled within the Qt and
2877 GStreamer frameworks.
2878 Because of this, the feature is backfilled and thus
2879 enabled for all distros through the
2880 <code class="filename">DISTRO_FEATURES_BACKFILL</code>
2881 variable in the <code class="filename">meta/conf/bitbake.conf</code> file.
2882 However, your distro needs to disable the feature.
2883 You can disable the feature without affecting
2884 other existing distro configurations that need PulseAudio support
2885 by adding "pulseaudio" to
2886 <code class="filename">DISTRO_FEATURES_BACKFILL_CONSIDERED</code>
2887 in your distro's <code class="filename">.conf</code> file.
2888 Adding the feature to this variable when it also
2889 exists in the <code class="filename">DISTRO_FEATURES_BACKFILL</code>
2890 variable prevents the build system from adding the feature to
2891 your configuration's <code class="filename">DISTRO_FEATURES</code>, effectively disabling
2892 the feature for that particular distro.</p></li><li class="listitem"><p><span class="emphasis"><em>The "rtc" machine feature option</em></span>:
2893 Previously, real time clock (RTC) support was enabled for all
2894 target devices.
2895 Because of this, the feature is backfilled and thus enabled
2896 for all machines through the <code class="filename">MACHINE_FEATURES_BACKFILL</code>
2897 variable in the <code class="filename">meta/conf/bitbake.conf</code> file.
2898 However, your target device does not have this capability.
2899 You can disable RTC support for your device without
2900 affecting other machines that need RTC support
2901 by adding the feature to your machine's
2902 <code class="filename">MACHINE_FEATURES_BACKFILL_CONSIDERED</code>
2903 list in the machine's <code class="filename">.conf</code> file.
2904 Adding the feature to this variable when it also
2905 exists in the <code class="filename">MACHINE_FEATURES_BACKFILL</code>
2906 variable prevents the build system from adding the feature to
2907 your configuration's <code class="filename">MACHINE_FEATURES</code>, effectively
2908 disabling RTC support for that particular machine.</p></li></ul></div><p>
2909 </p></div></div>
2910
2911 <div class="chapter" title="Chapter 10. Variables Glossary"><div class="titlepage"><div><div><h2 class="title"><a id="ref-variables-glos"></a>Chapter 10. Variables Glossary</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></div><p>
2912 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
2913 of their function and contents.
2914</p><div class="glossary" title="Glossary"><div class="titlepage"><div><div><h2 class="title"><a id="ref-variables-glossary"></a>Glossary</h2></div></div></div><p>
2915 <a class="link" href="#var-ALLOW_EMPTY" title="ALLOW_EMPTY">A</a>
2916 <a class="link" href="#var-B" title="B">B</a>
2917 <a class="link" href="#var-CFLAGS" title="CFLAGS">C</a>
2918 <a class="link" href="#var-D" title="D">D</a>
2919 <a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">E</a>
2920 <a class="link" href="#var-FILES" title="FILES">F</a>
2921
2922 <a class="link" href="#var-HOMEPAGE" title="HOMEPAGE">H</a>
2923 <a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">I</a>
2924
2925 <a class="link" href="#var-KBRANCH" title="KBRANCH">K</a>
2926 <a class="link" href="#var-LAYERDIR" title="LAYERDIR">L</a>
2927 <a class="link" href="#var-MACHINE" title="MACHINE">M</a>
2928
2929 <a class="link" href="#var-OE_TERMINAL" title="OE_TERMINAL">O</a>
2930 <a class="link" href="#var-P" title="P">P</a>
2931
2932 <a class="link" href="#var-RCONFLICTS" title="RCONFLICTS">R</a>
2933 <a class="link" href="#var-S" title="S">S</a>
2934 <a class="link" href="#var-T" title="T">T</a>
2935
2936
2937 <a class="link" href="#var-WORKDIR" title="WORKDIR">W</a>
2938
2939
2940
2941 </p><div class="glossdiv" title="A"><h3 class="title">A</h3><dl><dt><a id="var-ALLOW_EMPTY"></a>ALLOW_EMPTY</dt><dd><p>
2942 Specifies if an output package should still be produced if it is empty.
2943 By default, BitBake does not produce empty packages.
2944 This default behavior can cause issues when there is an
2945 <a class="link" href="#var-RDEPENDS" title="RDEPENDS"><code class="filename">RDEPENDS</code></a> or
2946 some other runtime hard-requirement on the existence of the package.
2947 </p><p>
2948 Like all package-controlling variables, you must always use them in
2949 conjunction with a package name override.
2950 Here is an example:
2951 </p><pre class="literallayout">
2952 ALLOW_EMPTY_${PN} = "1"
2953 </pre><p>
2954 </p></dd><dt><a id="var-AUTHOR"></a>AUTHOR</dt><dd><p>The email address used to contact the original author or authors in
2955 order to send patches, forward bugs, etc.</p></dd><dt><a id="var-AUTOREV"></a>AUTOREV</dt><dd><p>When <code class="filename"><a class="link" href="#var-SRCREV" title="SRCREV">SRCREV</a></code>
2956 is set to the value of this variable, it specifies that the latest
2957 source revision in the repository should be used. Here is an example:
2958 </p><pre class="literallayout">
2959 SRCREV = "${AUTOREV}"
2960 </pre><p>
2961 </p></dd></dl></div><div class="glossdiv" title="B"><h3 class="title">B</h3><dl><dt><a id="var-B"></a>B</dt><dd><p>
2962 The <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
2963 The OpenEmbedded build system places generated objects into the Build Directory
2964 during a recipe's build process.
2965 By default, this directory is the same as the <a class="link" href="#var-S" title="S"><code class="filename">S</code></a>
2966 directory:
2967 </p><pre class="literallayout">
2968 B = ${WORKDIR}/${BPN}/{PV}/
2969 </pre><p>
2970 You can separate the (<code class="filename">S</code>) directory and the directory pointed to
2971 by the <code class="filename">B</code> variable.
2972 Most autotools-based recipes support separating these directories.
2973 The build system defaults to using separate directories for <code class="filename">gcc</code>
2974 and some kernel recipes.
2975 </p></dd><dt><a id="var-BAD_RECOMMENDATIONS"></a>BAD_RECOMMENDATIONS</dt><dd><p>
2976 A list of packages not to install despite being recommended by a recipe.
2977 Support for this variable exists only when using the
2978 <code class="filename">ipk</code> packaging backend.
2979 </p></dd><dt><a id="var-BB_DISKMON_DIRS"></a>BB_DISKMON_DIRS</dt><dd><p>
2980 Monitors disk space and available inodes during the build
2981 and allows you to control the build based on these
2982 parameters.
2983 </p><p>
2984 Disk space monitoring is disabled by default.
2985 To enable monitoring, add the <code class="filename">BB_DISKMON_DIRS</code>
2986 variable to your <code class="filename">conf/local.conf</code> file found in the
2987 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
2988 Use the following form:
2989 </p><pre class="literallayout">
2990 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
2991
2992 where:
2993
2994 &lt;action&gt; is:
2995 ABORT: Immediately abort the build when
2996 a threshold is broken.
2997 STOPTASKS: Stop the build after the currently
2998 executing tasks have finished when
2999 a threshold is broken.
3000 WARN: Issue a warning but continue the
3001 build when a threshold is broken.
3002 Subsequent warnings are issued as
3003 defined by the
3004 <a class="link" href="#var-BB_DISKMON_WARNINTERVAL" title="BB_DISKMON_WARNINTERVAL">BB_DISKMON_WARNINTERVAL</a> variable,
3005 which must be defined in the
3006 conf/local.conf file.
3007
3008 &lt;dir&gt; is:
3009 Any directory you choose. You can specify one or
3010 more directories to monitor by separating the
3011 groupings with a space. If two directories are
3012 on the same device, only the first directory
3013 is monitored.
3014
3015 &lt;threshold&gt; is:
3016 Either the minimum available disk space,
3017 the minimum number of free inodes, or
3018 both. You must specify at least one. To
3019 omit one or the other, simply omit the value.
3020 Specify the threshold using G, M, K for Gbytes,
3021 Mbytes, and Kbytes, respectively. If you do
3022 not specify G, M, or K, Kbytes is assumed by
3023 default. Do not use GB, MB, or KB.
3024 </pre><p>
3025 </p><p>
3026 Here are some examples:
3027 </p><pre class="literallayout">
3028 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
3029 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
3030 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
3031 </pre><p>
3032 The first example works only if you also provide
3033 the <a class="link" href="#var-BB_DISKMON_WARNINTERVAL" title="BB_DISKMON_WARNINTERVAL"><code class="filename">BB_DISKMON_WARNINTERVAL</code></a> variable
3034 in the <code class="filename">conf/local.conf</code>.
3035 This example causes the build system to immediately
3036 abort when either the disk space in <code class="filename">${TMPDIR}</code> drops
3037 below 1 Gbyte or the available free inodes drops below
3038 100 Kbytes.
3039 Because two directories are provided with the variable, the
3040 build system also issue a
3041 warning when the disk space in the
3042 <code class="filename">${SSTATE_DIR}</code> directory drops
3043 below 1 Gbyte or the number of free inodes drops
3044 below 100 Kbytes.
3045 Subsequent warnings are issued during intervals as
3046 defined by the <code class="filename">BB_DISKMON_WARNINTERVAL</code>
3047 variable.
3048 </p><p>
3049 The second example stops the build after all currently
3050 executing tasks complete when the minimum disk space
3051 in the <code class="filename">${TMPDIR}</code> directory drops
3052 below 1 Gbyte.
3053 No disk monitoring occurs for the free inodes in this case.
3054 </p><p>
3055 The final example immediately aborts the build when the
3056 number of free inodes in the <code class="filename">${TMPDIR}</code> directory
3057 drops below 100 Kbytes.
3058 No disk space monitoring for the directory itself occurs
3059 in this case.
3060 </p></dd><dt><a id="var-BB_DISKMON_WARNINTERVAL"></a>BB_DISKMON_WARNINTERVAL</dt><dd><p>
3061 Defines the disk space and free inode warning intervals.
3062 To set these intervals, define the variable in your
3063 <code class="filename">conf/local.conf</code> file in the
3064 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
3065 </p><p>
3066 If you are going to use the
3067 <code class="filename">BB_DISKMON_WARNINTERVAL</code> variable, you must
3068 also use the
3069 <a class="link" href="#var-BB_DISKMON_DIRS" title="BB_DISKMON_DIRS"><code class="filename">BB_DISKMON_DIRS</code></a> variable
3070 and define its action as "WARN".
3071 During the build, subsequent warnings are issued each time
3072 disk space or number of free inodes further reduces by
3073 the respective interval.
3074 </p><p>
3075 If you do not provide a <code class="filename">BB_DISKMON_WARNINTERVAL</code>
3076 variable and you do use <code class="filename">BB_DISKMON_DIRS</code> with
3077 the "WARN" action, the disk monitoring interval defaults to
3078 the following:
3079 </p><pre class="literallayout">
3080 BB_DISKMON_WARNINTERVAL = "50M,5K"
3081 </pre><p>
3082 </p><p>
3083 When specifying the variable in your configuration file,
3084 use the following form:
3085 </p><pre class="literallayout">
3086 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
3087
3088 where:
3089
3090 &lt;disk_space_interval&gt; is:
3091 An interval of memory expressed in either
3092 G, M, or K for Gbytes, Mbytes, or Kbytes,
3093 respectively. You cannot use GB, MB, or KB.
3094
3095 &lt;disk_inode_interval&gt; is:
3096 An interval of free inodes expressed in either
3097 G, M, or K for Gbytes, Mbytes, or Kbytes,
3098 respectively. You cannot use GB, MB, or KB.
3099 </pre><p>
3100 </p><p>
3101 Here is an example:
3102 </p><pre class="literallayout">
3103 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
3104 BB_DISKMON_WARNINTERVAL = "50M,5K"
3105 </pre><p>
3106 These variables cause the OpenEmbedded build system to
3107 issue subsequent warnings each time the available
3108 disk space further reduces by 50 Mbytes or the number
3109 of free inodes further reduces by 5 Kbytes in the
3110 <code class="filename">${SSTATE_DIR}</code> directory.
3111 Subsequent warnings based on the interval occur each time
3112 a respective interval is reached beyond the intial warning
3113 (i.e. 1 Gbytes and 100 Kbytes).
3114 </p></dd><dt><a id="var-BBCLASSEXTEND"></a>BBCLASSEXTEND</dt><dd><p>
3115 Allows you to extend a recipe so that it builds variants of the software.
3116 Common variants for recipes exist such as "natives" like <code class="filename">quilt-native</code>,
3117 which is a copy of quilt built to run on the build system;
3118 "crosses" such as <code class="filename">gcc-cross</code>,
3119 which is a compiler built to run on the build machine but produces binaries
3120 that run on the target <a class="link" href="#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a>;
3121 "nativesdk", which targets the SDK machine instead of <code class="filename">MACHINE</code>;
3122 and "mulitlibs" in the form "<code class="filename">multilib:&lt;multilib_name&gt;</code>".
3123 </p><p>
3124 To build a different variant of the recipe with a minimal amount of code, it usually
3125 is as simple as adding the following to your recipe:
3126 </p><pre class="literallayout">
3127 BBCLASSEXTEND =+ "native nativesdk"
3128 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
3129 </pre><p>
3130 </p></dd><dt><a id="var-BBMASK"></a>BBMASK</dt><dd><p>Prevents BitBake from processing recipes and recipe append files.
3131 You can use the <code class="filename">BBMASK</code> variable to "hide"
3132 these <code class="filename">.bb</code> and <code class="filename">.bbappend</code> files.
3133 BitBake ignores any recipe or recipe append files that match the expression.
3134 It is as if BitBake does not see them at all.
3135 Consequently, matching files are not parsed or otherwise used by
3136 BitBake.</p><p>The value you provide is passed to python's regular expression compiler.
3137 For complete syntax information, see python's documentation at
3138 <a class="ulink" href="http://docs.python.org/release/2.3/lib/re-syntax.html" target="_top">http://docs.python.org/release/2.3/lib/re-syntax.html</a>.
3139 The expression is compared against the full paths to the files.
3140 For example, the following uses a complete regular expression to tell
3141 BitBake to ignore all recipe and recipe append files in the
3142 <code class="filename">.*/meta-ti/recipes-misc/</code> directory:
3143 </p><pre class="literallayout">
3144 BBMASK = ".*/meta-ti/recipes-misc/"
3145 </pre><p>Use the <code class="filename">BBMASK</code> variable from within the
3146 <code class="filename">conf/local.conf</code> file found
3147 in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.</p></dd><dt><a id="var-BB_NUMBER_THREADS"></a>BB_NUMBER_THREADS</dt><dd><p>The maximum number of tasks BitBake should run in parallel at any one time.
3148 If your host development system supports multiple cores a good rule of thumb
3149 is to set this variable to twice the number of cores.</p></dd><dt><a id="var-BBFILE_COLLECTIONS"></a>BBFILE_COLLECTIONS</dt><dd><p>Lists the names of configured layers.
3150 These names are used to find the other <code class="filename">BBFILE_*</code>
3151 variables.
3152 Typically, each layer will append its name to this variable in its
3153 <code class="filename">conf/layer.conf</code> file.
3154 </p></dd><dt><a id="var-BBFILE_PATTERN"></a>BBFILE_PATTERN</dt><dd><p>Variable that expands to match files from <code class="filename">BBFILES</code> in a particular layer.
3155 This variable is used in the <code class="filename">conf/layer.conf</code> file and must
3156 be suffixed with the name of the specific layer (e.g.
3157 <code class="filename">BBFILE_PATTERN_emenlow</code>).</p></dd><dt><a id="var-BBFILE_PRIORITY"></a>BBFILE_PRIORITY</dt><dd><p>Assigns the priority for recipe files in each layer.</p><p>This variable is useful in situations where the same recipe appears in
3158 more than one layer.
3159 Setting this variable allows you to prioritize a
3160 layer against other layers that contain the same recipe - effectively
3161 letting you control the precedence for the multiple layers.
3162 The precedence established through this variable stands regardless of a
3163 recipe's version (<code class="filename">PV</code> variable).
3164 For example, a layer that has a recipe with a higher <code class="filename">PV</code> value but for
3165 which the <code class="filename">BBFILE_PRIORITY</code> is set to have a lower precedence still has a
3166 lower precedence.</p><p>A larger value for the <code class="filename">BBFILE_PRIORITY</code> variable results in a higher
3167 precedence.
3168 For example, the value 6 has a higher precedence than the value 5.
3169 If not specified, the <code class="filename">BBFILE_PRIORITY</code> variable is set based on layer
3170 dependencies (see the
3171 <code class="filename"><a class="link" href="#var-LAYERDEPENDS" title="LAYERDEPENDS">LAYERDEPENDS</a></code> variable for
3172 more information.
3173 The default priority, if unspecified
3174 for a layer with no dependencies, is the lowest defined priority + 1
3175 (or 1 if no priorities are defined).</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
3176 You can use the command <code class="filename">bitbake-layers show_layers</code> to list
3177 all configured layers along with their priorities.
3178 </div></dd><dt><a id="var-BBFILES"></a>BBFILES</dt><dd><p>List of recipe files used by BitBake to build software</p></dd><dt><a id="var-BBPATH"></a>BBPATH</dt><dd><p>Used by BitBake to locate <code class="filename">.bbclass</code> and configuration files.
3179 This variable is analogous to the <code class="filename">PATH</code> variable.</p></dd><dt><a id="var-BBINCLUDELOGS"></a>BBINCLUDELOGS</dt><dd><p>Variable that controls how BitBake displays logs on build failure.</p></dd><dt><a id="var-BBLAYERS"></a>BBLAYERS</dt><dd><p>Lists the layers to enable during the build.
3180 This variable is defined in the <code class="filename">bblayers.conf</code> configuration
3181 file in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
3182 Here is an example:
3183 </p><pre class="literallayout">
3184 BBLAYERS = " \
3185 /home/scottrif/poky/meta \
3186 /home/scottrif/poky/meta-yocto \
3187 /home/scottrif/poky/meta-yocto-bsp \
3188 /home/scottrif/poky/meta-mykernel \
3189 "
3190
3191 BBLAYERS_NON_REMOVABLE ?= " \
3192 /home/scottrif/poky/meta \
3193 /home/scottrif/poky/meta-yocto \
3194 "
3195 </pre><p>
3196 This example enables four layers, one of which is a custom, user-defined layer
3197 named <code class="filename">meta-mykernel</code>.
3198 </p></dd><dt><a id="var-BBLAYERS_NON_REMOVABLE"></a>BBLAYERS_NON_REMOVABLE</dt><dd><p>Lists core layers that cannot be removed from the
3199 <code class="filename">bblayers.conf</code> file.
3200 In order for BitBake to build your image, your
3201 <code class="filename">bblayers.conf</code> file must include the
3202 <code class="filename">meta</code> and <code class="filename">meta-yocto</code>
3203 core layers.
3204 Here is an example that shows these two layers listed in
3205 the <code class="filename">BBLAYERS_NON_REMOVABLE</code> statement:
3206 </p><pre class="literallayout">
3207 BBLAYERS = " \
3208 /home/scottrif/poky/meta \
3209 /home/scottrif/poky/meta-yocto \
3210 /home/scottrif/poky/meta-yocto-bsp \
3211 /home/scottrif/poky/meta-mykernel \
3212 "
3213
3214 BBLAYERS_NON_REMOVABLE ?= " \
3215 /home/scottrif/poky/meta \
3216 /home/scottrif/poky/meta-yocto \
3217 "
3218 </pre><p>
3219 </p></dd><dt><a id="var-BP"></a>BP</dt><dd><p>The base recipe name and version but without any special
3220 recipe name suffix (i.e. <code class="filename">-native</code>, <code class="filename">lib64-</code>,
3221 and so forth).
3222 <code class="filename">BP</code> is comprised of the following:
3223 </p><pre class="literallayout">
3224 ${BPN}-${PV}
3225 </pre></dd><dt><a id="var-BPN"></a>BPN</dt><dd><p>The bare name of the recipe.
3226 This variable is a version of the <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> variable
3227 but removes common suffixes such as "-native" and "-cross" as well
3228 as removes common prefixes such as multilib's "lib64-" and "lib32-".
3229 The exact list of suffixes removed is specified by the
3230 <a class="link" href="#var-SPECIAL_PKGSUFFIX" title="SPECIAL_PKGSUFFIX"><code class="filename">SPECIAL_PKGSUFFIX</code></a> variable.
3231 The exact list of prefixes removed is specified by the
3232 <a class="link" href="#var-MLPREFIX" title="MLPREFIX"><code class="filename">MLPREFIX</code></a> variable.
3233 Prefixes are removed for multilib and nativesdk cases.</p></dd></dl></div><div class="glossdiv" title="C"><h3 class="title">C</h3><dl><dt><a id="var-CFLAGS"></a>CFLAGS</dt><dd><p>
3234 Flags passed to C compiler for the target system.
3235 This variable evaluates to the same as
3236 <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>.
3237 </p></dd><dt><a id="var-COMBINED_FEATURES"></a>COMBINED_FEATURES</dt><dd><p>A set of features common between
3238 <a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES"><code class="filename">MACHINE_FEATURES</code></a>
3239 and <a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES"><code class="filename">DISTRO_FEATURES</code></a>.
3240 See the glossary descriptions for these variables for more information.</p></dd><dt><a id="var-COMPATIBLE_MACHINE"></a>COMPATIBLE_MACHINE</dt><dd><p>A regular expression which evaluates to match the machines the recipe
3241 works with.
3242 It stops recipes being run on machines for which they are not compatible.
3243 This is particularly useful with kernels.
3244 It also helps to increase parsing speed as further parsing of the recipe is skipped
3245 if it is found the current machine is not compatible.</p></dd><dt><a id="var-CONFFILES"></a>CONFFILES</dt><dd><p>
3246 Identifies editable or configurable files that are part of a package.
3247 If the Package Management System (PMS) is being used to update
3248 packages on the target system, it is possible that
3249 configuration files you have changed after the original installation
3250 and that you now want to remain unchanged are overwritten.
3251 In other words, editable files might exist in the package that you do not
3252 want reset as part of the package update process.
3253 You can use the <code class="filename">CONFFILES</code> variable to list the files in the
3254 package that you wish to prevent the PMS from overwriting during this update process.
3255 </p><p>
3256 To use the <code class="filename">CONFFILES</code> variable, provide a package name
3257 override that identifies the resulting package.
3258 Then, provide a space-separated list of files.
3259 Here is an example:
3260 </p><pre class="literallayout">
3261 CONFFILES_${PN} += "${sysconfdir}/file1 \
3262 ${sysconfdir}/file2 ${sysconfdir}/file3"
3263 </pre><p>
3264 </p><p>
3265 A relationship exists between the <code class="filename">CONFFILES</code> and
3266 <code class="filename"><a class="link" href="#var-FILES" title="FILES">FILES</a></code> variables.
3267 The files listed within <code class="filename">CONFFILES</code> must be a subset of
3268 the files listed within <code class="filename">FILES</code>.
3269 Because the configuration files you provide with <code class="filename">CONFFILES</code>
3270 are simply being identified so that the PMS will not overwrite them,
3271 it makes sense that
3272 the files must already be included as part of the package through the
3273 <code class="filename">FILES</code> variable.
3274 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3275 When specifying paths as part of the <code class="filename">CONFFILES</code> variable,
3276 it is good practice to use appropriate path variables.
3277 For example, <code class="filename">${sysconfdir}</code> rather than
3278 <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather
3279 than <code class="filename">/usr/bin</code>.
3280 You can find a list of these variables at the top of the
3281 <code class="filename">/meta/conf/bitbake.conf</code> file in the
3282 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
3283 </div></dd><dt><a id="var-CONFIG_SITE"></a>CONFIG_SITE</dt><dd><p>
3284 A list of files that contains <code class="filename">autoconf</code> test results relevant
3285 to the current build.
3286 This variable is used by the Autotools utilities when running
3287 <code class="filename">configure</code>.
3288 </p></dd><dt><a id="var-CORE_IMAGE_EXTRA_INSTALL"></a>CORE_IMAGE_EXTRA_INSTALL</dt><dd><p>
3289 Specifies the list of packages to be added to the image.
3290 This variable should only be set in the <code class="filename">local.conf</code>
3291 configuration file found in the
3292 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
3293 </p><p>
3294 This variable replaces <code class="filename">POKY_EXTRA_INSTALL</code>, which is no longer supported.
3295 </p></dd></dl></div><div class="glossdiv" title="D"><h3 class="title">D</h3><dl><dt><a id="var-D"></a>D</dt><dd><p>The destination directory.</p></dd><dt><a id="var-DEBUG_BUILD"></a>DEBUG_BUILD</dt><dd><p>
3296 Specifies to build packages with debugging information.
3297 This influences the value of the
3298 <code class="filename"><a class="link" href="#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION</a></code>
3299 variable.
3300 </p></dd><dt><a id="var-DEBUG_OPTIMIZATION"></a>DEBUG_OPTIMIZATION</dt><dd><p>
3301 The options to pass in
3302 <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>
3303 and <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code> when compiling
3304 a system for debugging.
3305 This variable defaults to "-O -fno-omit-frame-pointer -g".
3306 </p></dd><dt><a id="var-DEFAULT_PREFERENCE"></a>DEFAULT_PREFERENCE</dt><dd><p>Specifies the priority of recipes.</p></dd><dt><a id="var-DEPENDS"></a>DEPENDS</dt><dd><p>
3307 Lists a recipe's build-time dependencies
3308 (i.e. other recipe files).
3309 The system ensures that all the dependencies listed
3310 have been built and have their contents in the appropriate
3311 sysroots before the recipe's configure task is executed.
3312 </p></dd><dt><a id="var-DESCRIPTION"></a>DESCRIPTION</dt><dd><p>The package description used by package managers.
3313 If not set, <code class="filename">DESCRIPTION</code> takes
3314 the value of the
3315 <a class="link" href="#var-SUMMARY" title="SUMMARY"><code class="filename">SUMMARY</code></a>
3316 variable.
3317 </p></dd><dt><a id="var-DESTDIR"></a>DESTDIR</dt><dd><p>the destination directory.</p></dd><dt><a id="var-DISTRO"></a>DISTRO</dt><dd><p>
3318 The short name of the distribution.
3319 This variable corresponds to a file with the
3320 extension <code class="filename">.conf</code>
3321 located in a <code class="filename">conf/distro</code> directory
3322 within the metadata that contains the distribution configuration.
3323 The
3324 value must not contain spaces, and is typically all lower-case.
3325 </p><p>
3326 If the variable is blank, a set of default configuration
3327 will be used, which is specified
3328 within <code class="filename">meta/conf/distro/defaultsetup.conf</code>.
3329 </p></dd><dt><a id="var-DISTRO_EXTRA_RDEPENDS"></a>DISTRO_EXTRA_RDEPENDS</dt><dd><p>
3330 Specifies a list of distro-specific packages to add to all images.
3331 This variable takes affect through
3332 <code class="filename">packagegroup-base</code> so the
3333 variable only really applies to the more full-featured
3334 images that include <code class="filename">packagegroup-base</code>.
3335 You can use this variable to keep distro policy out of
3336 generic images.
3337 As with all other distro variables, you set this variable
3338 in the distro <code class="filename">.conf</code> file.
3339 </p></dd><dt><a id="var-DISTRO_EXTRA_RRECOMMENDS"></a>DISTRO_EXTRA_RRECOMMENDS</dt><dd><p>
3340 Specifies a list of distro-specific packages to add to all images
3341 if the packages exist.
3342 The packages might not exist or be empty (e.g. kernel modules).
3343 The list of packages are automatically installed but can be
3344 removed by the user.
3345 </p></dd><dt><a id="var-DISTRO_FEATURES"></a>DISTRO_FEATURES</dt><dd><p>The features enabled for the distribution.
3346 For a list of features supported by the Yocto Project as shipped,
3347 see the "<a class="link" href="#ref-features-distro" title="9.1. Distro">Distro</a>"
3348 section.
3349 </p></dd><dt><a id="var-DISTRO_FEATURES_BACKFILL"></a>DISTRO_FEATURES_BACKFILL</dt><dd><p>Features to be added to
3350 <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>
3351 if not also present in
3352 <code class="filename"><a class="link" href="#var-DISTRO_FEATURES_BACKFILL_CONSIDERED" title="DISTRO_FEATURES_BACKFILL_CONSIDERED">DISTRO_FEATURES_BACKFILL_CONSIDERED</a></code>.
3353 </p><p>
3354 This variable is set in the <code class="filename">meta/conf/bitbake.conf</code> file.
3355 It is not intended to be user-configurable.
3356 It is best to just reference the variable to see which distro features are
3357 being backfilled for all distro configurations.
3358 See the <a class="link" href="#ref-features-backfill" title="9.4. Feature Backfilling">Feature backfilling</a> section for
3359 more information.
3360 </p></dd><dt><a id="var-DISTRO_FEATURES_BACKFILL_CONSIDERED"></a>DISTRO_FEATURES_BACKFILL_CONSIDERED</dt><dd><p>Features from
3361 <code class="filename"><a class="link" href="#var-DISTRO_FEATURES_BACKFILL" title="DISTRO_FEATURES_BACKFILL">DISTRO_FEATURES_BACKFILL</a></code>
3362 that should not backfilled (i.e. added to
3363 <code class="filename"><a class="link" href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></code>)
3364 during the build.
3365 See the "<a class="link" href="#ref-features-backfill" title="9.4. Feature Backfilling">Feature Backfilling</a>" section for
3366 more information.
3367 </p></dd><dt><a id="var-DISTRO_NAME"></a>DISTRO_NAME</dt><dd><p>The long name of the distribution.</p></dd><dt><a id="var-DISTRO_PN_ALIAS"></a>DISTRO_PN_ALIAS</dt><dd><p>Alias names used for the recipe in various Linux distributions.</p><p>See the
3368 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#usingpoky-configuring-DISTRO_PN_ALIAS" target="_top">Handling
3369 a Package Name Alias</a>" section in the Yocto Project Development
3370 Manual for more information.</p></dd><dt><a id="var-DISTRO_VERSION"></a>DISTRO_VERSION</dt><dd><p>the version of the distribution.</p></dd><dt><a id="var-DL_DIR"></a>DL_DIR</dt><dd><p>
3371 The central download directory used by the build process to store downloads.
3372 You can set this directory by defining the <code class="filename">DL_DIR</code>
3373 variable in the <code class="filename">/conf/local.conf</code> file.
3374 This directory is self-maintaining and you should not have
3375 to touch it.
3376 By default, the directory is <code class="filename">downloads</code> in the
3377 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
3378 </p><pre class="literallayout">
3379 #DL_DIR ?= "${TOPDIR}/downloads"
3380 </pre><p>
3381 To specify a different download directory, simply uncomment the line
3382 and provide your directory.
3383 </p><p>
3384 During a first build, the system downloads many different source code
3385 tarballs from various upstream projects.
3386 Downloading can take a while, particularly if your network
3387 connection is slow.
3388 Tarballs are all stored in the directory defined by
3389 <code class="filename">DL_DIR</code> and the build system looks there first
3390 to find source tarballs.
3391 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3392 When wiping and rebuilding, you can preserve this directory to speed
3393 up this part of subsequent builds.
3394 </div><p>
3395 </p><p>
3396 You can safely share this directory between multiple builds on the
3397 same development machine.
3398 For additional information on how the build process gets source files
3399 when working behind a firewall or proxy server, see the
3400 "<a class="link" href="#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server">FAQ</a>"
3401 chapter.
3402 </p></dd></dl></div><div class="glossdiv" title="E"><h3 class="title">E</h3><dl><dt><a id="var-ENABLE_BINARY_LOCALE_GENERATION"></a>ENABLE_BINARY_LOCALE_GENERATION</dt><dd><p></p><p>Variable that controls which locales for <code class="filename">eglibc</code> are
3403 to be generated during the build (useful if the target device has 64Mbytes
3404 of RAM or less).</p></dd><dt><a id="var-EXTENDPE"></a>EXTENDPE</dt><dd><p>
3405 Used with file and pathnames to create a prefix for a recipe's
3406 version based on the recipe's
3407 <a class="link" href="#var-PE" title="PE"><code class="filename">PE</code></a> value.
3408 If <code class="filename">PE</code> is set and greater than zero for a recipe,
3409 <code class="filename">EXTENDPE</code> becomes that value (e.g if
3410 <code class="filename">PE</code> is equal to "1" then <code class="filename">EXTENDPE</code>
3411 becomes "1_").
3412 If a recipe's <code class="filename">PE</code> is not set (the default) or is equal to
3413 zero, <code class="filename">EXTENDPE</code> becomes "".</p><p>See the <a class="link" href="#var-STAMP" title="STAMP"><code class="filename">STAMP</code></a>
3414 variable for an example.
3415 </p></dd><dt><a id="var-EXTRA_IMAGE_FEATURES"></a>EXTRA_IMAGE_FEATURES</dt><dd><p>Allows extra packages to be added to the generated images.
3416 You set this variable in the <code class="filename">local.conf</code>
3417 configuration file.
3418 Note that some image features are also added using the
3419 <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code>
3420 variable generally configured in image recipes.
3421 You can use this variable to add more features in addition to those.
3422 Here are some examples of features you can add:</p><pre class="literallayout">
3423"dbg-pkgs" - Adds -dbg packages for all installed packages
3424 including symbol information for debugging and
3425 profiling.
3426
3427"dev-pkgs" - Adds -dev packages for all installed packages.
3428 This is useful if you want to develop against
3429 the libraries in the image.
3430
3431"tools-sdk" - Adds development tools such as gcc, make,
3432 pkgconfig and so forth.
3433
3434"tools-debug" - Adds debugging tools such as gdb and
3435 strace.
3436
3437"tools-profile" - Adds profiling tools such as oprofile,
3438 exmap, lttng and valgrind (x86 only).
3439
3440"tools-testapps" - Adds useful testing tools such as
3441 ts_print, aplay, arecord and so
3442 forth.
3443
3444"debug-tweaks" - Makes an image suitable for development.
3445 For example, ssh root access has a blank
3446 password. You should remove this feature
3447 before you produce a production image.
3448 </pre><p>There are other valid features too, see the
3449 <a class="link" href="#ref-features-image" title="9.3. Images">Images</a>
3450 section for more details.</p></dd><dt><a id="var-EXTRA_IMAGEDEPENDS"></a>EXTRA_IMAGEDEPENDS</dt><dd><p>A list of recipes to be built that do not provide packages to be installed in
3451 the root filesystem.
3452 </p><p>Sometimes a recipe is required to build the final image but is not
3453 needed in the root filesystem.
3454 You can use the <code class="filename">EXTRA_IMAGEDEPENDS</code> variable to
3455 list these recipes and thus, specify the dependencies.
3456 A typical example is a required bootloader in a machine configuration.
3457 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3458 To add packages to the root filesystem, see the various
3459 <code class="filename">*DEPENDS</code> and <code class="filename">*RECOMMENDS</code>
3460 variables.
3461 </div></dd><dt><a id="var-EXTRA_OECMAKE"></a>EXTRA_OECMAKE</dt><dd><p>Additional <code class="filename">cmake</code> options.</p></dd><dt><a id="var-EXTRA_OECONF"></a>EXTRA_OECONF</dt><dd><p>Additional <code class="filename">configure</code> script options.</p></dd><dt><a id="var-EXTRA_OEMAKE"></a>EXTRA_OEMAKE</dt><dd><p>Additional GNU <code class="filename">make</code> options.</p></dd></dl></div><div class="glossdiv" title="F"><h3 class="title">F</h3><dl><dt><a id="var-FILES"></a>FILES</dt><dd><p>
3462 The list of directories or files that are placed in packages.
3463 </p><p>
3464 To use the <code class="filename">FILES</code> variable, provide a package name
3465 override that identifies the resulting package.
3466 Then, provide a space-separated list of files or paths that identifies the
3467 files you want included as part of the resulting package.
3468 Here is an example:
3469 </p><pre class="literallayout">
3470 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
3471 </pre><p>
3472 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
3473 When specifying paths as part of the <code class="filename">FILES</code> variable,
3474 it is good practice to use appropriate path variables.
3475 For example, <code class="filename">${sysconfdir}</code> rather than
3476 <code class="filename">/etc</code> or <code class="filename">${bindir}</code> rather
3477 than <code class="filename">/usr/bin</code>.
3478 You can find a list of these variables at the top of the
3479 <code class="filename">/meta/conf/bitbake.conf</code> file in the
3480 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
3481 </div><p>
3482 If some of the files you provide with the <code class="filename">FILES</code> variable
3483 are editable and you know they should not be
3484 overwritten during the package update process by the Package Management
3485 System (PMS), you can identify these files so that the PMS will not
3486 overwrite them.
3487 See the <code class="filename"><a class="link" href="#var-CONFFILES" title="CONFFILES">CONFFILES</a></code>
3488 variable for information on how to identify these files to the PMS.
3489 </p></dd><dt><a id="var-FILESEXTRAPATHS"></a>FILESEXTRAPATHS</dt><dd><p>
3490 Extends the search path the OpenEmbedded build system uses when
3491 looking for files and patches as it processes recipes.
3492 The directories BitBake uses when it processes recipes is defined by the
3493 <a class="link" href="#var-FILESPATH" title="FILESPATH"><code class="filename">FILESPATH</code></a> variable.
3494 You can add directories to the search path by defining the
3495 <code class="filename">FILESEXTRAPATHS</code> variable.
3496 </p><p>
3497 To add paths to the search order, provide a list of directories and separate
3498 each path using a colon character as follows:
3499 </p><pre class="literallayout">
3500 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
3501 </pre><p>
3502 Typically, you want your directories searched first.
3503 To make sure that happens, use <code class="filename">_prepend</code> and
3504 the immediate expansion (<code class="filename">:=</code>) operator as shown in the
3505 previous example.
3506 Finally, to maintain the integrity of the <code class="filename">FILESPATH</code> variable,
3507 you must include the appropriate beginning or ending (as needed) colon character.
3508 </p><p>
3509 The <code class="filename">FILESEXTRAPATHS</code> variable is intended for use in
3510 <code class="filename">.bbappend</code> files to include any additional files provided in that layer.
3511 You typically accomplish this with the following:
3512 </p><pre class="literallayout">
3513 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
3514 </pre><p>
3515 </p></dd><dt><a id="var-FILESPATH"></a>FILESPATH</dt><dd><p>
3516 The default set of directories the OpenEmbedded build system uses
3517 when searching for patches and files.
3518 During the build process, BitBake searches each directory in
3519 <code class="filename">FILESPATH</code> in the specified order when looking for
3520 files and patches specified by each <code class="filename">file://</code> URI in a recipe.
3521 </p><p>
3522 The default value for the <code class="filename">FILESPATH</code> variable is defined
3523 in the <code class="filename">base.bbclass</code> class found in
3524 <code class="filename">meta/classes</code> in the
3525 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>:
3526 </p><pre class="literallayout">
3527FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
3528 "${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \
3529 "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \
3530 "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}"
3531 </pre><p>
3532 Do not hand-edit the <code class="filename">FILESPATH</code> variable.
3533 If you want to extend the set of pathnames that BitBake uses when searching for
3534 files and patches, use the
3535 <a class="link" href="#var-FILESEXTRAPATHS" title="FILESEXTRAPATHS"><code class="filename">FILESEXTRAPATHS</code></a> variable.
3536 </p></dd><dt><a id="var-FILESYSTEM_PERMS_TABLES"></a>FILESYSTEM_PERMS_TABLES</dt><dd><p>Allows you to define your own file permissions settings table as part of
3537 your configuration for the packaging process.
3538 For example, suppose you need a consistent set of custom permissions for
3539 a set of groups and users across an entire work project.
3540 It is best to do this in the packages themselves but this is not always
3541 possible.
3542 </p><p>
3543 By default, the OpenEmbedded build system uses the <code class="filename">fs-perms.txt</code>, which
3544 is located in the <code class="filename">meta/files</code> folder in the
3545 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
3546 If you create your own file permissions setting table, you should place it in your
3547 layer or the distros layer.
3548 </p><p>
3549 You define the <code class="filename">FILESYSTEM_PERMS_TABLES</code> variable in the
3550 <code class="filename">conf/local.conf</code> file, which is found in the
3551 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>, to
3552 point to your custom <code class="filename">fs-perms.txt</code>.
3553 You can specify more than a single file permissions setting table.
3554 The paths you specify to these files must be defined within the
3555 <code class="filename">BBPATH</code> variable.
3556 </p><p>
3557 For guidance on how to create your own file permissions settings table file,
3558 examine the existing <code class="filename">fs-perms.txt</code>.
3559 </p></dd><dt><a id="var-FULL_OPTIMIZATION"></a>FULL_OPTIMIZATION</dt><dd><p>
3560 The options to pass in
3561 <code class="filename"><a class="link" href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a></code>
3562 and <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code>
3563 when compiling an optimized system.
3564 This variable defaults to
3565 "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
3566 </p></dd></dl></div><div class="glossdiv" title="H"><h3 class="title">H</h3><dl><dt><a id="var-HOMEPAGE"></a>HOMEPAGE</dt><dd><p>Website where more information about the software the recipe is building
3567 can be found.</p></dd></dl></div><div class="glossdiv" title="I"><h3 class="title">I</h3><dl><dt><a id="var-IMAGE_FEATURES"></a>IMAGE_FEATURES</dt><dd><p>The list of features to include in an image.
3568 Typically, you configure this variable in an image recipe.
3569 Note that you can also add extra features to the image by using the
3570 <code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES</a></code> variable.
3571 See the "<a class="link" href="#ref-features-image" title="9.3. Images">Images</a>" section for the
3572 full list of features that can be included in images built by the
3573 OpenEmbedded build system.</p></dd><dt><a id="var-IMAGE_FSTYPES"></a>IMAGE_FSTYPES</dt><dd><p>Formats of root filesystem images that you want to have created.</p></dd><dt><a id="var-IMAGE_INSTALL"></a>IMAGE_INSTALL</dt><dd><p>
3574 Specifies the packages to install into an image.
3575 The <code class="filename">IMAGE_INSTALL</code> variable is a mechanism for an image
3576 recipe and you should use it with care to avoid ordering issues.
3577 </p><p>
3578 Image recipes set <code class="filename">IMAGE_INSTALL</code> to specify the
3579 packages to install into an image through <code class="filename">image.bbclass</code>.
3580 Additionally, "helper" classes exist, such as <code class="filename">core-image.bbclass</code>,
3581 that can take
3582 <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code> lists
3583 and turn these into auto-generated entries in
3584 <code class="filename">IMAGE_INSTALL</code> in addition to its default contents.
3585 </p><p>
3586 Using <code class="filename">IMAGE_INSTALL</code> with the <code class="filename">+=</code>
3587 operator from the <code class="filename">/conf/local.conf</code> file or from within
3588 an image recipe is not recommended as it can cause ordering issues.
3589 Since <code class="filename">core-image.bbclass</code> sets <code class="filename">IMAGE_INSTALL</code>
3590 to a default value using the <code class="filename">?=</code> operator, using a
3591 <code class="filename">+=</code> operation against <code class="filename">IMAGE_INSTALL</code>
3592 will result in unexpected behavior when used in
3593 <code class="filename">/conf/local.conf</code>.
3594 Furthermore, the same operation from with an image recipe may or may not
3595 succeed depending on the specific situation.
3596 In both these cases, the behavior is contrary to how most users expect
3597 the <code class="filename">+=</code> operator to work.
3598 </p><p>
3599 When you use this variable, it is best to use it as follows:
3600 </p><pre class="literallayout">
3601 IMAGE_INSTALL_append = " package-name"
3602 </pre><p>
3603 Be sure to include the space between the quotation character and the start of the
3604 package name.
3605 </p></dd><dt><a id="var-IMAGE_OVERHEAD_FACTOR"></a>IMAGE_OVERHEAD_FACTOR</dt><dd><p>
3606 Defines a multiplier that the build system applies to the initial image
3607 size for cases when the multiplier times the returned disk usage value
3608 for the image is greater than the sum of
3609 <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code>
3610 and
3611 <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_EXTRA_SPACE" title="IMAGE_ROOTFS_EXTRA_SPACE">IMAGE_ROOTFS_EXTRA_SPACE</a></code>.
3612 The result of the multiplier applied to the initial image size creates
3613 free disk space in the image as overhead.
3614 By default, the build process uses a multiplier of 1.3 for this variable.
3615 This default value results in 30% free disk space added to the image when this
3616 method is used to determine the final generated image size.
3617 You should be aware that post install scripts and the package management
3618 system uses disk space inside this overhead area.
3619 Consequently, the multiplier does not produce an image with
3620 all the theoretical free disk space.
3621 See <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code>
3622 for information on how the build system determines the overall image size.
3623 </p><p>
3624 The default 30% free disk space typically gives the image enough room to boot
3625 and allows for basic post installs while still leaving a small amount of
3626 free disk space.
3627 If 30% free space is inadequate, you can increase the default value.
3628 For example, the following setting gives you 50% free space added to the image:
3629 </p><pre class="literallayout">
3630 IMAGE_OVERHEAD_FACTOR = "1.5"
3631 </pre><p>
3632 </p><p>
3633 Alternatively, you can ensure a specific amount of free disk space is added
3634 to the image by using
3635 <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_EXTRA_SPACE" title="IMAGE_ROOTFS_EXTRA_SPACE">IMAGE_ROOTFS_EXTRA_SPACE</a></code>
3636 the variable.
3637 </p></dd><dt><a id="var-IMAGE_ROOTFS_EXTRA_SPACE"></a>IMAGE_ROOTFS_EXTRA_SPACE</dt><dd><p>
3638 Defines additional free disk space created in the image in Kbytes.
3639 By default, this variable is set to "0".
3640 This free disk space is added to the image after the build system determines
3641 the image size as described in
3642 <code class="filename"><a class="link" href="#var-IMAGE_ROOTFS_SIZE" title="IMAGE_ROOTFS_SIZE">IMAGE_ROOTFS_SIZE</a></code>.
3643 </p><p>
3644 This variable is particularly useful when you want to ensure that a
3645 specific amount of free disk space is available on a device after an image
3646 is installed and running.
3647 For example, to be sure 5 Gbytes of free disk space is available, set the
3648 variable as follows:
3649 </p><pre class="literallayout">
3650 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3651 </pre><p>
3652 </p></dd><dt><a id="var-IMAGE_ROOTFS_SIZE"></a>IMAGE_ROOTFS_SIZE</dt><dd><p>
3653 Defines the size in Kbytes for the generated image.
3654 The OpenEmbedded build system determines the final size for the generated
3655 image using an algorithm that takes into account the initial disk space used
3656 for the generated image, a requested size for the image, and requested
3657 additional free disk space to be added to the image.
3658 Programatically, the build system determines the final size of the
3659 generated image as follows:
3660 </p><pre class="literallayout">
3661 if (image-du * overhead) &lt; rootfs-size:
3662 internal-rootfs-size = rootfs-size + xspace
3663 else:
3664 internal-rootfs-size = (image-du * overhead) + xspace
3665
3666 where:
3667
3668 image-du = Returned value of the du command on
3669 the image.
3670
3671 overhead = IMAGE_OVERHEAD_FACTOR
3672
3673 rootfs-size = IMAGE_ROOTFS_SIZE
3674
3675 internal-rootfs-size = Initial root filesystem
3676 size before any modifications.
3677
3678 xspace = IMAGE_ROOTFS_EXTRA_SPACE
3679 </pre><p>
3680
3681 </p></dd><dt><a id="var-INC_PR"></a>INC_PR</dt><dd><p>Helps define the recipe revision for recipes that share
3682 a common <code class="filename">include</code> file.
3683 You can think of this variable as part of the recipe revision
3684 as set from within an include file.</p><p>Suppose, for example, you have a set of recipes that
3685 are used across several projects.
3686 And, within each of those recipes the revision
3687 (its <code class="filename">PR</code> value) is set accordingly.
3688 In this case, when the revision of those recipes changes
3689 the burden is on you to find all those recipes and
3690 be sure that they get changed to reflect the updated
3691 version of the recipe.
3692 In this scenario, it can get complicated when recipes
3693 used in many places and that provide common functionality
3694 are upgraded to a new revision.</p><p>A more efficient way of dealing with this situation is
3695 to set the <code class="filename">INC_PR</code> variable inside
3696 the <code class="filename">include</code> files that the recipes
3697 share and then expand the <code class="filename">INC_PR</code>
3698 variable within the recipes to help
3699 define the recipe revision.
3700 </p><p>
3701 The following provides an example that shows how to use
3702 the <code class="filename">INC_PR</code> variable
3703 given a common <code class="filename">include</code> file that
3704 defines the variable.
3705 Once the variable is defined in the
3706 <code class="filename">include</code> file, you can use the
3707 variable to set the <code class="filename">PR</code> values in
3708 each recipe.
3709 You will notice that when you set a recipe's
3710 <code class="filename">PR</code> you can provide more granular
3711 revisioning by appending values to the
3712 <code class="filename">INC_PR</code> variable:
3713 </p><pre class="literallayout">
3714recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
3715recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
3716recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
3717recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3718 </pre><p>
3719 The first line of the example establishes the baseline
3720 revision to be used for all recipes that use the
3721 <code class="filename">include</code> file.
3722 The remaining lines in the example are from individual
3723 recipes and show how the <code class="filename">PR</code> value
3724 is set.</p></dd><dt><a id="var-INHIBIT_PACKAGE_STRIP"></a>INHIBIT_PACKAGE_STRIP</dt><dd><p>
3725 Causes the build to not strip binaries in resulting packages.
3726 </p></dd><dt><a id="var-INHERIT"></a>INHERIT</dt><dd><p>
3727 Causes the named class to be inherited at
3728 this point during parsing.
3729 The variable is only valid in configuration files.
3730 </p></dd><dt><a id="var-INITSCRIPT_PACKAGES"></a>INITSCRIPT_PACKAGES</dt><dd><p>
3731 A list of the packages that contain initscripts.
3732 If multiple packages are specified, you need to append the package name
3733 to the other <code class="filename">INITSCRIPT_*</code> as an override.</p><p>
3734 This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>.
3735 The variable is optional and defaults to the <code class="filename">PN</code> variable.
3736 </p></dd><dt><a id="var-INITSCRIPT_NAME"></a>INITSCRIPT_NAME</dt><dd><p>
3737 The filename of the initscript (as installed to <code class="filename">${etcdir}/init.d)</code>.
3738 </p><p>
3739 This variable is used in recipes when using <code class="filename">update-rc.d.bbclass</code>.
3740 The variable is Mandatory.
3741 </p></dd><dt><a id="var-INITSCRIPT_PARAMS"></a>INITSCRIPT_PARAMS</dt><dd><p>
3742 Specifies the options to pass to <code class="filename">update-rc.d</code>.
3743 An example is <code class="filename">start 99 5 2 . stop 20 0 1 6 .</code>, which gives the script a
3744 runlevel of 99, starts the script in initlevels 2 and 5, and
3745 stops the script in levels 0, 1 and 6.
3746 </p><p>
3747 The variable is mandatory and is used in recipes when using
3748 <code class="filename">update-rc.d.bbclass</code>.
3749 </p></dd></dl></div><div class="glossdiv" title="K"><h3 class="title">K</h3><dl><dt><a id="var-KBRANCH"></a>KBRANCH</dt><dd><p>
3750 A regular expression used by the build process to explicitly identify the kernel
3751 branch that is validated, patched and configured during a build.
3752 The <code class="filename">KBRANCH</code> variable is optional.
3753 You can use it to trigger checks to ensure the exact kernel branch you want is
3754 being used by the build process.
3755 </p><p>
3756 Values for this variable are set in the kernel's recipe file and the kernel's
3757 append file.
3758 For example, if you are using the Yocto Project kernel that is based on the
3759 Linux 3.4 kernel, the kernel recipe file is the
3760 <code class="filename">meta/recipes-kernel/linux/linux-yocto_3.4.bb</code> file.
3761 Following is the default value for <code class="filename">KBRANCH</code> and the default
3762 override for the architectures the Yocto Project supports:
3763 </p><pre class="literallayout">
3764 KBRANCH_DEFAULT = "standard/base"
3765 KBRANCH = "${KBRANCH_DEFAULT}"
3766 </pre><p>
3767 This branch exists in the <code class="filename">linux-yocto-3.4</code> kernel Git
3768 repository <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads" target="_top">http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads</a>.
3769 </p><p>
3770 This variable is also used from the kernel's append file to identify the kernel
3771 branch specific to a particular machine or target hardware.
3772 The kernel's append file is located in the BSP layer for a given machine.
3773 For example, the kernel append file for the Crown Bay BSP is in the
3774 <code class="filename">meta-intel</code> Git repository and is named
3775 <code class="filename">meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</code>.
3776 Here are the related statements from the append file:
3777 </p><pre class="literallayout">
3778 COMPATIBLE_MACHINE_crownbay = "crownbay"
3779 KMACHINE_crownbay = "crownbay"
3780 KBRANCH_crownbay = "standard/crownbay"
3781
3782 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
3783 KMACHINE_crownbay-noemgd = "crownbay"
3784 KBRANCH_crownbay-noemgd = "standard/crownbay"
3785 </pre><p>
3786 The <code class="filename">KBRANCH_*</code> statements identify the kernel branch to
3787 use when building for the Crown Bay BSP.
3788 In this case there are two identical statements: one for each type of
3789 Crown Bay machine.
3790 </p></dd><dt><a id="var-KERNEL_FEATURES"></a>KERNEL_FEATURES</dt><dd><p>Includes additional metadata from the Yocto Project kernel Git repository.
3791 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
3792 metadata is provided through
3793 the <code class="filename">KMACHINE</code> and <code class="filename">KBRANCH</code> variables.
3794 You can use the <code class="filename">KERNEL_FEATURES</code> variable to further
3795 add metadata for all BSPs.</p><p>The metadata you add through this variable includes config fragments and
3796 features descriptions,
3797 which usually includes patches as well as config fragments.
3798 You typically override the <code class="filename">KERNEL_FEATURES</code> variable
3799 for a specific machine.
3800 In this way, you can provide validated, but optional, sets of kernel
3801 configurations and features.</p><p>For example, the following adds <code class="filename">netfilter</code> to all
3802 the Yocto Project kernels and adds sound support to the <code class="filename">qemux86</code>
3803 machine:
3804 </p><pre class="literallayout">
3805 # Add netfilter to all linux-yocto kernels
3806 KERNEL_FEATURES="features/netfilter"
3807
3808 # Add sound support to the qemux86 machine
3809 KERNEL_FEATURES_append_qemux86=" cfg/sound"
3810 </pre></dd><dt><a id="var-KERNEL_IMAGETYPE"></a>KERNEL_IMAGETYPE</dt><dd><p>The type of kernel to build for a device, usually set by the
3811 machine configuration files and defaults to "zImage".
3812 This variable is used
3813 when building the kernel and is passed to <code class="filename">make</code> as the target to
3814 build.</p></dd><dt><a id="var-KMACHINE"></a>KMACHINE</dt><dd><p>
3815 The machine as known by the kernel.
3816 Sometimes the machine name used by the kernel does not match the machine name
3817 used by the OpenEmbedded build system.
3818 For example, the machine name that the OpenEmbedded build system understands as
3819 <code class="filename">qemuarm</code> goes by a different name in the Linux Yocto kernel.
3820 The kernel understands that machine as <code class="filename">arm_versatile926ejs</code>.
3821 For cases like these, the <code class="filename">KMACHINE</code> variable maps the
3822 kernel machine name to the OpenEmbedded build system machine name.
3823 </p><p>
3824 Kernel machine names are initially defined in the
3825 <a class="ulink" href="http://git.yoctoproject.org/cgit.cgi" target="_top">Yocto Linux Kernel</a> in
3826 the <code class="filename">meta</code> branch.
3827 From the <code class="filename">meta</code> branch, look in
3828 the <code class="filename">meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</code> file.
3829 For example, from the <code class="filename">meta</code> branch in the
3830 <code class="filename">linux-yocto-3.0</code> kernel, the
3831 <code class="filename">meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</code> file
3832 has the following:
3833 </p><pre class="literallayout">
3834 define KMACHINE cedartrail
3835 define KTYPE standard
3836 define KARCH i386
3837
3838 include ktypes/standard
3839 branch cedartrail
3840
3841 include cedartrail.scc
3842 </pre><p>
3843 You can see that the kernel understands the machine name for the Cedar Trail BSP as
3844 <code class="filename">cedartrail</code>.
3845 </p><p>
3846 If you look in the Cedar Trail BSP layer in the <code class="filename">meta-intel</code> source
3847 repository at <code class="filename">meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</code>,
3848 you will find the following statements among others:
3849 </p><pre class="literallayout">
3850 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
3851 KMACHINE_cedartrail = "cedartrail"
3852 KBRANCH_cedartrail = "yocto/standard/cedartrail"
3853 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
3854 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
3855
3856 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
3857 KMACHINE_cedartrail-nopvr = "cedartrail"
3858 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
3859 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
3860 </pre><p>
3861 The <code class="filename">KMACHINE</code> statements in the kernel's append file make sure that
3862 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
3863 names.
3864 </p><p>
3865 This append file uses two <code class="filename">KMACHINE</code> statements.
3866 The first is not really necessary but does ensure that the machine known to the
3867 OpenEmbedded build system as <code class="filename">cedartrail</code> maps to the machine
3868 in the kernel also known as <code class="filename">cedartrail</code>:
3869 </p><pre class="literallayout">
3870 KMACHINE_cedartrail = "cedartrail"
3871 </pre><p>
3872 </p><p>
3873 The second statement is a good example of why the <code class="filename">KMACHINE</code> variable
3874 is needed.
3875 In this example, the OpenEmbedded build system uses the <code class="filename">cedartrail-nopvr</code>
3876 machine name to refer to the Cedar Trail BSP that does not support the propriatory
3877 PowerVR driver.
3878 The kernel, however, uses the machine name <code class="filename">cedartrail</code>.
3879 Thus, the append file must map the <code class="filename">cedartrail-nopvr</code> machine name to
3880 the kernel's <code class="filename">cedartrail</code> name:
3881 </p><pre class="literallayout">
3882 KMACHINE_cedartrail-nopvr = "cedartrail"
3883 </pre><p>
3884 </p><p>
3885 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
3886 Project kernel machine names and the OpenEmbedded machine names.
3887 Be sure to use the <code class="filename">KMACHINE</code> if you create a BSP and the machine
3888 name you use is different than that used in the kernel.
3889 </p></dd></dl></div><div class="glossdiv" title="L"><h3 class="title">L</h3><dl><dt><a id="var-LAYERDEPENDS"></a>LAYERDEPENDS</dt><dd><p>Lists the layers that this recipe depends upon, separated by spaces.
3890 Optionally, you can specify a specific layer version for a dependency
3891 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
3892 to be compared against <code class="filename">LAYERVERSION_anotherlayer</code> in this case).
3893 An error will be produced if any dependency is missing or
3894 the version numbers do not match exactly (if specified).
3895 This variable is used in the <code class="filename">conf/layer.conf</code> file
3896 and must be suffixed with the name of the specific layer (e.g.
3897 <code class="filename">LAYERDEPENDS_mylayer</code>).</p></dd><dt><a id="var-LAYERDIR"></a>LAYERDIR</dt><dd><p>When used inside the <code class="filename">layer.conf</code> configuration
3898 file, this variable provides the path of the current layer.
3899 This variable requires immediate expansion
3900 (see the BitBake manual) as lazy expansion can result in
3901 the expansion happening in the wrong directory and therefore
3902 giving the wrong value.</p></dd><dt><a id="var-LAYERVERSION"></a>LAYERVERSION</dt><dd><p>Optionally specifies the version of a layer as a single number.
3903 You can use this within <code class="filename">LAYERDEPENDS</code> for another layer in order to
3904 depend on a specific version of the layer.
3905 This variable is used in the <code class="filename">conf/layer.conf</code> file
3906 and must be suffixed with the name of the specific layer (e.g.
3907 <code class="filename">LAYERVERSION_mylayer</code>).</p></dd><dt><a id="var-LIC_FILES_CHKSUM"></a>LIC_FILES_CHKSUM</dt><dd><p>Checksums of the license text in the recipe source code.</p><p>This variable tracks changes in license text of the source
3908 code files.
3909 If the license text is changed, it will trigger a build
3910 failure, which gives the developer an opportunity to review any
3911 license change.</p><p>
3912 This variable must be defined for all recipes (unless <code class="filename">LICENSE</code>
3913 is set to "CLOSED")</p><p>For more information, see the
3914 <a class="link" href="#usingpoky-configuring-LIC_FILES_CHKSUM" title="3.4.1. Tracking License Changes">
3915 Tracking License Changes</a> section</p></dd><dt><a id="var-LICENSE"></a>LICENSE</dt><dd><p>
3916 The list of source licenses for the recipe.
3917 Follow these rules:
3918 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Do not use spaces within individual
3919 license names.</p></li><li class="listitem"><p>Separate license names using
3920 | (pipe) when there is a choice between licenses.
3921 </p></li><li class="listitem"><p>Separate license names using
3922 &amp; (ampersand) when multiple licenses exist
3923 that cover different parts of the source.
3924 </p></li><li class="listitem"><p>You can use spaces between license
3925 names.</p></li></ul></div><p>
3926 </p><p>
3927 Here are some examples:
3928 </p><pre class="literallayout">
3929 LICENSE = "LGPLv2.1 | GPLv3"
3930 LICENSE = "MPL-1 &amp; LGPLv2.1"
3931 LICENSE = "GPLv2+"
3932 </pre><p>
3933 The first example is from the recipes for Qt, which the user
3934 may choose to distribute under either the LGPL version
3935 2.1 or GPL version 3.
3936 The second example is from Cairo where two licenses cover
3937 different parts of the source code.
3938 The final example is from <code class="filename">sysstat</code>,
3939 which presents a single license.
3940 </p></dd><dt><a id="var-LICENSE_PATH"></a>LICENSE_PATH</dt><dd><p>Path to additional licenses used during the build.
3941 By default, the OpenEmbedded build system uses <code class="filename">COMMON_LICENSE_DIR</code>
3942 to define the directory that holds common license text used during the build.
3943 The <code class="filename">LICENSE_PATH</code> variable allows you to extend that
3944 location to other areas that have additional licenses:
3945 </p><pre class="literallayout">
3946 LICENSE_PATH += "/path/to/additional/common/licenses"
3947 </pre></dd></dl></div><div class="glossdiv" title="M"><h3 class="title">M</h3><dl><dt><a id="var-MACHINE"></a>MACHINE</dt><dd><p>
3948 Specifies the target device for which the image is built.
3949 You define <code class="filename">MACHINE</code> in the
3950 <code class="filename">local.conf</code> file found in the
3951 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
3952 By default, <code class="filename">MACHINE</code> is set to
3953 "qemux86", which is an x86-based architecture machine to
3954 be emulated using QEMU:
3955 </p><pre class="literallayout">
3956 MACHINE ?= "qemux86"
3957 </pre><p>
3958 The variable corresponds to a machine configuration file of the
3959 same name, through which machine-specific configurations are set.
3960 Thus, when <code class="filename">MACHINE</code> is set to "qemux86" there
3961 exists the corresponding <code class="filename">qemux86.conf</code> machine
3962 configuration file, which can be found in the
3963 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>
3964 in <code class="filename">meta/conf/machine</code>.
3965 </p><p>
3966 The list of machines supported by the Yocto Project as
3967 shipped include the following:
3968 </p><pre class="literallayout">
3969 MACHINE ?= "qemuarm"
3970 MACHINE ?= "qemumips"
3971 MACHINE ?= "qemuppc"
3972 MACHINE ?= "qemux86"
3973 MACHINE ?= "qemux86-64"
3974 MACHINE ?= "atom-pc"
3975 MACHINE ?= "beagleboard"
3976 MACHINE ?= "mpc8315e-rdb"
3977 MACHINE ?= "routerstationpro"
3978 </pre><p>
3979 The last four are Yocto Project reference hardware boards, which
3980 are provided in the <code class="filename">meta-yocto-bsp</code> layer.
3981 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Adding additional Board Support Package (BSP) layers
3982 to your configuration adds new possible settings for
3983 <code class="filename">MACHINE</code>.
3984 </div><p>
3985 </p></dd><dt><a id="var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS"></a>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</dt><dd><p></p><p>
3986 A list of required machine-specific packages to install as part of
3987 the image being built.
3988 The build process depends on these packages being present.
3989 Furthermore, because this is a "machine essential" variable, the list of
3990 packages are essential for the machine to boot.
3991 The impact of this variable affects images based on
3992 <code class="filename">packagegroup-core-boot</code>,
3993 including the <code class="filename">core-image-minimal</code> image.
3994 </p><p>
3995 This variable is similar to the
3996 <code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS" title="MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS">MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code>
3997 variable with the exception that the image being built has a build
3998 dependency on the variable's list of packages.
3999 In other words, the image will not build if a file in this list is not found.
4000 </p><p>
4001 As an example, suppose the machine for which you are building requires
4002 <code class="filename">example-init</code> to be run during boot to initialize the hardware.
4003 In this case, you would use the following in the machine's
4004 <code class="filename">.conf</code> configuration file:
4005 </p><pre class="literallayout">
4006 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
4007 </pre><p>
4008 </p></dd><dt><a id="var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS"></a>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</dt><dd><p></p><p>
4009 A list of recommended machine-specific packages to install as part of
4010 the image being built.
4011 The build process does not depend on these packages being present.
4012 However, because this is a "machine essential" variable, the list of
4013 packages are essential for the machine to boot.
4014 The impact of this variable affects images based on
4015 <code class="filename">packagegroup-core-boot</code>,
4016 including the <code class="filename">core-image-minimal</code> image.
4017 </p><p>
4018 This variable is similar to the
4019 <code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS" title="MACHINE_ESSENTIAL_EXTRA_RDEPENDS">MACHINE_ESSENTIAL_EXTRA_RDEPENDS</a></code>
4020 variable with the exception that the image being built does not have a build
4021 dependency on the variable's list of packages.
4022 In other words, the image will still build if a package in this list is not found.
4023 Typically, this variable is used to handle essential kernel modules, whose
4024 functionality may be selected to be built into the kernel rather than as a module,
4025 in which case a package will not be produced.
4026 </p><p>
4027 Consider an example where you have a custom kernel where a specific touchscreen
4028 driver is required for the machine to be usable.
4029 However, the driver can be built as a module or
4030 into the kernel depending on the kernel configuration.
4031 If the driver is built as a module, you want it to be installed.
4032 But, when the driver is built into the kernel, you still want the
4033 build to succeed.
4034 This variable sets up a "recommends" relationship so that in the latter case,
4035 the build will not fail due to the missing package.
4036 To accomplish this, assuming the package for the module was called
4037 <code class="filename">kernel-module-ab123</code>, you would use the
4038 following in the machine's <code class="filename">.conf</code> configuration
4039 file:
4040 </p><pre class="literallayout">
4041 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
4042 </pre><p>
4043 </p><p>
4044 Some examples of these machine essentials are flash, screen, keyboard, mouse,
4045 or touchscreen drivers (depending on the machine).
4046 </p></dd><dt><a id="var-MACHINE_EXTRA_RDEPENDS"></a>MACHINE_EXTRA_RDEPENDS</dt><dd><p>
4047 A list of machine-specific packages to install as part of the
4048 image being built that are not essential for the machine to boot.
4049 However, the build process for more fully-featured images
4050 depends on the packages being present.
4051 </p><p>
4052 This variable affects all images based on
4053 <code class="filename">packagegroup-base</code>, which does not include the
4054 <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code>
4055 images.
4056 </p><p>
4057 The variable is similar to the
4058 <code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS</a></code>
4059 variable with the exception that the image being built has a build
4060 dependency on the variable's list of packages.
4061 In other words, the image will not build if a file in this list is not found.
4062 </p><p>
4063 An example is a machine that has WiFi capability but is not essential
4064 For the machine to boot the image.
4065 However, if you are building a more fully-featured image, you want to enable
4066 the WiFi.
4067 The package containing the firmware for the WiFi hardware is always
4068 expected to exist, so it is acceptable for the build process to depend upon
4069 finding the package.
4070 In this case, assuming the package for the firmware was called
4071 <code class="filename">wifidriver-firmware</code>, you would use the following in the
4072 <code class="filename">.conf</code> file for the machine:
4073 </p><pre class="literallayout">
4074 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
4075 </pre><p>
4076 </p></dd><dt><a id="var-MACHINE_EXTRA_RRECOMMENDS"></a>MACHINE_EXTRA_RRECOMMENDS</dt><dd><p></p><p>
4077 A list of machine-specific packages to install as part of the
4078 image being built that are not essential for booting the machine.
4079 The image being built has no build dependency on this list of packages.
4080 </p><p>
4081 This variable affects only images based on
4082 <code class="filename">packagegroup-base</code>, which does not include the
4083 <code class="filename">core-image-minimal</code> or <code class="filename">core-image-basic</code>
4084 images.
4085 </p><p>
4086 This variable is similar to the
4087 <code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS</a></code>
4088 variable with the exception that the image being built does not have a build
4089 dependency on the variable's list of packages.
4090 In other words, the image will build if a file in this list is not found.
4091 </p><p>
4092 An example is a machine that has WiFi capability but is not essential
4093 For the machine to boot the image.
4094 However, if you are building a more fully-featured image, you want to enable
4095 WiFi.
4096 In this case, the package containing the WiFi kernel module will not be produced
4097 if the WiFi driver is built into the kernel, in which case you still want the
4098 build to succeed instead of failing as a result of the package not being found.
4099 To accomplish this, assuming the package for the module was called
4100 <code class="filename">kernel-module-examplewifi</code>, you would use the
4101 following in the <code class="filename">.conf</code> file for the machine:
4102 </p><pre class="literallayout">
4103 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
4104 </pre><p>
4105 </p></dd><dt><a id="var-MACHINE_FEATURES"></a>MACHINE_FEATURES</dt><dd><p>Specifies the list of hardware features the
4106 <a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a> supports.
4107 For example, including the "bluetooth" feature causes the
4108 <code class="filename">bluez</code> bluetooth daemon to be built and
4109 added to the image.
4110 It also causes the <code class="filename">connman</code> recipe
4111 to look at <code class="filename">MACHINE_FEATURES</code> and when it
4112 finds "bluetooth" there it enables the bluetooth
4113 support in ConnMan.
4114 </p><p>
4115 For a list of features supported by the Yocto Project as shipped,
4116 see the "<a class="link" href="#ref-features-machine" title="9.2. Machine">Machine</a>" section.
4117 </p></dd><dt><a id="var-MACHINE_FEATURES_BACKFILL"></a>MACHINE_FEATURES_BACKFILL</dt><dd><p>Features to be added to
4118 <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>
4119 if not also present in
4120 <code class="filename"><a class="link" href="#var-MACHINE_FEATURES_BACKFILL_CONSIDERED" title="MACHINE_FEATURES_BACKFILL_CONSIDERED">MACHINE_FEATURES_BACKFILL_CONSIDERED</a></code>.
4121 </p><p>
4122 This variable is set in the <code class="filename">meta/conf/bitbake.conf</code> file.
4123 It is not intended to be user-configurable.
4124 It is best to just reference the variable to see which machine features are
4125 being backfilled for all machine configurations.
4126 See the <a class="link" href="#ref-features-backfill" title="9.4. Feature Backfilling">Feature backfilling</a> section for
4127 more information.
4128 </p></dd><dt><a id="var-MACHINE_FEATURES_BACKFILL_CONSIDERED"></a>MACHINE_FEATURES_BACKFILL_CONSIDERED</dt><dd><p>Features from
4129 <code class="filename"><a class="link" href="#var-MACHINE_FEATURES_BACKFILL" title="MACHINE_FEATURES_BACKFILL">MACHINE_FEATURES_BACKFILL</a></code>
4130 that should not be backfilled (i.e. added to
4131 <code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></code>)
4132 during the build.
4133 See the <a class="link" href="#ref-features-backfill" title="9.4. Feature Backfilling">Feature backfilling</a> section for
4134 more information.
4135 </p></dd><dt><a id="var-MAINTAINER"></a>MAINTAINER</dt><dd><p>The email address of the distribution maintainer.</p></dd><dt><a id="var-MLPREFIX"></a>MLPREFIX</dt><dd><p>
4136 Specifies a prefix has been added to
4137 <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> to create a special version
4138 of a recipe or package, such as a multilib version.
4139 The variable is used in places where the prefix needs to be
4140 added to or removed from a the name (e.g. the
4141 <a class="link" href="#var-BPN" title="BPN"><code class="filename">BPN</code></a> variable).
4142 <code class="filename">MLPREFIX</code> gets set when a prefix has been
4143 added to <code class="filename">PN</code>.
4144 </p></dd><dt><a id="var-MULTIMACH_TARGET_SYS"></a>MULTIMACH_TARGET_SYS</dt><dd><p>
4145 Separates files for different machines such that you can build
4146 for multiple target machines using the same output directories.
4147 See the <a class="link" href="#var-STAMP" title="STAMP"><code class="filename">STAMP</code></a> variable
4148 for an example.
4149 </p></dd></dl></div><div class="glossdiv" title="O"><h3 class="title">O</h3><dl><dt><a id="var-OE_TERMINAL"></a>OE_TERMINAL</dt><dd><p>
4150 Controls how the OpenEmbedded build system spawns
4151 interactive terminals on the host development system
4152 (e.g. using the BitBake command with the
4153 <code class="filename">-c devshell</code> command-line option).
4154 For more information, see the
4155 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#platdev-appdev-devshell" target="_top">Using a Development Shell</a>" section
4156 in the Yocto Project Development Manual.
4157 </p><p>
4158 You can use the following values for the
4159 <code class="filename">OE_TERMINAL</code> variable:
4160 </p><pre class="literallayout">
4161 auto
4162 gnome
4163 xfce
4164 rxvt
4165 screen
4166 konsole
4167 none
4168 </pre><p>
4169 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>Konsole support only works for KDE 3.x.
4170 Also, "auto" is the default behavior for
4171 <code class="filename">OE_TERMINAL</code></div><p>
4172 </p></dd></dl></div><div class="glossdiv" title="P"><h3 class="title">P</h3><dl><dt><a id="var-P"></a>P</dt><dd><p>The recipe name and version.
4173 <code class="filename">P</code> is comprised of the following:
4174 </p><pre class="literallayout">
4175 ${PN}-${PV}
4176 </pre></dd><dt><a id="var-PACKAGE_ARCH"></a>PACKAGE_ARCH</dt><dd><p>The architecture of the resulting package or packages.</p></dd><dt><a id="var-PACKAGE_BEFORE_PN"></a>PACKAGE_BEFORE_PN</dt><dd><p>Enables easily adding packages to
4177 <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>
4178 before <code class="filename">${PN}</code> so that the packages can pick
4179 up files that would normally be included in the default package.</p></dd><dt><a id="var-PACKAGE_CLASSES"></a>PACKAGE_CLASSES</dt><dd><p>This variable, which is set in the <code class="filename">local.conf</code> configuration
4180 file found in the <code class="filename">conf</code> folder of the
4181 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>,
4182 specifies the package manager to use when packaging data.
4183 You can provide one or more arguments for the variable with the first
4184 argument being the package manager used to create images:
4185 </p><pre class="literallayout">
4186 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
4187 </pre><p>
4188 For information on build performance effects as a result of the
4189 package manager use, see
4190 <a class="link" href="#ref-classes-package" title="7.13. Packaging - package*.bbclass">Packaging - <code class="filename">package*.bbclass</code></a>
4191 in this manual.
4192 </p></dd><dt><a id="var-PACKAGE_EXTRA_ARCHS"></a>PACKAGE_EXTRA_ARCHS</dt><dd><p>Specifies the list of architectures compatible with the device CPU.
4193 This variable is useful when you build for several different devices that use
4194 miscellaneous processors such as XScale and ARM926-EJS).</p></dd><dt><a id="var-PACKAGECONFIG"></a>PACKAGECONFIG</dt><dd><p>
4195 This variable provides a means of enabling or disabling
4196 features of a recipe on a per-recipe basis.
4197 The <code class="filename">PACKAGECONFIG</code>
4198 variable itself specifies a space-separated list of the
4199 features to enable.
4200 The features themselves are specified as flags on the
4201 <code class="filename">PACKAGECONFIG</code> variable.
4202 You can provide up to four arguments, which are separated by
4203 commas, to determine the behavior of each feature
4204 when it is enabled or disabled.
4205 You can omit any argument you like but must retain the
4206 separating commas.
4207 The arguments specify the following:
4208 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Extra arguments
4209 that should be added to the configure script argument list
4210 (<a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF"><code class="filename">EXTRA_OECONF</code></a>)
4211 if the feature is enabled.</p></li><li class="listitem"><p>Extra arguments
4212 that should be added to <code class="filename">EXTRA_OECONF</code>
4213 if the feature is disabled.
4214 </p></li><li class="listitem"><p>Additional build dependencies
4215 (<a class="link" href="#var-DEPENDS" title="DEPENDS"><code class="filename">DEPENDS</code></a>)
4216 that should be added if the feature is enabled.
4217 </p></li><li class="listitem"><p>Additional runtime dependencies
4218 (<a class="link" href="#var-RDEPENDS" title="RDEPENDS"><code class="filename">RDEPENDS</code></a>)
4219 that should be added if the feature is enabled.
4220 </p></li></ol></div><p>
4221 </p><p>
4222 Consider the following example taken from the
4223 <code class="filename">librsvg</code> recipe.
4224 In this example the feature is <code class="filename">croco</code>, which
4225 has three arguments that determine the feature's behavior.
4226 </p><pre class="literallayout">
4227 PACKAGECONFIG ??= "croco"
4228 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
4229 </pre><p>
4230 The <code class="filename">--with-croco</code> and
4231 <code class="filename">libcroco</code> arguments apply only if
4232 the feature is enabled.
4233 In this case, <code class="filename">--with-croco</code> is
4234 added to the configure script argument list and
4235 <code class="filename">libcroco</code> is added to
4236 <code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></code>.
4237 On the other hand, if the feature is disabled say through
4238 a <code class="filename">.bbappend</code> file in another layer, then
4239 the second argument <code class="filename">--without-croco</code> is
4240 added to the configure script rather than
4241 <code class="filename">--with-croco</code>.
4242 </p></dd><dt><a id="var-PACKAGES"></a>PACKAGES</dt><dd><p>The list of packages to be created from the recipe.
4243 The default value is the following:
4244 </p><pre class="literallayout">
4245 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
4246 </pre></dd><dt><a id="var-PACKAGES_DYNAMIC"></a>PACKAGES_DYNAMIC</dt><dd><p>
4247 A promise that your recipe satisfies runtime dependencies
4248 for optional modules that are found in other recipes.
4249 <code class="filename">PACKAGES_DYNAMIC</code>
4250 does not actually satisfy the dependencies, it only states that
4251 they should be satisfied.
4252 For example, if a hard, runtime dependency
4253 (<code class="filename">RDEPENDS</code>) of another package is satisfied
4254 at build time through the <code class="filename">PACKAGES_DYNAMIC</code>
4255 variable, but a package with the module name is never actually
4256 produced, then the other package will be broken.
4257 Thus, if you attempt to include that package in an image,
4258 you will get a dependency failure from the packaging system
4259 during <code class="filename">do_rootfs</code>.
4260 Typically, if there is a chance that such a situation can
4261 occur and the package that is not created is valid
4262 without the dependency being satisfied, then you should use
4263 <code class="filename">RRECOMMENDS</code> (a soft runtime dependency)
4264 instead of <code class="filename">RDEPENDS</code>.
4265 </p><p>
4266 For an example of how to use the <code class="filename">PACKAGES_DYNAMIC</code>
4267 variable when you are splitting packages, see the
4268 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#handling-optional-module-packaging" target="_top">Handling Optional Module Packaging</a>" section
4269 in the Yocto Project Development Manual.
4270 </p></dd><dt><a id="var-PARALLEL_MAKE"></a>PARALLEL_MAKE</dt><dd><p>Specifies extra options that are passed to the <code class="filename">make</code> command during the
4271 compile tasks.
4272 This variable is usually in the form <code class="filename">-j 4</code>, where the number
4273 represents the maximum number of parallel threads make can run.
4274 If you development host supports multiple cores a good rule of thumb is to set
4275 this variable to twice the number of cores on the host.</p></dd><dt><a id="var-PF"></a>PF</dt><dd><p>Specifies the recipe or package name and includes all version and revision
4276 numbers (i.e. <code class="filename">eglibc-2.13-r20+svnr15508/</code> and
4277 <code class="filename">bash-4.2-r1/</code>).
4278 This variable is comprised of the following:
4279 </p><pre class="literallayout">
4280 ${PN}-${EXTENDPE}${PV}-${PR}
4281 </pre></dd><dt><a id="var-PN"></a>PN</dt><dd><p>This variable can have two separate functions depending on the context: a recipe
4282 name or a resulting package name.</p><p><code class="filename">PN</code> refers to a recipe name in the context of a file used
4283 by the OpenEmbedded build system as input to create a package.
4284 The name is normally extracted from the recipe file name.
4285 For example, if the recipe is named
4286 <code class="filename">expat_2.0.1.bb</code>, then the default value of <code class="filename">PN</code>
4287 will be "expat".</p><p>
4288 The variable refers to a package name in the context of a file created or produced by the
4289 OpenEmbedded build system.</p><p>If applicable, the <code class="filename">PN</code> variable also contains any special
4290 suffix or prefix.
4291 For example, using <code class="filename">bash</code> to build packages for the native
4292 machine, <code class="filename">PN</code> is <code class="filename">bash-native</code>.
4293 Using <code class="filename">bash</code> to build packages for the target and for Multilib,
4294 <code class="filename">PN</code> would be <code class="filename">bash</code> and
4295 <code class="filename">lib64-bash</code>, respectively.
4296 </p></dd><dt><a id="var-PR"></a>PR</dt><dd><p>The revision of the recipe.
4297 The default value for this variable is "r0".
4298 </p></dd><dt><a id="var-PRINC"></a>PRINC</dt><dd><p>Causes the <code class="filename">PR</code> variable of
4299 <code class="filename">.bbappend</code> files to dynamically increment.
4300 This increment minimizes the impact of layer ordering.</p><p>In order to ensure multiple <code class="filename">.bbappend</code> files can co-exist,
4301 <code class="filename">PRINC</code> should be self referencing.
4302 This variable defaults to 0.</p><p>Following is an example that increments <code class="filename">PR</code> by two:
4303 </p><pre class="literallayout">
4304 PRINC := "${@int(PRINC) + 2}"
4305 </pre><p>
4306 It is adviseable not to use strings such as ".= '.1'" with the variable because
4307 this usage is very sensitive to layer ordering.
4308 Explicit assignments should be avoided as they cannot adequately represent multiple
4309 <code class="filename">.bbappend</code> files.</p></dd><dt><a id="var-PV"></a>PV</dt><dd><p>The version of the recipe.
4310 The version is normally extracted from the recipe filename.
4311 For example, if the recipe is named
4312 <code class="filename">expat_2.0.1.bb</code>, then the default value of <code class="filename">PV</code>
4313 will be "2.0.1".
4314 <code class="filename">PV</code> is generally not overridden within
4315 a recipe unless it is building an unstable (i.e. development) version from a source code repository
4316 (e.g. Git or Subversion).
4317 </p></dd><dt><a id="var-PE"></a>PE</dt><dd><p>
4318 the epoch of the recipe.
4319 The default value is "0".
4320 The field is used to make upgrades possible when the versioning scheme changes in
4321 some backwards incompatible way.
4322 </p></dd><dt><a id="var-PREFERRED_PROVIDER"></a>PREFERRED_PROVIDER</dt><dd><p>
4323 If multiple recipes provide an item, this variable
4324 determines which recipe should be given preference.
4325 The variable must always be suffixed with the name of the
4326 provided item, and should be set to the
4327 <code class="filename">PN</code> of the recipe
4328 to which you want to give precedence.
4329 Here is an example:
4330 </p><pre class="literallayout">
4331 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
4332 </pre><p>
4333 </p></dd><dt><a id="var-PREFERRED_VERSION"></a>PREFERRED_VERSION</dt><dd><p>
4334 If there are multiple versions of recipes available, this
4335 variable determines which recipe should be given preference.
4336 The variable must always be suffixed with the <code class="filename">PN</code>
4337 for which to select, and should be set to the
4338 <code class="filename">PV</code> to which you want to give precedence.
4339 You can use the "<code class="filename">%</code>" character as a wildcard
4340 to match any number of characters, which can be useful when
4341 specifying versions that contain long revision number that could
4342 potentially change.
4343 Here are two examples:
4344 </p><pre class="literallayout">
4345 PREFERRED_VERSION_python = "2.6.6"
4346 PREFERRED_VERSION_linux-yocto = "3.0+git%"
4347 </pre><p>
4348 </p></dd></dl></div><div class="glossdiv" title="R"><h3 class="title">R</h3><dl><dt><a id="var-RCONFLICTS"></a>RCONFLICTS</dt><dd><p>The list of packages that conflict with a package.
4349 Note that the package will not be installed if the conflicting packages are not
4350 first removed.</p><p>
4351 Like all package-controlling variables, you must always use them in
4352 conjunction with a package name override.
4353 Here is an example:
4354 </p><pre class="literallayout">
4355 RCONFLICTS_${PN} = "another-conflicting-package-name"
4356 </pre><p>
4357 </p></dd><dt><a id="var-RDEPENDS"></a>RDEPENDS</dt><dd><p>
4358 Lists a package's run-time dependencies (i.e. other packages)
4359 that must be installed for the package to be built.
4360 In other words, in order for the package to be built and
4361 run correctly, it depends on the listed packages.
4362 If a package in this list cannot be found, it is probable
4363 that a dependency error would occur before the build.
4364 </p><p>
4365 The names of the variables you list with
4366 <code class="filename">RDEPENDS</code> must be the names of other
4367 packages as listed in the
4368 <a class="link" href="#var-PACKAGES" title="PACKAGES"><code class="filename">PACKAGES</code></a>
4369 variable.
4370 You should not list recipe names (<code class="filename">PN</code>).
4371 </p><p>
4372 Because the <code class="filename">RDEPENDS</code> variable applies
4373 to packages being built, you should
4374 always attach a package name to the variable to specify the
4375 particular run-time package that has the dependency.
4376 For example, suppose you are building a development package
4377 that depends on the <code class="filename">perl</code> package.
4378 In this case, you would use the following
4379 <code class="filename">RDEPENDS</code> statement:
4380 </p><pre class="literallayout">
4381 RDEPENDS_${PN}-dev += "perl"
4382 </pre><p>
4383 In the example, the package name
4384 (<code class="filename">${PN}-dev</code>) must appear as it would
4385 in the
4386 <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>
4387 namespace before any renaming of the output package by
4388 classes like <code class="filename">debian.bbclass</code>.
4389 </p><p>
4390 In many cases you do not need to explicitly add dependencies
4391 to <code class="filename">RDEPENDS</code> since some automatic
4392 handling occurs:
4393 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">shlibdeps</code></em></span>: If
4394 a run-time package contains a shared library
4395 (<code class="filename">.so</code>), the build
4396 processes the library in order to determine other
4397 libraries to which it is dynamically linked.
4398 The build process adds these libraries to
4399 <code class="filename">RDEPENDS</code> when creating the run-time
4400 package.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">pcdeps</code></em></span>: If
4401 the package ships a <code class="filename">pkg-config</code>
4402 information file, the build process uses this file
4403 to add items to the <code class="filename">RDEPENDS</code>
4404 variable to create the run-time packages.
4405 </p></li></ul></div><p>
4406 </p></dd><dt><a id="var-RRECOMMENDS"></a>RRECOMMENDS</dt><dd><p>
4407 A list of packages that extend the usability of a package being
4408 built.
4409 The package being built does not depend on this list of packages in
4410 order to successfully build, but needs them for the extended usability.
4411 To specify runtime dependencies for packages, see the
4412 <code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></code> variable.
4413 </p><p>
4414 The OpenEmbedded build process automatically installs the list of packages
4415 as part of the built package.
4416 However, you can remove them later if you want.
4417 If, during the build, a package from the list cannot be found, the build
4418 process continues without an error.
4419 </p><p>
4420 Because the <code class="filename">RRECOMMENDS</code> variable applies to packages
4421 being built, you should
4422 always attach an override to the variable to specify the particular package
4423 whose usability is being extended.
4424 For example, suppose you are building a development package that is extended
4425 to support wireless functionality.
4426 In this case, you would use the following:
4427 </p><pre class="literallayout">
4428 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
4429 </pre><p>
4430 In the example, the package name (<code class="filename">${PN}-dev</code>) must
4431 appear as it would in the
4432 <code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code> namespace before any
4433 renaming of the output package by classes like <code class="filename">debian.bbclass</code>.
4434 </p></dd><dt><a id="var-RREPLACES"></a>RREPLACES</dt><dd><p>The list of packages that are replaced with this package.</p></dd></dl></div><div class="glossdiv" title="S"><h3 class="title">S</h3><dl><dt><a id="var-S"></a>S</dt><dd><p>
4435 The location in the <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>
4436 where unpacked package source code resides.
4437 This location is within the working directory
4438 (<code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></code>), which
4439 is not static.
4440 The unpacked source location depends on the package name
4441 (<code class="filename"><a class="link" href="#var-PN" title="PN">PN</a></code>) and
4442 package version (<code class="filename"><a class="link" href="#var-PV" title="PV">PV</a></code>) as
4443 follows:
4444 </p><pre class="literallayout">
4445 ${WORKDIR}/${PN}/${PV}
4446 </pre><p>
4447 As an example, assume a
4448 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> top-level
4449 folder named <code class="filename">poky</code>
4450 and a default <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>
4451 at <code class="filename">poky/build</code>.
4452 In this case, the working directory the build system uses to build
4453 the <code class="filename">db</code> package is the following:
4454 </p><pre class="literallayout">
4455 ~/poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
4456 </pre><p>
4457 </p></dd><dt><a id="var-SDKIMAGE_FEATURES"></a>SDKIMAGE_FEATURES</dt><dd><p>Equivalent to
4458 <code class="filename"><a class="link" href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></code>.
4459 However, this variable applies to the SDK generated from an image using
4460 <code class="filename">bitbake -c populate_sdk imagename</code>).
4461 </p></dd><dt><a id="var-SECTION"></a>SECTION</dt><dd><p>The section in which packages should be categorized.
4462 Package management utilities can make use of this variable.</p></dd><dt><a id="var-SELECTED_OPTIMIZATION"></a>SELECTED_OPTIMIZATION</dt><dd><p>
4463 The variable takes the value of
4464 <code class="filename"><a class="link" href="#var-FULL_OPTIMIZATION" title="FULL_OPTIMIZATION">FULL_OPTIMIZATION</a></code>
4465 unless <code class="filename"><a class="link" href="#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a></code> = "1".
4466 In this case the value of
4467 <code class="filename"><a class="link" href="#var-DEBUG_OPTIMIZATION" title="DEBUG_OPTIMIZATION">DEBUG_OPTIMIZATION</a></code> is used.
4468 </p></dd><dt><a id="var-SERIAL_CONSOLE"></a>SERIAL_CONSOLE</dt><dd><p>The speed and device for the serial port used to attach the serial console.
4469 This variable is given to the kernel as the "console"
4470 parameter and after booting occurs <code class="filename">getty</code> is started on that port
4471 so remote login is possible.</p></dd><dt><a id="var-SITEINFO_ENDIANNESS"></a>SITEINFO_ENDIANNESS</dt><dd><p>
4472 Specifies the endian byte order of the target system.
4473 The value should be either "le" for little-endian or "be" for big-endian.
4474 </p></dd><dt><a id="var-SITEINFO_BITS"></a>SITEINFO_BITS</dt><dd><p>
4475 Specifies the number of bits for the target system CPU.
4476 The value should be either "32" or "64".
4477 </p></dd><dt><a id="var-SPECIAL_PKGSUFFIX"></a>SPECIAL_PKGSUFFIX</dt><dd><p>
4478 A list of prefixes for <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a> used by the
4479 OpenEmbedded build system to create variants of recipes or packages.
4480 The list specifies the prefixes to strip off during certain circumstances
4481 such as the generation of the <a class="link" href="#var-BPN" title="BPN"><code class="filename">BPN</code></a> variable.
4482 </p></dd><dt><a id="var-SRC_URI"></a>SRC_URI</dt><dd><p>The list of source files - local or remote.
4483 This variable tells the OpenEmbedded build system which bits to pull
4484 in for the build and how to pull them in.
4485 For example, if the recipe only needs to fetch a tarball from the
4486 internet, the recipe uses a single <code class="filename">SRC_URI</code> entry.
4487 On the other hand, if the recipe needs to fetch a tarball, apply
4488 two patches, and include a custom file, the recipe would include four
4489 instances of the variable.</p><p>The following list explains the available URI protocols:
4490 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">file://</code> -</em></span> Fetches files, which is usually
4491 a file shipped with the metadata, from the local machine.
4492 The path is relative to the
4493 <a class="link" href="#var-FILESPATH" title="FILESPATH"><code class="filename">FILESPATH</code></a>
4494 variable.
4495 Thus, the build system searches, in order, from the following directories,
4496 which are assumed to be a subdirectories of the directory in which the
4497 recipe file resides:
4498 </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><span class="emphasis"><em><code class="filename">${PN}</code> -</em></span> The recipe name
4499 with any special suffix or prefix, if applicable.
4500 For example, using <code class="filename">bash</code> to build for the native
4501 machine, <code class="filename">PN</code> is <code class="filename">bash-native</code>.
4502 Using <code class="filename">bash</code> to build for the target and for Multilib,
4503 <code class="filename">PN</code> would be <code class="filename">bash</code> and
4504 <code class="filename">lib64-bash</code>, respectively.
4505 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">${PF}</code> - </em></span>
4506 <code class="filename">${PN}-${EXTENDPE}${PV}-${PR}</code>.
4507 The recipe name including all version and revision numbers
4508 (i.e. <code class="filename">eglibc-2.13-r20+svnr15508/</code> and
4509 <code class="filename">bash-4.2-r1/</code>).</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">${P}</code> -</em></span>
4510 <code class="filename">${PN}-${PV}</code>.
4511 The recipe name and version (i.e. <code class="filename">bash-4.2</code>).
4512 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">${BPN}</code> -</em></span> The
4513 base recipe name without any special suffix or version numbers.
4514 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">${BP}</code> -</em></span>
4515 <code class="filename">${BPN}-${PV}</code>.
4516 The base recipe name and version but without any special
4517 package name suffix.</p></li><li class="listitem"><p><span class="emphasis"><em>Files -</em></span> Files beneath the directory in which the recipe
4518 resides.</p></li><li class="listitem"><p><span class="emphasis"><em>Directory -</em></span> The directory itself in which the recipe
4519 resides.</p></li></ul></div></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">bzr://</code> -</em></span> Fetches files from a
4520 Bazaar revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">git://</code> -</em></span> Fetches files from a
4521 Git revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">osc://</code> -</em></span> Fetches files from
4522 an OSC (OpenSuse Build service) revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">repo://</code> -</em></span> Fetches files from
4523 a repo (Git) repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">svk://</code> -</em></span> Fetches files from
4524 an SVK revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">http://</code> -</em></span> Fetches files from
4525 the Internet using <code class="filename">http</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">https://</code> -</em></span> Fetches files
4526 from the Internet using <code class="filename">https</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">ftp://</code> -</em></span> Fetches files
4527 from the Internet using <code class="filename">ftp</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">cvs://</code> -</em></span> Fetches files from
4528 a CVS revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">hg://</code> -</em></span> Fetches files from
4529 a Mercurial (<code class="filename">hg</code>) revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">p4://</code> -</em></span> Fetches files from
4530 a Perforce (<code class="filename">p4</code>) revision control repository.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">ssh://</code> -</em></span> Fetches files from
4531 a secure shell.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">svn://</code> -</em></span> Fetches files from
4532 a Subversion (<code class="filename">svn</code>) revision control repository.</p></li></ul></div><p>
4533 </p><p>Standard and recipe-specific options for <code class="filename">SRC_URI</code> exist.
4534 Here are standard options:
4535 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">apply</code> -</em></span> Whether to apply
4536 the patch or not.
4537 The default action is to apply the patch.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">striplevel</code> -</em></span> Which
4538 striplevel to use when applying the patch.
4539 The default level is 1.</p></li></ul></div><p>
4540 </p><p>Here are options specific to recipes building code from a revision control system:
4541 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">mindate</code> -</em></span> Only applies
4542 the patch if <a class="link" href="#var-SRCDATE" title="SRCDATE"><code class="filename">SRCDATE</code></a>
4543 is equal to or greater than <code class="filename">mindate</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">maxdate</code> -</em></span> Only applies
4544 the patch if <a class="link" href="#var-SRCDATE" title="SRCDATE"><code class="filename">SRCDATE</code></a>
4545 is not later than <code class="filename">mindate</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">minrev</code> -</em></span> Only applies
4546 the patch if <a class="link" href="#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a>
4547 is equal to or greater than <code class="filename">minrev</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">maxrev</code> -</em></span> Only applies
4548 the patch if <a class="link" href="#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a>
4549 is not later than <code class="filename">maxrev</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">rev</code> -</em></span> Only applies the
4550 patch if <a class="link" href="#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a>
4551 is equal to <code class="filename">rev</code>.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">notrev</code> -</em></span> Only applies
4552 the patch if <a class="link" href="#var-SRCREV" title="SRCREV"><code class="filename">SRCREV</code></a>
4553 is not equal to <code class="filename">rev</code>.</p></li></ul></div><p>
4554 </p><p>Here are some additional options worth mentioning:
4555 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><code class="filename">unpack</code> -</em></span> Controls
4556 whether or not to unpack the file if it is an archive.
4557 The default action is to upack the file.</p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">subdir</code> -</em></span> Places the file
4558 (or extracts its contents) into the specified
4559 subdirectory of <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>.
4560 This option is useful for unusual tarballs or other archives that
4561 don't have their files already in a subdirectory within the archive.
4562 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">name</code> -</em></span> Specifies a
4563 name to be used for association with <code class="filename">SRC_URI</code> checksums
4564 when you have more than one file specified in <code class="filename">SRC_URI</code>.
4565 </p></li><li class="listitem"><p><span class="emphasis"><em><code class="filename">downloadfilename</code> -</em></span> Specifies
4566 the filename used when storing the downloaded file.</p></li></ul></div><p>
4567 </p></dd><dt><a id="var-SRC_URI_OVERRIDES_PACKAGE_ARCH"></a>SRC_URI_OVERRIDES_PACKAGE_ARCH</dt><dd><p></p><p>
4568 By default, the OpenEmbedded build system automatically detects whether
4569 <code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code>
4570 contains files that are machine-specific.
4571 If so, the build system automatically changes
4572 <code class="filename"><a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></code>.
4573 Setting this variable to "0" disables this behavior.
4574 </p></dd><dt><a id="var-SRCDATE"></a>SRCDATE</dt><dd><p>
4575 The date of the source code used to build the package.
4576 This variable applies only if the source was fetched from a Source Code Manager (SCM).
4577 </p></dd><dt><a id="var-SRCREV"></a>SRCREV</dt><dd><p>
4578 The revision of the source code used to build the package.
4579 This variable applies to Subversion, Git, Mercurial and Bazaar
4580 only.
4581 Note that if you wish to build a fixed revision and you wish
4582 to avoid performing a query on the remote repository every time
4583 BitBake parses your recipe, you should specify a <code class="filename">SRCREV</code> that is a
4584 full revision identifier and not just a tag.
4585 </p></dd><dt><a id="var-SSTATE_DIR"></a>SSTATE_DIR</dt><dd><p>The directory for the shared state.</p></dd><dt><a id="var-SSTATE_MIRRORS"></a>SSTATE_MIRRORS</dt><dd><p>
4586 Configures the OpenEmbedded build system to search other
4587 mirror locations for prebuilt cache data objects before
4588 building out the data.
4589 This variable works like fetcher
4590 <code class="filename">MIRRORS</code>/<code class="filename">PREMIRRORS</code>
4591 and points to the cache locations to check for the shared
4592 objects.
4593 </p><p>
4594 You can specify a filesystem directory or a remote URL such
4595 as HTTP or FTP.
4596 The locations you specify need to contain the shared state
4597 cache (sstate-cache) results from previous builds.
4598 The sstate-cache you point to can also be from builds on
4599 other machines.
4600 </p><p>
4601 If a mirror uses the same structure as
4602 <a class="link" href="#var-SSTATE_DIR" title="SSTATE_DIR"><code class="filename">SSTATE_DIR</code></a>,
4603 you need to add
4604 "PATH" at the end as shown in the examples below.
4605 The build system substitues the correct path within the
4606 directory structure.
4607 </p><pre class="literallayout">
4608 SSTATE_MIRRORS ?= "\
4609 file://.* http://someserver.tld/share/sstate/PATH \n \
4610 file://.* file:///some/local/dir/sstate/PATH"
4611 </pre><p>
4612 </p></dd><dt><a id="var-STAGING_KERNEL_DIR"></a>STAGING_KERNEL_DIR</dt><dd><p>
4613 The directory with kernel headers that are required to build out-of-tree
4614 modules.
4615 </p></dd><dt><a id="var-STAMP"></a>STAMP</dt><dd><p>
4616 Specifies the base path used to create recipe stamp files.
4617 The path to an actual stamp file is constructed by evaluating this
4618 string and then appending additional information.
4619 Currently, the default assignment for <code class="filename">STAMP</code>
4620 as set in the <code class="filename">meta/conf/bitbake.conf</code> file
4621 is:
4622 </p><pre class="literallayout">
4623 STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
4624 </pre><p>
4625 See <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a>,
4626 <a class="link" href="#var-MULTIMACH_TARGET_SYS" title="MULTIMACH_TARGET_SYS"><code class="filename">MULTIMACH_TARGET_SYS</code></a>,
4627 <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a>,
4628 <a class="link" href="#var-EXTENDPE" title="EXTENDPE"><code class="filename">EXTENDPE</code></a>,
4629 <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a>, and
4630 <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a> for related variable
4631 information.
4632 </p></dd><dt><a id="var-SUMMARY"></a>SUMMARY</dt><dd><p>The short (72 characters or less) summary of the binary package for packaging
4633 systems such as <code class="filename">opkg</code>, <code class="filename">rpm</code> or
4634 <code class="filename">dpkg</code>.
4635 By default, <code class="filename">SUMMARY</code> is used to define
4636 the <a class="link" href="#var-DESCRIPTION" title="DESCRIPTION"><code class="filename">DESCRIPTION</code></a>
4637 variable if <code class="filename">DESCRIPTION</code> is not set
4638 in the recipe.
4639 </p></dd></dl></div><div class="glossdiv" title="T"><h3 class="title">T</h3><dl><dt><a id="var-T"></a>T</dt><dd><p>This variable points to a directory were Bitbake places temporary
4640 files when building a particular package.
4641 It is typically set as follows:
4642 </p><pre class="literallayout">
4643 T = ${WORKDIR}/temp
4644 </pre><p>
4645 The <a class="link" href="#var-WORKDIR" title="WORKDIR"><code class="filename">WORKDIR</code></a>
4646 is the directory into which Bitbake unpacks and builds the package.
4647 The default <code class="filename">bitbake.conf</code> file sets this variable.</p><p>The <code class="filename">T</code> variable is not to be confused with
4648 the <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> variable,
4649 which points to the root of the directory tree where Bitbake
4650 places the output of an entire build.
4651 </p></dd><dt><a id="var-TARGET_ARCH"></a>TARGET_ARCH</dt><dd><p>The architecture of the device being built.
4652 While a number of values are possible, the OpenEmbedded build system primarily supports
4653 <code class="filename">arm</code> and <code class="filename">i586</code>.</p></dd><dt><a id="var-TARGET_CFLAGS"></a>TARGET_CFLAGS</dt><dd><p>
4654 Flags passed to the C compiler for the target system.
4655 This variable evaluates to the same as
4656 <code class="filename"><a class="link" href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></code>.
4657 </p></dd><dt><a id="var-TARGET_FPU"></a>TARGET_FPU</dt><dd><p>Specifies the method for handling FPU code.
4658 For FPU-less targets, which include most ARM CPUs, the variable must be
4659 set to "soft".
4660 If not, the kernel emulation gets used, which results in a performance penalty.</p></dd><dt><a id="var-TARGET_OS"></a>TARGET_OS</dt><dd><p>Specifies the target's operating system.
4661 The variable can be set to "linux" for <code class="filename">eglibc</code>-based systems and
4662 to "linux-uclibc" for <code class="filename">uclibc</code>.
4663 For ARM/EABI targets, there are also "linux-gnueabi" and
4664 "linux-uclibc-gnueabi" values possible.</p></dd><dt><a id="var-TCLIBC"></a>TCLIBC</dt><dd><p>
4665 Specifies which variant of the GNU standard C library (<code class="filename">libc</code>)
4666 to use during the build process.
4667 This variable replaces <code class="filename">POKYLIBC</code>, which is no longer
4668 supported.
4669 </p><p>
4670 You can select <code class="filename">eglibc</code> or <code class="filename">uclibc</code>.
4671 </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
4672 This release of the Yocto Project does not support the
4673 <code class="filename">glibc</code> implementation of <code class="filename">libc</code>.
4674 </div><p>
4675 </p></dd><dt><a id="var-TCMODE"></a>TCMODE</dt><dd><p>
4676 The toolchain selector.
4677 This variable replaces <code class="filename">POKYMODE</code>, which is no longer
4678 supported.
4679 </p><p>
4680 The <code class="filename">TCMODE</code> variable selects the external toolchain
4681 built using the OpenEmbedded build system or a few supported combinations of
4682 the upstream GCC or CodeSourcery Labs toolchain.
4683 The variable identifies the <code class="filename">tcmode-*</code> files used in
4684 the <code class="filename">meta/conf/distro/include</code> directory, which is found in the
4685 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
4686 </p><p>
4687 By default, <code class="filename">TCMODE</code> is set to "default", which
4688 chooses the <code class="filename">tcmode-default.inc</code> file.
4689 The variable is similar to
4690 <a class="link" href="#var-TCLIBC" title="TCLIBC"><code class="filename">TCLIBC</code></a>, which controls
4691 the variant of the GNU standard C library (<code class="filename">libc</code>)
4692 used during the build process: <code class="filename">eglibc</code> or <code class="filename">uclibc</code>.
4693 </p></dd><dt><a id="var-TMPDIR"></a>TMPDIR</dt><dd><p>
4694 This variable is the temporary directory the OpenEmbedded build system
4695 uses when it does its work building images.
4696 By default, the <code class="filename">TMPDIR</code> variable is named
4697 <code class="filename">tmp</code> within the
4698 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
4699 </p><p>
4700 If you want to establish this directory in a location other than the
4701 default, you can uncomment the following statement in the
4702 <code class="filename">conf/local.conf</code> file in the
4703 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>:
4704 </p><pre class="literallayout">
4705 #TMPDIR = "${TOPDIR}/tmp"
4706 </pre><p>
4707 </p></dd><dt><a id="var-TOPDIR"></a>TOPDIR</dt><dd><p>
4708 This variable is the
4709 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>.
4710 BitBake automatically sets this variable.
4711 The OpenEmbedded build system uses the Build Directory when building images.
4712 </p></dd></dl></div><div class="glossdiv" title="W"><h3 class="title">W</h3><dl><dt><a id="var-WORKDIR"></a>WORKDIR</dt><dd><p>
4713 The pathname of the working directory in which the OpenEmbedded build system
4714 builds a recipe.
4715 This directory is located within the
4716 <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a> directory structure and changes
4717 as different packages are built.
4718 </p><p>
4719 The actual <code class="filename">WORKDIR</code> directory depends on several things:
4720 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">The temporary directory - <a class="link" href="#var-TMPDIR" title="TMPDIR"><code class="filename">TMPDIR</code></a></li><li class="listitem">The package architecture - <a class="link" href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH"><code class="filename">PACKAGE_ARCH</code></a></li><li class="listitem">The target machine - <a class="link" href="#var-MACHINE" title="MACHINE"><code class="filename">MACHINE</code></a></li><li class="listitem">The target operating system - <a class="link" href="#var-TARGET_OS" title="TARGET_OS"><code class="filename">TARGET_OS</code></a></li><li class="listitem">The recipe name - <a class="link" href="#var-PN" title="PN"><code class="filename">PN</code></a></li><li class="listitem">The recipe version - <a class="link" href="#var-PV" title="PV"><code class="filename">PV</code></a></li><li class="listitem">The recipe revision - <a class="link" href="#var-PR" title="PR"><code class="filename">PR</code></a></li></ul></div><p>
4721 </p><p>
4722 For packages that are not dependent on a particular machine,
4723 <code class="filename">WORKDIR</code> is defined as follows:
4724 </p><pre class="literallayout">
4725 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
4726 </pre><p>
4727 As an example, assume a
4728 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a> top-level
4729 folder name <code class="filename">poky</code> and a default
4730 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">Build Directory</a>
4731 at <code class="filename">poky/build</code>.
4732 In this case, the working directory the build system uses to build
4733 the <code class="filename">v86d</code> package is the following:
4734 </p><pre class="literallayout">
4735 ~/poky/build/tmp/work/qemux86-poky-linux/v86d/01.9-r0
4736 </pre><p>
4737 </p><p>
4738 For packages that are dependent on a particular machine, <code class="filename">WORKDIR</code>
4739 is defined slightly different:
4740 </p><pre class="literallayout">
4741 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
4742 </pre><p>
4743 As an example, again assume a Source Directory top-level folder
4744 named <code class="filename">poky</code> and a default Build Directory
4745 at <code class="filename">poky/build</code>.
4746 In this case, the working directory the build system uses to build
4747 the <code class="filename">acl</code> recipe, which is being built for a
4748 MIPS-based device, is the following:
4749 </p><pre class="literallayout">
4750 ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2
4751 </pre><p>
4752 </p></dd></dl></div></div></div>
4753
4754 <div class="chapter" title="Chapter 11. Variable Context"><div class="titlepage"><div><div><h2 class="title"><a id="ref-varlocality"></a>Chapter 11. Variable Context</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#ref-varlocality-configuration">11.1. Configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">11.1.1. Distribution (Distro)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">11.1.2. Machine</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">11.1.3. Local</a></span></dt></dl></dd><dt><span class="section"><a href="#ref-varlocality-recipes">11.2. Recipes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-recipe-required">11.2.1. Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">11.2.2. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">11.2.3. Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">11.2.4. Extra Build Information</a></span></dt></dl></dd></dl></div><p>
4755 While most variables can be used in almost any context such as
4756 <code class="filename">.conf</code>, <code class="filename">.bbclass</code>,
4757 <code class="filename">.inc</code>, and <code class="filename">.bb</code> files,
4758 some variables are often associated with a particular locality or context.
4759 This chapter describes some common associations.
4760 </p><div class="section" title="11.1. Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-varlocality-configuration"></a>11.1. Configuration</h2></div></div></div><p>
4761 The following subsections provide lists of variables whose context is
4762 configuration: distribution, machine, and local.
4763 </p><div class="section" title="11.1.1. Distribution (Distro)"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-distro"></a>11.1.1. Distribution (Distro)</h3></div></div></div><p>
4764 This section lists variables whose context is the distribution, or distro.
4765 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO_NAME" title="DISTRO_NAME">DISTRO_NAME</a></code>
4766 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO_VERSION" title="DISTRO_VERSION">DISTRO_VERSION</a>
4767 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MAINTAINER" title="MAINTAINER">MAINTAINER</a></code>
4768 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a>
4769 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_OS" title="TARGET_OS">TARGET_OS</a></code>
4770 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_FPU" title="TARGET_FPU">TARGET_FPU</a></code>
4771 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TCMODE" title="TCMODE">TCMODE</a></code>
4772 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-TCLIBC" title="TCLIBC">TCLIBC</a></code>
4773 </p></li></ul></div><p>
4774 </p></div><div class="section" title="11.1.2. Machine"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-machine"></a>11.1.2. Machine</h3></div></div></div><p>
4775 This section lists variables whose context is the machine.
4776 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-TARGET_ARCH" title="TARGET_ARCH">TARGET_ARCH</a></code>
4777 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE</a>
4778 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_EXTRA_ARCHS" title="PACKAGE_EXTRA_ARCHS">PACKAGE_EXTRA_ARCHS</a>
4779 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a>
4780 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a>
4781 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS
4782 </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMENDS">MACHINE_EXTRA_RRECOMMENDS
4783 </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS" title="MACHINE_ESSENTIAL_EXTRA_RDEPENDS">MACHINE_ESSENTIAL_EXTRA_RDEPENDS
4784 </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS" title="MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS">
4785 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</a></code></p></li></ul></div><p>
4786 </p></div><div class="section" title="11.1.3. Local"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-config-local"></a>11.1.3. Local</h3></div></div></div><p>
4787 This section lists variables whose context is the local configuration through the
4788 <code class="filename">local.conf</code> file.
4789 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DISTRO" title="DISTRO">DISTRO</a></code>
4790 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-MACHINE" title="MACHINE">MACHINE</a></code>
4791 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></code>
4792 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BBFILES" title="BBFILES">BBFILES</a></code>
4793 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_IMAGE_FEATURES" title="EXTRA_IMAGE_FEATURES">EXTRA_IMAGE_FEATURES
4794 </a></code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a>
4795 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a>
4796 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-BBINCLUDELOGS" title="BBINCLUDELOGS">BBINCLUDELOGS</a>
4797 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">
4798 ENABLE_BINARY_LOCALE_GENERATION</a></code></p></li></ul></div><p>
4799 </p></div></div><div class="section" title="11.2. Recipes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ref-varlocality-recipes"></a>11.2. Recipes</h2></div></div></div><p>
4800 The following subsections provide lists of variables whose context is
4801 recipes: required, dependencies, path, and extra build information.
4802 </p><div class="section" title="11.2.1. Required"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-required"></a>11.2.1. Required</h3></div></div></div><p>
4803 This section lists variables that are required for recipes.
4804 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-LICENSE" title="LICENSE">LICENSE</a>
4805 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-LIC_FILES_CHKSUM" title="LIC_FILES_CHKSUM">LIC_FILES_CHKSUM</a>
4806 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></code> - used
4807 in recipes that fetch local or remote files.
4808 </p></li></ul></div><p>
4809 </p></div><div class="section" title="11.2.2. Dependencies"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-dependencies"></a>11.2.2. Dependencies</h3></div></div></div><p>
4810 This section lists variables that define recipe dependencies.
4811 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-DEPENDS" title="DEPENDS">DEPENDS</a>
4812 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a>
4813 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RRECOMMENDS" title="RRECOMMENDS">RRECOMMENDS</a>
4814 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RCONFLICTS" title="RCONFLICTS">RCONFLICTS</a>
4815 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-RREPLACES" title="RREPLACES">RREPLACES</a>
4816 </code></p></li></ul></div><p>
4817 </p></div><div class="section" title="11.2.3. Paths"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-paths"></a>11.2.3. Paths</h3></div></div></div><p>
4818 This section lists variables that define recipe paths.
4819 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-WORKDIR" title="WORKDIR">WORKDIR</a>
4820 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-S" title="S">S</a>
4821 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-FILES" title="FILES">FILES</a>
4822 </code></p></li></ul></div><p>
4823 </p></div><div class="section" title="11.2.4. Extra Build Information"><div class="titlepage"><div><div><h3 class="title"><a id="ref-varlocality-recipe-build"></a>11.2.4. Extra Build Information</h3></div></div></div><p>
4824 This section lists variables that define extra build information for recipes.
4825 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OECMAKE" title="EXTRA_OECMAKE">EXTRA_OECMAKE</a>
4826 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a>
4827 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a>
4828 </code></p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></code>
4829 </p></li><li class="listitem"><p><code class="filename"><a class="link" href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE
4830 </a></code></p></li></ul></div><p>
4831 </p></div></div></div>
4832
4833 <div class="chapter" title="Chapter 12. FAQ"><div class="titlepage"><div><div><h2 class="title"><a id="faq"></a>Chapter 12. FAQ</h2></div></div></div><div class="qandaset" title="Frequently Asked Questions"><a id="idm975296"></a><dl><dt>12.1. <a href="#idm974832">
4834 How does Poky differ from OpenEmbedded?
4835 </a></dt><dt>12.2. <a href="#idp1801248">
4836 I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
4837 Can I still use the Yocto Project?
4838 </a></dt><dt>12.3. <a href="#idm1781424">
4839 How can you claim Poky / OpenEmbedded-Core is stable?
4840 </a></dt><dt>12.4. <a href="#idm1777456">
4841 How do I get support for my board added to the Yocto Project?
4842 </a></dt><dt>12.5. <a href="#idm345792">
4843 Are there any products built using the OpenEmbedded build system?
4844 </a></dt><dt>12.6. <a href="#idm343136">
4845 What does the OpenEmbedded build system produce as output?
4846 </a></dt><dt>12.7. <a href="#idm341840">
4847 How do I add my package to the Yocto Project?
4848 </a></dt><dt>12.8. <a href="#idp1600368">
4849 Do I have to reflash my entire board with a new Yocto Project image when recompiling
4850 a package?
4851 </a></dt><dt>12.9. <a href="#idp1603824">
4852 What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
4853 </a></dt><dt>12.10. <a href="#idp1605872">
4854 I see the error 'chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x'.
4855 What is wrong?
4856 </a></dt><dt>12.11. <a href="#idp1662416">
4857 How do I make the Yocto Project work in RHEL/CentOS?
4858 </a></dt><dt>12.12. <a href="#idp562304">
4859 I see lots of 404 responses for files on
4860 http://www.yoctoproject.org/sources/*. Is something wrong?
4861 </a></dt><dt>12.13. <a href="#idp179952">
4862 I have machine-specific data in a package for one machine only but the package is
4863 being marked as machine-specific in all cases, how do I prevent this?
4864 </a></dt><dt>12.14. <a href="#idp184672">
4865 I'm behind a firewall and need to use a proxy server. How do I do that?
4866 </a></dt><dt>12.15. <a href="#idp1585952">
4867 What’s the difference between foo and foo-native?
4868 </a></dt><dt>12.16. <a href="#idp3269536">
4869 I'm seeing random build failures. Help?!
4870 </a></dt><dt>12.17. <a href="#idp3271104">
4871 What do we need to ship for license compliance?
4872 </a></dt><dt>12.18. <a href="#idp3272560">
4873 How do I disable the cursor on my touchscreen device?
4874 </a></dt><dt>12.19. <a href="#idp3244640">
4875 How do I make sure connected network interfaces are brought up by default?
4876 </a></dt><dt>12.20. <a href="#idp3248256">
4877 How do I create images with more free space?
4878 </a></dt><dt>12.21. <a href="#idp348464">
4879 Why don't you support directories with spaces in the pathnames?
4880 </a></dt><dt>12.22. <a href="#idp350512">
4881 How do I use an external toolchain?
4882 </a></dt><dt>12.23. <a href="#idm184288">
4883 How does the OpenEmbedded build system obtain source code and will it work behind my
4884 firewall or proxy server?
4885 </a></dt><dt>12.24. <a href="#idm1036560">
4886 Can I get rid of build output so I can start over?
4887 </a></dt></dl><table border="0" width="100%" summary="Q and A Set"><col align="left" width="1%" /><col /><tbody><tr class="question" title="12.1."><td align="left" valign="top"><a id="idm974832"></a><a id="idm974704"></a><p><strong>12.1.</strong></p></td><td align="left" valign="top"><p>
4888 How does Poky differ from <a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>?
4889 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4890 The term "Poky" refers to the specific reference build system that
4891 the Yocto Project provides.
4892 Poky is based on <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#oe-core" target="_top">OE-Core</a>
4893 and BitBake.
4894 Thus, the generic term used here for the build system is
4895 the "OpenEmbedded build system."
4896 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
4897 changes always being merged to OE-Core or BitBake first before being pulled back
4898 into Poky.
4899 This practice benefits both projects immediately.
4900 For a fuller description of the term "Poky", see the
4901 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#poky" target="_top">poky</a> term in the Yocto Project
4902 Development Manual.
4903 </p></td></tr><tr class="question" title="12.2."><td align="left" valign="top"><a id="idp1801248"></a><a id="idp1801376"></a><p><strong>12.2.</strong></p></td><td align="left" valign="top"><p>
4904 I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
4905 Can I still use the Yocto Project?
4906 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4907 You can use a stand-alone tarball to provide Python 2.6.
4908 You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations:
4909 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://downloads.yoctoproject.org/releases/miscsupport/python-nativesdk-standalone-i686.tar.bz2" target="_top">32-bit tarball</a></p></li><li class="listitem"><p><a class="ulink" href="http://downloads.yoctoproject.org/releases/miscsupport/python-nativesdk-standalone-x86_64.tar.bz2" target="_top">64-bit tarball</a></p></li></ul></div><p>
4910 </p><p>
4911 These tarballs are self-contained with all required libraries and should work
4912 on most Linux systems.
4913 To use the tarballs extract them into the root
4914 directory and run the appropriate command:
4915 </p><pre class="literallayout">
4916 $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH
4917 $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH
4918 </pre><p>
4919 </p><p>
4920 Once you run the command, BitBake uses Python 2.6.
4921 </p></td></tr><tr class="question" title="12.3."><td align="left" valign="top"><a id="idm1781424"></a><a id="idm1781296"></a><p><strong>12.3.</strong></p></td><td align="left" valign="top"><p>
4922 How can you claim Poky / OpenEmbedded-Core is stable?
4923 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4924 There are three areas that help with stability;
4925 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The Yocto Project team keeps
4926 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#oe-core" target="_top">OE-Core</a> small
4927 and focused, containing around 830 recipes as opposed to the thousands
4928 available in other OpenEmbedded community layers.
4929 Keeping it small makes it easy to test and maintain.</p></li><li class="listitem"><p>The Yocto Project team runs manual and automated tests
4930 using a small, fixed set of reference hardware as well as emulated
4931 targets.</p></li><li class="listitem"><p>The Yocto Project uses an an autobuilder,
4932 which provides continuous build and integration tests.</p></li></ul></div><p>
4933 </p></td></tr><tr class="question" title="12.4."><td align="left" valign="top"><a id="idm1777456"></a><a id="idm1777328"></a><p><strong>12.4.</strong></p></td><td align="left" valign="top"><p>
4934 How do I get support for my board added to the Yocto Project?
4935 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4936 Support for an additional board is added by creating a BSP layer for it.
4937 For more information on how to create a BSP layer, see the
4938 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/bsp-guide/bsp-guide.html" target="_top">Yocto Project Board Support Package (BSP) Developer's Guide</a>.
4939 </p><p>
4940 Usually, if the board is not completely exotic, adding support in
4941 the Yocto Project is fairly straightforward.
4942 </p></td></tr><tr class="question" title="12.5."><td align="left" valign="top"><a id="idm345792"></a><a id="idm345664"></a><p><strong>12.5.</strong></p></td><td align="left" valign="top"><p>
4943 Are there any products built using the OpenEmbedded build system?
4944 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4945 The software running on the <a class="ulink" href="http://vernier.com/labquest/" target="_top">Vernier LabQuest</a>
4946 is built using the OpenEmbedded build system.
4947 See the <a class="ulink" href="http://www.vernier.com/products/interfaces/labq/" target="_top">Vernier LabQuest</a>
4948 website for more information.
4949 There are a number of pre-production devices using the OpenEmbedded build system
4950 and the Yocto Project team
4951 announces them as soon as they are released.
4952 </p></td></tr><tr class="question" title="12.6."><td align="left" valign="top"><a id="idm343136"></a><a id="idm343008"></a><p><strong>12.6.</strong></p></td><td align="left" valign="top"><p>
4953 What does the OpenEmbedded build system produce as output?
4954 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4955 Because the same set of recipes can be used to create output of various formats, the
4956 output of an OpenEmbedded build depends on how it was started.
4957 Usually, the output is a flashable image ready for the target device.
4958 </p></td></tr><tr class="question" title="12.7."><td align="left" valign="top"><a id="idm341840"></a><a id="idm341712"></a><p><strong>12.7.</strong></p></td><td align="left" valign="top"><p>
4959 How do I add my package to the Yocto Project?
4960 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4961 To add a package, you need to create a BitBake recipe.
4962 For information on how to add a package, see the section
4963 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#usingpoky-extend-addpkg" target="_top">Adding a Package</a>"
4964 in the Yocto Project Development Manual.
4965 </p></td></tr><tr class="question" title="12.8."><td align="left" valign="top"><a id="idp1600368"></a><a id="idp1600496"></a><p><strong>12.8.</strong></p></td><td align="left" valign="top"><p>
4966 Do I have to reflash my entire board with a new Yocto Project image when recompiling
4967 a package?
4968 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4969 The OpenEmbedded build system can build packages in various formats such as
4970 <code class="filename">ipk</code> for <code class="filename">opkg</code>,
4971 Debian package (<code class="filename">.deb</code>), or RPM.
4972 The packages can then be upgraded using the package tools on the device, much like
4973 on a desktop distribution such as Ubuntu or Fedora.
4974 </p></td></tr><tr class="question" title="12.9."><td align="left" valign="top"><a id="idp1603824"></a><a id="idp1603952"></a><p><strong>12.9.</strong></p></td><td align="left" valign="top"><p>
4975 What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
4976 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4977 GNOME Mobile is a subset of the <a class="ulink" href="http://www.gnome.org" target="_top">GNOME</a>
4978 platform targeted at mobile and embedded devices.
4979 The the main difference between GNOME Mobile and standard GNOME is that
4980 desktop-orientated libraries have been removed, along with deprecated libraries,
4981 creating a much smaller footprint.
4982 </p></td></tr><tr class="question" title="12.10."><td align="left" valign="top"><a id="idp1605872"></a><a id="idp1606000"></a><p><strong>12.10.</strong></p></td><td align="left" valign="top"><p>
4983 I see the error '<code class="filename">chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</code>'.
4984 What is wrong?
4985 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4986 You are probably running the build on an NTFS filesystem.
4987 Use <code class="filename">ext2</code>, <code class="filename">ext3</code>, or <code class="filename">ext4</code> instead.
4988 </p></td></tr><tr class="question" title="12.11."><td align="left" valign="top"><a id="idp1662416"></a><a id="idp1662544"></a><p><strong>12.11.</strong></p></td><td align="left" valign="top"><p>
4989 How do I make the Yocto Project work in RHEL/CentOS?
4990 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
4991 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
4992 install some required packages.
4993 The standard CentOS packages needed are:
4994 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>"Development tools" (selected during installation)</p></li><li class="listitem"><p><code class="filename">texi2html</code></p></li><li class="listitem"><p><code class="filename">compat-gcc-34</code></p></li></ul></div><p>
4995 On top of these, you need the following external packages:
4996 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">python-sqlite2</code> from
4997 <a class="ulink" href="http://dag.wieers.com/rpm/packages/python-sqlite2/" target="_top">DAG repository</a>
4998 </p></li><li class="listitem"><p><code class="filename">help2man</code> from
4999 <a class="ulink" href="http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html" target="_top">Karan repository</a></p></li></ul></div><p>
5000 </p><p>
5001 Once these packages are installed, the OpenEmbedded build system will be able
5002 to build standard images.
5003 However, there might be a problem with the QEMU emulator segfaulting.
5004 You can either disable the generation of binary locales by setting
5005 <code class="filename"><a class="link" href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">ENABLE_BINARY_LOCALE_GENERATION</a>
5006 </code> to "0" or by removing the <code class="filename">linux-2.6-execshield.patch</code>
5007 from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
5008 </p></td></tr><tr class="question" title="12.12."><td align="left" valign="top"><a id="idp562304"></a><a id="idp562432"></a><p><strong>12.12.</strong></p></td><td align="left" valign="top"><p>
5009 I see lots of 404 responses for files on
5010 <code class="filename">http://www.yoctoproject.org/sources/*</code>. Is something wrong?
5011 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5012 Nothing is wrong.
5013 The OpenEmbedded build system checks any configured source mirrors before downloading
5014 from the upstream sources.
5015 The build system does this searching for both source archives and
5016 pre-checked out versions of SCM managed software.
5017 These checks help in large installations because it can reduce load on the SCM servers
5018 themselves.
5019 The address above is one of the default mirrors configured into the
5020 build system.
5021 Consequently, if an upstream source disappears, the team
5022 can place sources there so builds continue to work.
5023 </p></td></tr><tr class="question" title="12.13."><td align="left" valign="top"><a id="idp179952"></a><a id="idp180080"></a><p><strong>12.13.</strong></p></td><td align="left" valign="top"><p>
5024 I have machine-specific data in a package for one machine only but the package is
5025 being marked as machine-specific in all cases, how do I prevent this?
5026 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5027 Set <code class="filename"><a class="link" href="#var-SRC_URI_OVERRIDES_PACKAGE_ARCH" title="SRC_URI_OVERRIDES_PACKAGE_ARCH">SRC_URI_OVERRIDES_PACKAGE_ARCH</a>
5028 </code> = "0" in the <code class="filename">.bb</code> file but make sure the package is
5029 manually marked as
5030 machine-specific in the case that needs it.
5031 The code that handles <code class="filename">SRC_URI_OVERRIDES_PACKAGE_ARCH</code> is in <code class="filename">base.bbclass</code>.
5032 </p></td></tr><tr class="question" title="12.14."><td align="left" valign="top"><a id="idp184672"></a><a id="idp1581568"></a><p><strong>12.14.</strong></p></td><td align="left" valign="top"><p>
5033 I'm behind a firewall and need to use a proxy server. How do I do that?
5034 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5035 Most source fetching by the OpenEmbedded build system is done by <code class="filename">wget</code>
5036 and you therefore need to specify the proxy settings in a
5037 <code class="filename">.wgetrc</code> file in your home directory.
5038 Example settings in that file would be
5039 </p><pre class="literallayout">
5040 http_proxy = http://proxy.yoyodyne.com:18023/
5041 ftp_proxy = http://proxy.yoyodyne.com:18023/
5042 </pre><p>
5043 The Yocto Project also includes a <code class="filename">site.conf.sample</code>
5044 file that shows how to configure CVS and Git proxy servers
5045 if needed.
5046 </p></td></tr><tr class="question" title="12.15."><td align="left" valign="top"><a id="idp1585952"></a><a id="idp1586080"></a><p><strong>12.15.</strong></p></td><td align="left" valign="top"><p>
5047 What’s the difference between <code class="filename">foo</code> and <code class="filename">foo-native</code>?
5048 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5049 The <code class="filename">*-native</code> targets are designed to run on the system
5050 being used for the build.
5051 These are usually tools that are needed to assist the build in some way such as
5052 <code class="filename">quilt-native</code>, which is used to apply patches.
5053 The non-native version is the one that runs on the target device.
5054 </p></td></tr><tr class="question" title="12.16."><td align="left" valign="top"><a id="idp3269536"></a><a id="idp3269664"></a><p><strong>12.16.</strong></p></td><td align="left" valign="top"><p>
5055 I'm seeing random build failures. Help?!
5056 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5057 If the same build is failing in totally different and random ways,
5058 the most likely explanation is that either the hardware you're running the
5059 build on has some problem, or, if you are running the build under virtualisation,
5060 the virtualisation probably has bugs.
5061 The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and
5062 CPU activity and is sensitive to even single bit failures in any of these areas.
5063 True random failures have always been traced back to hardware or virtualisation issues.
5064 </p></td></tr><tr class="question" title="12.17."><td align="left" valign="top"><a id="idp3271104"></a><a id="idp3271232"></a><p><strong>12.17.</strong></p></td><td align="left" valign="top"><p>
5065 What do we need to ship for license compliance?
5066 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5067 This is a difficult question and you need to consult your lawyer for the answer
5068 for your specific case.
5069 It is worth bearing in mind that for GPL compliance there needs to be enough
5070 information shipped to allow someone else to rebuild the same end result
5071 you are shipping.
5072 This means sharing the source code, any patches applied to it, and also any
5073 configuration information about how that package was configured and built.
5074 </p></td></tr><tr class="question" title="12.18."><td align="left" valign="top"><a id="idp3272560"></a><a id="idp3272688"></a><p><strong>12.18.</strong></p></td><td align="left" valign="top"><p>
5075 How do I disable the cursor on my touchscreen device?
5076 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5077 You need to create a form factor file as described in the
5078 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/bsp-guide/bsp-guide.html#bsp-filelayout-misc-recipes" target="_top">Miscellaneous Recipe Files</a>"
5079 section and set the <code class="filename">HAVE_TOUCHSCREEN</code> variable equal to one as follows:
5080 </p><pre class="literallayout">
5081 HAVE_TOUCHSCREEN=1
5082 </pre><p>
5083 </p></td></tr><tr class="question" title="12.19."><td align="left" valign="top"><a id="idp3244640"></a><a id="idp3244768"></a><p><strong>12.19.</strong></p></td><td align="left" valign="top"><p>
5084 How do I make sure connected network interfaces are brought up by default?
5085 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5086 The default interfaces file provided by the netbase recipe does not
5087 automatically bring up network interfaces.
5088 Therefore, you will need to add a BSP-specific netbase that includes an interfaces
5089 file.
5090 See the "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/bsp-guide/bsp-guide.html#bsp-filelayout-misc-recipes" target="_top">Miscellaneous Recipe Files</a>"
5091 section for information on creating these types of miscellaneous recipe files.
5092 </p><p>
5093 For example, add the following files to your layer:
5094 </p><pre class="literallayout">
5095 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
5096 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
5097 </pre><p>
5098 </p></td></tr><tr class="question" title="12.20."><td align="left" valign="top"><a id="idp3248256"></a><a id="idp3248384"></a><p><strong>12.20.</strong></p></td><td align="left" valign="top"><p>
5099 How do I create images with more free space?
5100 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5101 Images are created to be 1.2 times the size of the populated root filesystem.
5102 To modify this ratio so that there is more free space available, you need to
5103 set the configuration value <code class="filename">IMAGE_OVERHEAD_FACTOR</code>.
5104 For example, setting <code class="filename">IMAGE_OVERHEAD_FACTOR</code> to 1.5 sets
5105 the image size ratio to one and a half times the size of the populated
5106 root filesystem.
5107 </p><pre class="literallayout">
5108 IMAGE_OVERHEAD_FACTOR = "1.5"
5109 </pre><p>
5110 </p></td></tr><tr class="question" title="12.21."><td align="left" valign="top"><a id="idp348464"></a><a id="idp348592"></a><p><strong>12.21.</strong></p></td><td align="left" valign="top"><p>
5111 Why don't you support directories with spaces in the pathnames?
5112 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5113 The Yocto Project team has tried to do this before but too many of the tools
5114 the OpenEmbedded build system depends on such as <code class="filename">autoconf</code>
5115 break when they find spaces in pathnames.
5116 Until that situation changes, the team will not support spaces in pathnames.
5117 </p></td></tr><tr class="question" title="12.22."><td align="left" valign="top"><a id="idp350512"></a><a id="idp350640"></a><p><strong>12.22.</strong></p></td><td align="left" valign="top"><p>
5118 How do I use an external toolchain?
5119 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5120 The toolchain configuration is very flexible and customizable.
5121 It is primarily controlled with the
5122 <code class="filename"><a class="link" href="#var-TCMODE" title="TCMODE">TCMODE</a></code> variable.
5123 This variable controls which <code class="filename">tcmode-*.inc</code> file to include
5124 from the <code class="filename">meta/conf/distro/include</code> directory within the
5125 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">source directory</a>.
5126 </p><p>
5127 The default value of <code class="filename">TCMODE</code> is "default"
5128 (i.e. <code class="filename">tcmode-default.inc</code>).
5129 However, other patterns are accepted.
5130 In particular, "external-*" refers to external toolchains of which there are some
5131 basic examples included in the OpenEmbedded Core (<code class="filename">meta</code>).
5132 You can use your own custom toolchain definition in your own layer
5133 (or as defined in the <code class="filename">local.conf</code> file) at the location
5134 <code class="filename">conf/distro/include/tcmode-*.inc</code>.
5135 </p><p>
5136 In addition to the toolchain configuration, you also need a corresponding toolchain recipe file.
5137 This recipe file needs to package up any pre-built objects in the toolchain such as
5138 <code class="filename">libgcc</code>, <code class="filename">libstdcc++</code>,
5139 any locales, and <code class="filename">libc</code>.
5140 An example is the <code class="filename">external-sourcery-toolchain.bb</code>, which is located
5141 in <code class="filename">meta/recipes-core/meta/</code> within the source directory.
5142 </p></td></tr><tr class="question" title="12.23."><td align="left" valign="top"><a id="idm184288"></a><a id="idm1835680"></a><p><strong>12.23.</strong></p></td><td align="left" valign="top"><p><a id="how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server"></a>
5143 How does the OpenEmbedded build system obtain source code and will it work behind my
5144 firewall or proxy server?
5145 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5146 The way the build system obtains source code is highly configurable.
5147 You can setup the build system to get source code in most environments if
5148 HTTP transport is available.
5149 </p><p>
5150 When the build system searches for source code, it first tries the local download directory.
5151 If that location fails, Poky tries PREMIRRORS, the upstream source,
5152 and then MIRRORS in that order.
5153 </p><p>
5154 By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS
5155 for SCM-based sources,
5156 upstreams for normal tarballs, and then falls back to a number of other mirrors
5157 including the Yocto Project source mirror if those fail.
5158 </p><p>
5159 As an example, you could add a specific server for Poky to attempt before any
5160 others by adding something like the following to the <code class="filename">local.conf</code>
5161 configuration file:
5162 </p><pre class="literallayout">
5163 PREMIRRORS_prepend = "\
5164 git://.*/.* http://www.yoctoproject.org/sources/ \n \
5165 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
5166 http://.*/.* http://www.yoctoproject.org/sources/ \n \
5167 https://.*/.* http://www.yoctoproject.org/sources/ \n"
5168 </pre><p>
5169 </p><p>
5170 These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS
5171 requests and direct them to the <code class="filename">http://</code> sources mirror.
5172 You can use <code class="filename">file://</code> URLs to point to local directories
5173 or network shares as well.
5174 </p><p>
5175 Aside from the previous technique, these options also exist:
5176 </p><pre class="literallayout">
5177 BB_NO_NETWORK = "1"
5178 </pre><p>
5179 This statement tells BitBake to throw an error instead of trying to access the
5180 Internet.
5181 This technique is useful if you want to ensure code builds only from local sources.
5182 </p><p>
5183 Here is another technique:
5184 </p><pre class="literallayout">
5185 BB_FETCH_PREMIRRORONLY = "1"
5186 </pre><p>
5187 This statement limits Poky to pulling source from the PREMIRRORS only.
5188 Again, this technique is useful for reproducing builds.
5189 </p><p>
5190 Here is another technique:
5191 </p><pre class="literallayout">
5192 BB_GENERATE_MIRROR_TARBALLS = "1"
5193 </pre><p>
5194 This statement tells Poky to generate mirror tarballs.
5195 This technique is useful if you want to create a mirror server.
5196 If not, however, the technique can simply waste time during the build.
5197 </p><p>
5198 Finally, consider an example where you are behind an HTTP-only firewall.
5199 You could make the following changes to the <code class="filename">local.conf</code>
5200 configuration file as long as the PREMIRROR server is up to date:
5201 </p><pre class="literallayout">
5202 PREMIRRORS_prepend = "\
5203 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
5204 http://.*/.* http://www.yoctoproject.org/sources/ \n \
5205 https://.*/.* http://www.yoctoproject.org/sources/ \n"
5206 BB_FETCH_PREMIRRORONLY = "1"
5207 </pre><p>
5208 These changes would cause Poky to successfully fetch source over HTTP and
5209 any network accesses to anything other than the PREMIRROR would fail.
5210 </p><p>
5211 The build system also honors the standard shell environment variables
5212 <code class="filename">http_proxy</code>, <code class="filename">ftp_proxy</code>,
5213 <code class="filename">https_proxy</code>, and <code class="filename">all_proxy</code>
5214 to redirect requests through proxy servers.
5215 </p></td></tr><tr class="question" title="12.24."><td align="left" valign="top"><a id="idm1036560"></a><a id="idm1036432"></a><p><strong>12.24.</strong></p></td><td align="left" valign="top"><p>
5216 Can I get rid of build output so I can start over?
5217 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
5218 Yes - you can easily do this.
5219 When you use BitBake to build an image, all the build output goes into the
5220 directory created when you source the <code class="filename">oe-init-build-env</code>
5221 setup file.
5222 By default, this <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#build-directory" target="_top">build directory</a>
5223 is named <code class="filename">build</code> but can be named
5224 anything you want.
5225 </p><p>
5226 Within the build directory is the <code class="filename">tmp</code> directory.
5227 To remove all the build output yet preserve any source code or downloaded files
5228 from previous builds, simply remove the <code class="filename">tmp</code> directory.
5229 </p></td></tr></tbody></table></div></div>
5230
5231 <div class="chapter" title="Chapter 13. Contributing to the Yocto Project"><div class="titlepage"><div><div><h2 class="title"><a id="resources"></a>Chapter 13. Contributing to the Yocto Project</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="#resources-intro">13.1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">13.2. Tracking Bugs</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">13.3. Mailing lists</a></span></dt><dt><span class="section"><a href="#resources-irc">13.4. Internet Relay Chat (IRC)</a></span></dt><dt><span class="section"><a href="#resources-links">13.5. Links</a></span></dt><dt><span class="section"><a href="#resources-contributions">13.6. Contributions</a></span></dt></dl></div><div class="section" title="13.1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-intro"></a>13.1. Introduction</h2></div></div></div><p>
5232 The Yocto Project team is happy for people to experiment with the Yocto Project.
5233 A number of places exist to find help if you run into difficulties or find bugs.
5234 To find out how to download source code,
5235 see the "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#local-yp-release" target="_top">Yocto Project Release</a>"
5236 list item in the Yocto Project Development Manual.
5237 </p></div><div class="section" title="13.2. Tracking Bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-bugtracker"></a>13.2. Tracking Bugs</h2></div></div></div><p>
5238 If you find problems with the Yocto Project, you should report them using the
5239 Bugzilla application at <a class="ulink" href="http://bugzilla.yoctoproject.org" target="_top">http://bugzilla.yoctoproject.org</a>.
5240 </p></div><div class="section" title="13.3. Mailing lists"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-mailinglist"></a>13.3. Mailing lists</h2></div></div></div><p>
5241 There are a number of mailing lists maintained by the Yocto Project as well as
5242 related OpenEmbedded mailing lists for discussion, patch submission and announcements.
5243 To subscribe to one of the following mailing lists, click on the appropriate URL
5244 in the following list and follow the instructions:
5245 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto" target="_top">http://lists.yoctoproject.org/listinfo/yocto</a> -
5246 General Yocto Project discussion mailing list. </p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core</a> -
5247 Discussion mailing list about OpenEmbedded-Core (the core metadata).</p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel</a> -
5248 Discussion mailing list about OpenEmbedded.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel" target="_top">http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/bitbake-devel</a> -
5249 Discussion mailing list about the BitBake build tool.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/poky" target="_top">http://lists.yoctoproject.org/listinfo/poky</a> -
5250 Discussion mailing list about Poky.</p></li><li class="listitem"><p><a class="ulink" href="http://lists.yoctoproject.org/listinfo/yocto-announce" target="_top">http://lists.yoctoproject.org/listinfo/yocto-announce</a> -
5251 Mailing list to receive official Yocto Project release and milestone
5252 announcements.</p></li></ul></div><p>
5253 </p></div><div class="section" title="13.4. Internet Relay Chat (IRC)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-irc"></a>13.4. Internet Relay Chat (IRC)</h2></div></div></div><p>
5254 Two IRC channels on freenode are available for the Yocto Project and Poky discussions:
5255 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="filename">#yocto</code></p></li><li class="listitem"><p><code class="filename">#poky</code></p></li></ul></div><p>
5256 </p></div><div class="section" title="13.5. Links"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-links"></a>13.5. Links</h2></div></div></div><p>
5257 Following is a list of resources you will find helpful:
5258 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.yoctoproject.org" target="_top">The Yocto Project website</a>:
5259 </em></span> The home site for the Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.intel.com/" target="_top">Intel Corporation</a>:</em></span>
5260 The company who acquired OpenedHand in 2008 and began development on the
5261 Yocto Project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://www.openembedded.org" target="_top">OpenEmbedded</a>:</em></span>
5262 The upstream, generic, embedded distribution used as the basis for the build system in the
5263 Yocto Project.
5264 Poky derives from and contributes back to the OpenEmbedded project.</p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://developer.berlios.de/projects/bitbake/" target="_top">
5265 BitBake</a>:</em></span> The tool used to process metadata.</p></li><li class="listitem"><p><span class="emphasis"><em>BitBake User Manual:</em></span>
5266 A comprehensive guide to the BitBake tool.
5267 You can find the BitBake User Manual in the <code class="filename">bitbake/doc/manual</code>
5268 directory, which is found in the
5269 <a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#source-directory" target="_top">Source Directory</a>.
5270 </p></li><li class="listitem"><p><span class="emphasis"><em><a class="ulink" href="http://wiki.qemu.org/Index.html" target="_top">QEMU</a>:
5271 </em></span> An open source machine emulator and virtualizer.</p></li></ul></div><p>
5272 </p></div><div class="section" title="13.6. Contributions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="resources-contributions"></a>13.6. Contributions</h2></div></div></div><p>
5273 The Yocto Project gladly accepts contributions.
5274 You can submit changes to the project either by creating and sending pull requests,
5275 or by submitting patches through email.
5276 For information on how to do both, see the
5277 "<a class="ulink" href="http://www.yoctoproject.org/docs/1.4/dev-manual/dev-manual.html#how-to-submit-a-change" target="_top">How to Submit a Change</a>"
5278 section in the Yocto Project Development Manual.
5279 </p></div></div>
5280
5281
5282
5283</div></body></html>
diff --git a/documentation/ref-manual/ref-manual.pdf b/documentation/ref-manual/ref-manual.pdf
new file mode 100644
index 0000000000..4dd9f7a25f
--- /dev/null
+++ b/documentation/ref-manual/ref-manual.pdf
Binary files differ
diff --git a/documentation/ref-manual/ref-manual.tgz b/documentation/ref-manual/ref-manual.tgz
new file mode 100644
index 0000000000..e4a17c884f
--- /dev/null
+++ b/documentation/ref-manual/ref-manual.tgz
Binary files differ
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 @@
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<book id='ref-manual' lang='en'
6 xmlns:xi="http://www.w3.org/2003/XInclude"
7 xmlns="http://docbook.org/ns/docbook"
8 >
9 <bookinfo>
10
11 <mediaobject>
12 <imageobject>
13 <imagedata fileref='figures/poky-title.png'
14 format='SVG'
15 align='left' scalefit='1' width='100%'/>
16 </imageobject>
17 </mediaobject>
18
19 <title></title>
20
21 <authorgroup>
22 <author>
23 <firstname>Richard</firstname> <surname>Purdie</surname>
24 <affiliation>
25 <orgname>Linux Foundation</orgname>
26 </affiliation>
27 <email>richard.purdie@linuxfoundation.org</email>
28 </author>
29
30 </authorgroup>
31
32 <revhistory>
33 <revision>
34 <revnumber>4.0+git</revnumber>
35 <date>24 November 2010</date>
36 <revremark>Released with the Yocto Project 0.9 Release</revremark>
37 </revision>
38 <revision>
39 <revnumber>1.0</revnumber>
40 <date>6 April 2011</date>
41 <revremark>Released with the Yocto Project 1.0 Release.</revremark>
42 </revision>
43 <revision>
44 <revnumber>1.0.1</revnumber>
45 <date>23 May 2011</date>
46 <revremark>Released with the Yocto Project 1.0.1 Release.</revremark>
47 </revision>
48 <revision>
49 <revnumber>1.1</revnumber>
50 <date>6 October 2011</date>
51 <revremark>Released with the Yocto Project 1.1 Release.</revremark>
52 </revision>
53 <revision>
54 <revnumber>1.2</revnumber>
55 <date>April 2012</date>
56 <revremark>Released with the Yocto Project 1.2 Release.</revremark>
57 </revision>
58 <revision>
59 <revnumber>1.3</revnumber>
60 <date>October 2012</date>
61 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
62 </revision>
63 <revision>
64 <revnumber>1.4</revnumber>
65 <date>Sometime in 2013</date>
66 <revremark>Released with the Yocto Project 1.4 Release.</revremark>
67 </revision>
68 </revhistory>
69
70 <copyright>
71 <year>&COPYRIGHT_YEAR;</year>
72 <holder>Linux Foundation</holder>
73 </copyright>
74
75 <legalnotice>
76 <para>
77 Permission is granted to copy, distribute and/or modify this document under
78 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 &amp; Wales</ulink> as published by Creative Commons.
79 </para>
80 <note>
81 Due to production processes, there could be differences between the Yocto Project
82 documentation bundled in the release tarball and the
83 <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink> on
84 the <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
85 For the latest version of this manual, see the manual on the website.
86 </note>
87 </legalnotice>
88
89 </bookinfo>
90
91 <xi:include href="introduction.xml"/>
92
93 <xi:include href="usingpoky.xml"/>
94
95 <xi:include href="technical-details.xml"/>
96
97 <xi:include href="migration.xml"/>
98
99 <xi:include href="ref-structure.xml"/>
100
101 <xi:include href="ref-bitbake.xml"/>
102
103 <xi:include href="ref-classes.xml"/>
104
105 <xi:include href="ref-images.xml"/>
106
107 <xi:include href="ref-features.xml"/>
108
109 <xi:include href="ref-variables.xml"/>
110
111 <xi:include href="ref-varlocality.xml"/>
112
113 <xi:include href="faq.xml"/>
114
115 <xi:include href="resources.xml"/>
116
117<!-- <index id='index'>
118 <title>Index</title>
119 </index>
120-->
121
122</book>
123<!--
124vim: expandtab tw=80 ts=4
125-->
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-structure'>
6
7<title>Source Directory Structure</title>
8
9<para>
10 The <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> consists of several components.
11 Understanding them and knowing where they are located is key to using the Yocto Project well.
12 This chapter describes the Source Directory and gives information about the various
13 files and directories.
14</para>
15
16<para>
17 For information on how to establish a local Source Directory on your development system, see the
18 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
19 section in the Yocto Project Development Manual.
20</para>
21
22<note>
23 The OpenEmbedded build system does not support file or directory names that
24 contain spaces.
25 Be sure that the Source Directory you use does not contain these types
26 of names.
27</note>
28
29<section id='structure-core'>
30 <title>Top level core components</title>
31
32 <section id='structure-core-bitbake'>
33 <title><filename>bitbake/</filename></title>
34
35 <para>
36 The <ulink url='source-directory'>Source Directory</ulink>
37 includes a copy of BitBake for ease of use.
38 The copy usually matches the current stable BitBake release from the BitBake project.
39 BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks
40 defined by that data.
41 Failures are usually from the metadata and not from BitBake itself.
42 Consequently, most users do not need to worry about BitBake.
43 </para>
44
45 <para>
46 When you run the <filename>bitbake</filename> command, the wrapper script in
47 <filename>scripts/</filename> is executed to run the main BitBake executable,
48 which resides in the <filename>bitbake/bin/</filename> directory.
49 Sourcing the <link linkend="structure-core-script">&OE_INIT_FILE;</link>
50 script places the <filename>scripts</filename> and <filename>bitbake/bin</filename>
51 directories (in that order) into the shell's <filename>PATH</filename> environment
52 variable.
53 </para>
54
55 <para>
56 For more information on BitBake, see the BitBake documentation
57 inculded in the <filename>bitbake/doc/manual</filename> directory of the
58 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
59 </para>
60 </section>
61
62 <section id='structure-core-build'>
63 <title><filename>build/</filename></title>
64
65 <para>
66 This directory contains user configuration files and the output
67 generated by the OpenEmbedded build system in its standard configuration where
68 the source tree is combined with the output.
69 The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
70 is created initially when you <filename>source</filename>
71 the OpenEmbedded build environment setup script <filename>&OE_INIT_FILE;</filename>.
72 </para>
73
74 <para>
75 It is also possible to place output and configuration
76 files in a directory separate from the
77 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
78 by providing a directory name when you <filename>source</filename>
79 the setup script.
80 For information on separating output from your local Source Directory files, see <link
81 linkend='structure-core-script'>&OE_INIT_FILE;</link>.
82 </para>
83 </section>
84
85 <section id='handbook'>
86 <title><filename>documentation</filename></title>
87
88 <para>
89 This directory holds the source for the Yocto Project documentation
90 as well as templates and tools that allow you to generate PDF and HTML
91 versions of the manuals.
92 Each manual is contained in a sub-folder.
93 For example, the files for this manual reside in
94 <filename>ref-manual</filename>.
95 </para>
96 </section>
97
98 <section id='structure-core-meta'>
99 <title><filename>meta/</filename></title>
100
101 <para>
102 This directory contains the OpenEmbedded Core metadata.
103 The directory holds recipes, common classes, and machine
104 configuration for emulated targets (qemux86, qemuarm,
105 and so on.)
106 </para>
107 </section>
108
109 <section id='structure-core-meta-yocto'>
110 <title><filename>meta-yocto/</filename></title>
111
112 <para>
113 This directory contains the configuration for the Poky
114 reference distribution.
115 </para>
116 </section>
117
118 <section id='structure-core-meta-yocto-bsp'>
119 <title><filename>meta-yocto-bsp/</filename></title>
120
121 <para>
122 This directory contains the Yocto Project reference
123 hardware BSPs.
124 </para>
125 </section>
126
127 <section id='structure-meta-hob'>
128 <title><filename>meta-hob/</filename></title>
129
130 <para>
131 This directory contains template recipes used by the
132 <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink>
133 build UI.
134 </para>
135 </section>
136
137 <section id='structure-meta-skeleton'>
138 <title><filename>meta-skeleton/</filename></title>
139
140 <para>
141 This directory contains template recipes for BSP and kernel development.
142 </para>
143 </section>
144
145 <section id='structure-core-scripts'>
146 <title><filename>scripts/</filename></title>
147
148 <para>
149 This directory contains various integration scripts that implement
150 extra functionality in the Yocto Project environment (e.g. QEMU scripts).
151 The <link linkend="structure-core-script">&OE_INIT_FILE;</link> script appends this
152 directory to the shell's <filename>PATH</filename> environment variable.
153 </para>
154
155 <para>
156 The <filename>scripts</filename> directory has useful scripts that assist contributing
157 back to the Yocto Project, such as <filename>create_pull_request</filename> and
158 <filename>send_pull_request</filename>.
159 </para>
160 </section>
161
162 <section id='structure-core-script'>
163 <title><filename>&OE_INIT_FILE;</filename></title>
164
165 <para>
166 This script sets up the OpenEmbedded build environment.
167 Running this script with the <filename>source</filename> command in
168 a shell makes changes to <filename>PATH</filename> and sets other core BitBake variables based on the
169 current working directory.
170 You need to run this script before running BitBake commands.
171 The script uses other scripts within the <filename>scripts</filename> directory to do
172 the bulk of the work.
173 </para>
174
175 <para>
176 By default, running this script without a Build Directory argument creates the
177 <filename>build</filename> directory.
178 If you provide a Build Directory argument when you <filename>source</filename>
179 the script, you direct OpenEmbedded build system to create a
180 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> of your choice.
181 For example, the following command creates a Build Directory named
182 <filename>mybuilds</filename> that is outside of the
183 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
184 <literallayout class='monospaced'>
185 $ source &OE_INIT_FILE; ~/mybuilds
186 </literallayout>
187 <note>
188 The OpenEmbedded build system does not support file or directory names that
189 contain spaces.
190 If you attempt to run the <filename>&OE_INIT_FILE;</filename> script
191 from a Source Directory that contains spaces in either the filenames
192 or directory names, the script returns an error indicating no such
193 file or directory.
194 Be sure to use a Source Directory free of names containing spaces.
195 </note>
196 </para>
197 </section>
198
199 <section id='structure-basic-top-level'>
200 <title><filename>LICENSE, README, and README.hardware</filename></title>
201
202 <para>
203 These files are standard top-level files.
204 </para>
205 </section>
206</section>
207
208<section id='structure-build'>
209 <title>The Build Directory - <filename>build/</filename></title>
210
211 <section id='structure-build-pseudodone'>
212 <title><filename>build/pseudodone</filename></title>
213
214 <para>
215 This tag file indicates that the initial pseudo binary was created.
216 The file is built the first time BitBake is invoked.
217 </para>
218 </section>
219
220 <section id='structure-build-conf-local.conf'>
221 <title><filename>build/conf/local.conf</filename></title>
222
223 <para>
224 This file contains all the local user configuration for your build environment.
225 If there is no <filename>local.conf</filename> present, it is created from
226 <filename>local.conf.sample</filename>.
227 The <filename>local.conf</filename> file contains documentation on the various configuration options.
228 Any variable set here overrides any variable set elsewhere within the environment unless
229 that variable is hard-coded within a file (e.g. by using '=' instead of '?=').
230 Some variables are hard-coded for various reasons but these variables are
231 relatively rare.
232 </para>
233
234 <para>
235 Edit this file to set the <filename><link linkend='var-MACHINE'>MACHINE</link></filename>
236 for which you want to build, which package types you wish to use
237 (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
238 where you want to downloaded files
239 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>),
240 and how you want your host machine to use resources
241 (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> and
242 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>).
243 </para>
244 </section>
245
246 <section id='structure-build-conf-bblayers.conf'>
247 <title><filename>build/conf/bblayers.conf</filename></title>
248
249 <para>
250 This file defines layers, which are directory trees, traversed (or walked) by BitBake.
251 If <filename>bblayers.conf</filename>
252 is not present, it is created from <filename>bblayers.conf.sample</filename> when
253 you <filename>source</filename> the environment setup script.
254 </para>
255
256 <para>
257 The <filename>bblayers.conf</filename> file uses the
258 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link> variable to
259 list the layers BitBake tries to find.
260 The file uses the
261 <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link>
262 variable to list layers that must not be removed.
263 </para>
264 </section>
265
266 <section id='structure-build-conf-sanity_info'>
267 <title><filename>build/conf/sanity_info</filename></title>
268
269 <para>
270 This file is created during the build to indicate the state of the sanity checks.
271 </para>
272 </section>
273
274 <section id='structure-build-downloads'>
275 <title><filename>build/downloads/</filename></title>
276
277 <para>
278 This directory is used for the upstream source tarballs.
279 The directory can be reused by multiple builds or moved to another location.
280 You can control the location of this directory through the
281 <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable.
282 </para>
283 </section>
284
285 <section id='structure-build-sstate-cache'>
286 <title><filename>build/sstate-cache/</filename></title>
287
288 <para>
289 This directory is used for the shared state cache.
290 The directory can be reused by multiple builds or moved to another location.
291 You can control the location of this directory through the
292 <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable.
293 </para>
294 </section>
295
296 <section id='structure-build-tmp'>
297 <title><filename>build/tmp/</filename></title>
298
299 <para>
300 This directory receives all the OpenEmbedded build system's output.
301 BitBake creates this directory if it does not exist.
302 As a last resort, to clean up a build and start it from scratch (other than the downloads),
303 you can remove everything in the <filename>tmp</filename> directory or get rid of the
304 directory completely.
305 If you do, you should also completely remove the <filename>build/sstate-cache</filename>
306 directory as well.
307 </para>
308 </section>
309
310 <section id='structure-build-tmp-buildstats'>
311 <title><filename>build/tmp/buildstats/</filename></title>
312
313 <para>
314 This directory stores the build statistics.
315 </para>
316 </section>
317
318 <section id='structure-build-tmp-cache'>
319 <title><filename>build/tmp/cache/</filename></title>
320
321 <para>
322 When BitBake parses the metadata, it creates a cache file of the result that can
323 be used when subsequently running commands.
324 These results are stored here on a per-machine basis.
325 </para>
326 </section>
327
328 <section id='structure-build-tmp-deploy'>
329 <title><filename>build/tmp/deploy/</filename></title>
330
331 <para>
332 This directory contains any 'end result' output from the OpenEmbedded build process.
333 </para>
334 </section>
335
336 <section id='structure-build-tmp-deploy-deb'>
337 <title><filename>build/tmp/deploy/deb/</filename></title>
338
339 <para>
340 This directory receives any <filename>.deb</filename> packages produced by
341 the build process.
342 The packages are sorted into feeds for different architecture types.
343 </para>
344 </section>
345
346 <section id='structure-build-tmp-deploy-rpm'>
347 <title><filename>build/tmp/deploy/rpm/</filename></title>
348
349 <para>
350 This directory receives any <filename>.rpm</filename> packages produced by
351 the build process.
352 The packages are sorted into feeds for different architecture types.
353 </para>
354 </section>
355
356 <section id='structure-build-tmp-deploy-licenses'>
357 <title><filename>build/tmp/deploy/licenses/</filename></title>
358
359 <para>
360 This directory receives package licensing information.
361 For example, the directory contains sub-directories for <filename>bash</filename>,
362 <filename>busybox</filename>, and <filename>eglibc</filename> (among others) that in turn
363 contain appropriate <filename>COPYING</filename> license files with other licensing information.
364 </para>
365 </section>
366
367 <section id='structure-build-tmp-deploy-images'>
368 <title><filename>build/tmp/deploy/images/</filename></title>
369
370 <para>
371 This directory receives complete filesystem images.
372 If you want to flash the resulting image from a build onto a device, look here for the image.
373 </para>
374
375 <para>
376 Be careful when deleting files in this directory.
377 You can safely delete old images from this directory (e.g.
378 <filename>core-image-*</filename>, <filename>hob-image-*</filename>,
379 etc.).
380 However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.),
381 bootloader and other supplementary files might be deployed here prior to building an
382 image.
383 Because these files, however, are not directly produced from the image, if you
384 delete them they will not be automatically re-created when you build the image again.
385 </para>
386
387 <para>
388 If you do accidentally delete files here, you will need to force them to be
389 re-created.
390 In order to do that, you will need to know the target that produced them.
391 For example, these commands rebuild and re-create the kernel files:
392 <literallayout class='monospaced'>
393 $ bitbake -c clean virtual/kernel
394 $ bitbake virtual/kernel
395 </literallayout>
396 </para>
397 </section>
398
399 <section id='structure-build-tmp-deploy-ipk'>
400 <title><filename>build/tmp/deploy/ipk/</filename></title>
401
402 <para>
403 This directory receives <filename>.ipk</filename> packages produced by
404 the build process.</para>
405 </section>
406
407 <section id='structure-build-tmp-sysroots'>
408 <title><filename>build/tmp/sysroots/</filename></title>
409
410 <para>
411 This directory contains shared header files and libraries as well as other shared
412 data.
413 Packages that need to share output with other packages do so within this directory.
414 The directory is subdivided by architecture so multiple builds can run within
415 the one Build Directory.
416 </para>
417 </section>
418
419 <section id='structure-build-tmp-stamps'>
420 <title><filename>build/tmp/stamps/</filename></title>
421
422 <para>
423 This directory holds information that BitBake uses for accounting purposes
424 to track what tasks have run and when they have run.
425 The directory is sub-divided by architecture, package name, and
426 version.
427 Following is an example:
428 <literallayout class='monospaced'>
429 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
430 </literallayout>
431 Although the files in the directory are empty of data,
432 BitBake uses the filenames and timestamps for tracking purposes.
433 </para>
434 </section>
435
436 <section id='structure-build-tmp-log'>
437 <title><filename>build/tmp/log/</filename></title>
438
439 <para>
440 This directory contains general logs that are not otherwise placed using the
441 package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
442 Examples of logs are the output from the <filename>check_pkg</filename> or
443 <filename>distro_check</filename> tasks.
444 Running a build does not necessarily mean this directory is created.
445 </para>
446 </section>
447
448 <section id='structure-build-tmp-pkgdata'>
449 <title><filename>build/tmp/pkgdata/</filename></title>
450
451 <para>
452 This directory contains intermediate packaging data that is used later in the packaging process.
453 For more information, see the "<link linkend='ref-classes-package'>Packaging - package*.bbclass</link>" section.
454 </para>
455 </section>
456
457 <section id='structure-build-tmp-work'>
458 <title><filename>build/tmp/work/</filename></title>
459
460 <para>
461 This directory contains architecture-specific work sub-directories
462 for packages built by BitBake.
463 All tasks execute from the appropriate work directory.
464 For example, the source for a particular package is unpacked,
465 patched, configured and compiled all within its own work directory.
466 Within the work directory, organization is based on the package group
467 and version for which the source is being compiled
468 as defined by the
469 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
470 </para>
471
472 <para>
473 It is worth considering the structure of a typical work directory.
474 As an example, consider the <filename>linux-yocto-kernel-3.0</filename>
475 on the machine <filename>qemux86</filename>
476 built within the Yocto Project.
477 For this package, a work directory of
478 <filename>tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+&lt;.....&gt;</filename>,
479 referred to as the
480 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, is created.
481 Within this directory, the source is unpacked to
482 <filename>linux-qemux86-standard-build</filename> and then patched by Quilt
483 (see the
484 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Modifying Package
485 Source Code with Quilt</ulink>" section in the Yocto Project Development Manual.
486 Within the <filename>linux-qemux86-standard-build</filename> directory,
487 standard Quilt directories <filename>linux-3.0/patches</filename>
488 and <filename>linux-3.0/.pc</filename> are created,
489 and standard Quilt commands can be used.
490 </para>
491
492 <para>
493 There are other directories generated within <filename>WORKDIR</filename>.
494 The most important directory is <filename>WORKDIR/temp/</filename>,
495 which has log files for each task (<filename>log.do_*.pid</filename>)
496 and contains the scripts BitBake runs for each task
497 (<filename>run.do_*.pid</filename>).
498 The <filename>WORKDIR/image/</filename> directory is where "make
499 install" places its output that is then split into sub-packages
500 within <filename>WORKDIR/packages-split/</filename>.
501 </para>
502 </section>
503</section>
504
505<section id='structure-meta'>
506 <title>The Metadata - <filename>meta/</filename></title>
507
508 <para>
509 As mentioned previously, metadata is the core of the Yocto Project.
510 Metadata has several important subdivisions:
511 </para>
512
513 <section id='structure-meta-classes'>
514 <title><filename>meta/classes/</filename></title>
515
516 <para>
517 This directory contains the <filename>*.bbclass</filename> files.
518 Class files are used to abstract common code so it can be reused by multiple
519 packages.
520 Every package inherits the <filename>base.bbclass</filename> file.
521 Examples of other important classes are <filename>autotools.bbclass</filename>, which
522 in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
523 Another example is <filename>kernel.bbclass</filename> that contains common code and functions
524 for working with the Linux kernel.
525 Functions like image generation or packaging also have their specific class files
526 such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and
527 <filename>package*.bbclass</filename>.
528 </para>
529 </section>
530
531 <section id='structure-meta-conf'>
532 <title><filename>meta/conf/</filename></title>
533
534 <para>
535 This directory contains the core set of configuration files that start from
536 <filename>bitbake.conf</filename> and from which all other configuration
537 files are included.
538 See the include statements at the end of the file and you will note that even
539 <filename>local.conf</filename> is loaded from there.
540 While <filename>bitbake.conf</filename> sets up the defaults, you can often override
541 these by using the (<filename>local.conf</filename>) file, machine file or
542 the distribution configuration file.
543 </para>
544 </section>
545
546 <section id='structure-meta-conf-machine'>
547 <title><filename>meta/conf/machine/</filename></title>
548
549 <para>
550 This directory contains all the machine configuration files.
551 If you set <filename>MACHINE="qemux86"</filename>,
552 the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this
553 directory.
554 The <filename>include</filename> directory contains various data common to multiple machines.
555 If you want to add support for a new machine to the Yocto Project, look in this directory.
556 </para>
557 </section>
558
559 <section id='structure-meta-conf-distro'>
560 <title><filename>meta/conf/distro/</filename></title>
561
562 <para>
563 Any distribution-specific configuration is controlled from this directory.
564 For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here.
565 This directory includes the versions and the
566 <filename>SRCDATE</filename> definitions for applications that are configured here.
567 An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>.
568 Although this file mainly inherits its configuration from Poky.
569 </para>
570 </section>
571
572 <section id='structure-meta-recipes-bsp'>
573 <title><filename>meta/recipes-bsp/</filename></title>
574
575 <para>
576 This directory contains anything linking to specific hardware or hardware
577 configuration information such as "u-boot" and "grub".
578 </para>
579 </section>
580
581 <section id='structure-meta-recipes-connectivity'>
582 <title><filename>meta/recipes-connectivity/</filename></title>
583
584 <para>
585 This directory contains libraries and applications related to communication with other devices.
586 </para>
587 </section>
588
589 <section id='structure-meta-recipes-core'>
590 <title><filename>meta/recipes-core/</filename></title>
591
592 <para>
593 This directory contains what is needed to build a basic working Linux image
594 including commonly used dependencies.
595 </para>
596 </section>
597
598 <section id='structure-meta-recipes-devtools'>
599 <title><filename>meta/recipes-devtools/</filename></title>
600
601 <para>
602 This directory contains tools that are primarily used by the build system.
603 The tools, however, can also be used on targets.
604 </para>
605 </section>
606
607 <section id='structure-meta-recipes-extended'>
608 <title><filename>meta/recipes-extended/</filename></title>
609
610 <para>
611 This directory contains non-essential applications that add features compared to the
612 alternatives in core.
613 You might need this directory for full tool functionality or for Linux Standard Base (LSB)
614 compliance.
615 </para>
616 </section>
617
618 <section id='structure-meta-recipes-gnome'>
619 <title><filename>meta/recipes-gnome/</filename></title>
620
621 <para>
622 This directory contains all things related to the GTK+ application framework.
623 </para>
624 </section>
625
626 <section id='structure-meta-recipes-graphics'>
627 <title><filename>meta/recipes-graphics/</filename></title>
628
629 <para>
630 This directory contains X and other graphically related system libraries
631 </para>
632 </section>
633
634 <section id='structure-meta-recipes-kernel'>
635 <title><filename>meta/recipes-kernel/</filename></title>
636
637 <para>
638 This directory contains the kernel and generic applications and libraries that
639 have strong kernel dependencies.
640 </para>
641 </section>
642
643 <section id='structure-meta-recipes-multimedia'>
644 <title><filename>meta/recipes-multimedia/</filename></title>
645
646 <para>
647 This directory contains codecs and support utilities for audio, images and video.
648 </para>
649 </section>
650
651 <section id='structure-meta-recipes-qt'>
652 <title><filename>meta/recipes-qt/</filename></title>
653
654 <para>
655 This directory contains all things related to the Qt application framework.
656 </para>
657 </section>
658
659 <section id='structure-meta-recipes-rt'>
660 <title><filename>meta/recipes-rt/</filename></title>
661
662 <para>
663 This directory contains package and image recipes for using and testing
664 the <filename>PREEMPT_RT</filename> kernel.
665 </para>
666 </section>
667
668 <section id='structure-meta-recipes-sato'>
669 <title><filename>meta/recipes-sato/</filename></title>
670
671 <para>
672 This directory contains the Sato demo/reference UI/UX and its associated applications
673 and configuration data.
674 </para>
675 </section>
676
677 <section id='structure-meta-recipes-support'>
678 <title><filename>meta/recipes-support/</filename></title>
679
680 <para>
681 This directory contains recipes that used by other recipes, but that are not directly
682 included in images (i.e. dependencies of other recipes).
683 </para>
684 </section>
685
686 <section id='structure-meta-site'>
687 <title><filename>meta/site/</filename></title>
688
689 <para>
690 This directory contains a list of cached results for various architectures.
691 Because certain "autoconf" test results cannot be determined when cross-compiling due to
692 the tests not able to run on a live system, the information in this directory is
693 passed to "autoconf" for the various architectures.
694 </para>
695 </section>
696
697 <section id='structure-meta-recipes-txt'>
698 <title><filename>meta/recipes.txt</filename></title>
699
700 <para>
701 This file is a description of the contents of <filename>recipes-*</filename>.
702 </para>
703 </section>
704</section>
705
706</chapter>
707<!--
708vim: expandtab tw=80 ts=4
709-->
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 @@
1/*
2 Generic XHTML / DocBook XHTML CSS Stylesheet.
3
4 Browser wrangling and typographic design by
5 Oyvind Kolas / pippin@gimp.org
6
7 Customised for Poky by
8 Matthew Allum / mallum@o-hand.com
9
10 Thanks to:
11 Liam R. E. Quin
12 William Skaggs
13 Jakub Steiner
14
15 Structure
16 ---------
17
18 The stylesheet is divided into the following sections:
19
20 Positioning
21 Margins, paddings, width, font-size, clearing.
22 Decorations
23 Borders, style
24 Colors
25 Colors
26 Graphics
27 Graphical backgrounds
28 Nasty IE tweaks
29 Workarounds needed to make it work in internet explorer,
30 currently makes the stylesheet non validating, but up until
31 this point it is validating.
32 Mozilla extensions
33 Transparency for footer
34 Rounded corners on boxes
35
36*/
37
38
39 /*************** /
40 / Positioning /
41/ ***************/
42
43body {
44 font-family: Verdana, Sans, sans-serif;
45
46 min-width: 640px;
47 width: 80%;
48 margin: 0em auto;
49 padding: 2em 5em 5em 5em;
50 color: #333;
51}
52
53h1,h2,h3,h4,h5,h6,h7 {
54 font-family: Arial, Sans;
55 color: #00557D;
56 clear: both;
57}
58
59h1 {
60 font-size: 2em;
61 text-align: left;
62 padding: 0em 0em 0em 0em;
63 margin: 2em 0em 0em 0em;
64}
65
66h2.subtitle {
67 margin: 0.10em 0em 3.0em 0em;
68 padding: 0em 0em 0em 0em;
69 font-size: 1.8em;
70 padding-left: 20%;
71 font-weight: normal;
72 font-style: italic;
73}
74
75h2 {
76 margin: 2em 0em 0.66em 0em;
77 padding: 0.5em 0em 0em 0em;
78 font-size: 1.5em;
79 font-weight: bold;
80}
81
82h3.subtitle {
83 margin: 0em 0em 1em 0em;
84 padding: 0em 0em 0em 0em;
85 font-size: 142.14%;
86 text-align: right;
87}
88
89h3 {
90 margin: 1em 0em 0.5em 0em;
91 padding: 1em 0em 0em 0em;
92 font-size: 140%;
93 font-weight: bold;
94}
95
96h4 {
97 margin: 1em 0em 0.5em 0em;
98 padding: 1em 0em 0em 0em;
99 font-size: 120%;
100 font-weight: bold;
101}
102
103h5 {
104 margin: 1em 0em 0.5em 0em;
105 padding: 1em 0em 0em 0em;
106 font-size: 110%;
107 font-weight: bold;
108}
109
110h6 {
111 margin: 1em 0em 0em 0em;
112 padding: 1em 0em 0em 0em;
113 font-size: 110%;
114 font-weight: bold;
115}
116
117.authorgroup {
118 background-color: transparent;
119 background-repeat: no-repeat;
120 padding-top: 256px;
121 background-image: url("figures/poky-title.png");
122 background-position: left top;
123 margin-top: -256px;
124 padding-right: 50px;
125 margin-left: 0px;
126 text-align: right;
127 width: 740px;
128}
129
130h3.author {
131 margin: 0em 0me 0em 0em;
132 padding: 0em 0em 0em 0em;
133 font-weight: normal;
134 font-size: 100%;
135 color: #333;
136 clear: both;
137}
138
139.author tt.email {
140 font-size: 66%;
141}
142
143.titlepage hr {
144 width: 0em;
145 clear: both;
146}
147
148.revhistory {
149 padding-top: 2em;
150 clear: both;
151}
152
153.toc,
154.list-of-tables,
155.list-of-examples,
156.list-of-figures {
157 padding: 1.33em 0em 2.5em 0em;
158 color: #00557D;
159}
160
161.toc p,
162.list-of-tables p,
163.list-of-figures p,
164.list-of-examples p {
165 padding: 0em 0em 0em 0em;
166 padding: 0em 0em 0.3em;
167 margin: 1.5em 0em 0em 0em;
168}
169
170.toc p b,
171.list-of-tables p b,
172.list-of-figures p b,
173.list-of-examples p b{
174 font-size: 100.0%;
175 font-weight: bold;
176}
177
178.toc dl,
179.list-of-tables dl,
180.list-of-figures dl,
181.list-of-examples dl {
182 margin: 0em 0em 0.5em 0em;
183 padding: 0em 0em 0em 0em;
184}
185
186.toc dt {
187 margin: 0em 0em 0em 0em;
188 padding: 0em 0em 0em 0em;
189}
190
191.toc dd {
192 margin: 0em 0em 0em 2.6em;
193 padding: 0em 0em 0em 0em;
194}
195
196div.glossary dl,
197div.variablelist dl {
198}
199
200.glossary dl dt,
201.variablelist dl dt,
202.variablelist dl dt span.term {
203 font-weight: normal;
204 width: 20em;
205 text-align: right;
206}
207
208.variablelist dl dt {
209 margin-top: 0.5em;
210}
211
212.glossary dl dd,
213.variablelist dl dd {
214 margin-top: -1em;
215 margin-left: 25.5em;
216}
217
218.glossary dd p,
219.variablelist dd p {
220 margin-top: 0em;
221 margin-bottom: 1em;
222}
223
224
225div.calloutlist table td {
226 padding: 0em 0em 0em 0em;
227 margin: 0em 0em 0em 0em;
228}
229
230div.calloutlist table td p {
231 margin-top: 0em;
232 margin-bottom: 1em;
233}
234
235div p.copyright {
236 text-align: left;
237}
238
239div.legalnotice p.legalnotice-title {
240 margin-bottom: 0em;
241}
242
243p {
244 line-height: 1.5em;
245 margin-top: 0em;
246
247}
248
249dl {
250 padding-top: 0em;
251}
252
253hr {
254 border: solid 1px;
255}
256
257
258.mediaobject,
259.mediaobjectco {
260 text-align: center;
261}
262
263img {
264 border: none;
265}
266
267ul {
268 padding: 0em 0em 0em 1.5em;
269}
270
271ul li {
272 padding: 0em 0em 0em 0em;
273}
274
275ul li p {
276 text-align: left;
277}
278
279table {
280 width :100%;
281}
282
283th {
284 padding: 0.25em;
285 text-align: left;
286 font-weight: normal;
287 vertical-align: top;
288}
289
290td {
291 padding: 0.25em;
292 vertical-align: top;
293}
294
295p a[id] {
296 margin: 0px;
297 padding: 0px;
298 display: inline;
299 background-image: none;
300}
301
302a {
303 text-decoration: underline;
304 color: #444;
305}
306
307pre {
308 overflow: auto;
309}
310
311a:hover {
312 text-decoration: underline;
313 /*font-weight: bold;*/
314}
315
316
317div.informalfigure,
318div.informalexample,
319div.informaltable,
320div.figure,
321div.table,
322div.example {
323 margin: 1em 0em;
324 padding: 1em;
325 page-break-inside: avoid;
326}
327
328
329div.informalfigure p.title b,
330div.informalexample p.title b,
331div.informaltable p.title b,
332div.figure p.title b,
333div.example p.title b,
334div.table p.title b{
335 padding-top: 0em;
336 margin-top: 0em;
337 font-size: 100%;
338 font-weight: normal;
339}
340
341.mediaobject .caption,
342.mediaobject .caption p {
343 text-align: center;
344 font-size: 80%;
345 padding-top: 0.5em;
346 padding-bottom: 0.5em;
347}
348
349.epigraph {
350 padding-left: 55%;
351 margin-bottom: 1em;
352}
353
354.epigraph p {
355 text-align: left;
356}
357
358.epigraph .quote {
359 font-style: italic;
360}
361.epigraph .attribution {
362 font-style: normal;
363 text-align: right;
364}
365
366span.application {
367 font-style: italic;
368}
369
370.programlisting {
371 font-family: monospace;
372 font-size: 80%;
373 white-space: pre;
374 margin: 1.33em 0em;
375 padding: 1.33em;
376}
377
378.tip,
379.warning,
380.caution,
381.note {
382 margin-top: 1em;
383 margin-bottom: 1em;
384
385}
386
387/* force full width of table within div */
388.tip table,
389.warning table,
390.caution table,
391.note table {
392 border: none;
393 width: 100%;
394}
395
396
397.tip table th,
398.warning table th,
399.caution table th,
400.note table th {
401 padding: 0.8em 0.0em 0.0em 0.0em;
402 margin : 0em 0em 0em 0em;
403}
404
405.tip p,
406.warning p,
407.caution p,
408.note p {
409 margin-top: 0.5em;
410 margin-bottom: 0.5em;
411 padding-right: 1em;
412 text-align: left;
413}
414
415.acronym {
416 text-transform: uppercase;
417}
418
419b.keycap,
420.keycap {
421 padding: 0.09em 0.3em;
422 margin: 0em;
423}
424
425.itemizedlist li {
426 clear: none;
427}
428
429.filename {
430 font-size: medium;
431 font-family: Courier, monospace;
432}
433
434
435div.navheader, div.heading{
436 position: absolute;
437 left: 0em;
438 top: 0em;
439 width: 100%;
440 background-color: #cdf;
441 width: 100%;
442}
443
444div.navfooter, div.footing{
445 position: fixed;
446 left: 0em;
447 bottom: 0em;
448 background-color: #eee;
449 width: 100%;
450}
451
452
453div.navheader td,
454div.navfooter td {
455 font-size: 66%;
456}
457
458div.navheader table th {
459 /*font-family: Georgia, Times, serif;*/
460 /*font-size: x-large;*/
461 font-size: 80%;
462}
463
464div.navheader table {
465 border-left: 0em;
466 border-right: 0em;
467 border-top: 0em;
468 width: 100%;
469}
470
471div.navfooter table {
472 border-left: 0em;
473 border-right: 0em;
474 border-bottom: 0em;
475 width: 100%;
476}
477
478div.navheader table td a,
479div.navfooter table td a {
480 color: #777;
481 text-decoration: none;
482}
483
484/* normal text in the footer */
485div.navfooter table td {
486 color: black;
487}
488
489div.navheader table td a:visited,
490div.navfooter table td a:visited {
491 color: #444;
492}
493
494
495/* links in header and footer */
496div.navheader table td a:hover,
497div.navfooter table td a:hover {
498 text-decoration: underline;
499 background-color: transparent;
500 color: #33a;
501}
502
503div.navheader hr,
504div.navfooter hr {
505 display: none;
506}
507
508
509.qandaset tr.question td p {
510 margin: 0em 0em 1em 0em;
511 padding: 0em 0em 0em 0em;
512}
513
514.qandaset tr.answer td p {
515 margin: 0em 0em 1em 0em;
516 padding: 0em 0em 0em 0em;
517}
518.answer td {
519 padding-bottom: 1.5em;
520}
521
522.emphasis {
523 font-weight: bold;
524}
525
526
527 /************* /
528 / decorations /
529/ *************/
530
531.titlepage {
532}
533
534.part .title {
535}
536
537.subtitle {
538 border: none;
539}
540
541/*
542h1 {
543 border: none;
544}
545
546h2 {
547 border-top: solid 0.2em;
548 border-bottom: solid 0.06em;
549}
550
551h3 {
552 border-top: 0em;
553 border-bottom: solid 0.06em;
554}
555
556h4 {
557 border: 0em;
558 border-bottom: solid 0.06em;
559}
560
561h5 {
562 border: 0em;
563}
564*/
565
566.programlisting {
567 border: solid 1px;
568}
569
570div.figure,
571div.table,
572div.informalfigure,
573div.informaltable,
574div.informalexample,
575div.example {
576 border: 1px solid;
577}
578
579
580
581.tip,
582.warning,
583.caution,
584.note {
585 border: 1px solid;
586}
587
588.tip table th,
589.warning table th,
590.caution table th,
591.note table th {
592 border-bottom: 1px solid;
593}
594
595.question td {
596 border-top: 1px solid black;
597}
598
599.answer {
600}
601
602
603b.keycap,
604.keycap {
605 border: 1px solid;
606}
607
608
609div.navheader, div.heading{
610 border-bottom: 1px solid;
611}
612
613
614div.navfooter, div.footing{
615 border-top: 1px solid;
616}
617
618 /********* /
619 / colors /
620/ *********/
621
622body {
623 color: #333;
624 background: white;
625}
626
627a {
628 background: transparent;
629}
630
631a:hover {
632 background-color: #dedede;
633}
634
635
636h1,
637h2,
638h3,
639h4,
640h5,
641h6,
642h7,
643h8 {
644 background-color: transparent;
645}
646
647hr {
648 border-color: #aaa;
649}
650
651
652.tip, .warning, .caution, .note {
653 border-color: #fff;
654}
655
656
657.tip table th,
658.warning table th,
659.caution table th,
660.note table th {
661 border-bottom-color: #fff;
662}
663
664
665.warning {
666 background-color: #f0f0f2;
667}
668
669.caution {
670 background-color: #f0f0f2;
671}
672
673.tip {
674 background-color: #f0f0f2;
675}
676
677.note {
678 background-color: #f0f0f2;
679}
680
681.glossary dl dt,
682.variablelist dl dt,
683.variablelist dl dt span.term {
684 color: #044;
685}
686
687div.figure,
688div.table,
689div.example,
690div.informalfigure,
691div.informaltable,
692div.informalexample {
693 border-color: #aaa;
694}
695
696pre.programlisting {
697 color: black;
698 background-color: #fff;
699 border-color: #aaa;
700 border-width: 2px;
701}
702
703.guimenu,
704.guilabel,
705.guimenuitem {
706 background-color: #eee;
707}
708
709
710b.keycap,
711.keycap {
712 background-color: #eee;
713 border-color: #999;
714}
715
716
717div.navheader {
718 border-color: black;
719}
720
721
722div.navfooter {
723 border-color: black;
724}
725
726
727 /*********** /
728 / graphics /
729/ ***********/
730
731/*
732body {
733 background-image: url("images/body_bg.jpg");
734 background-attachment: fixed;
735}
736
737.navheader,
738.note,
739.tip {
740 background-image: url("images/note_bg.jpg");
741 background-attachment: fixed;
742}
743
744.warning,
745.caution {
746 background-image: url("images/warning_bg.jpg");
747 background-attachment: fixed;
748}
749
750.figure,
751.informalfigure,
752.example,
753.informalexample,
754.table,
755.informaltable {
756 background-image: url("images/figure_bg.jpg");
757 background-attachment: fixed;
758}
759
760*/
761h1,
762h2,
763h3,
764h4,
765h5,
766h6,
767h7{
768}
769
770/*
771Example of how to stick an image as part of the title.
772
773div.article .titlepage .title
774{
775 background-image: url("figures/white-on-black.png");
776 background-position: center;
777 background-repeat: repeat-x;
778}
779*/
780
781div.preface .titlepage .title,
782div.colophon .title,
783div.chapter .titlepage .title,
784div.article .titlepage .title
785{
786}
787
788div.section div.section .titlepage .title,
789div.sect2 .titlepage .title {
790 background: none;
791}
792
793
794h1.title {
795 background-color: transparent;
796 background-image: url("figures/poky-title.png");
797 background-repeat: no-repeat;
798 height: 256px;
799 text-indent: -9000px;
800 overflow:hidden;
801}
802
803h2.subtitle {
804 background-color: transparent;
805 text-indent: -9000px;
806 overflow:hidden;
807 width: 0px;
808 display: none;
809}
810
811 /*************************************** /
812 / pippin.gimp.org specific alterations /
813/ ***************************************/
814
815/*
816div.heading, div.navheader {
817 color: #777;
818 font-size: 80%;
819 padding: 0;
820 margin: 0;
821 text-align: left;
822 position: absolute;
823 top: 0px;
824 left: 0px;
825 width: 100%;
826 height: 50px;
827 background: url('/gfx/heading_bg.png') transparent;
828 background-repeat: repeat-x;
829 background-attachment: fixed;
830 border: none;
831}
832
833div.heading a {
834 color: #444;
835}
836
837div.footing, div.navfooter {
838 border: none;
839 color: #ddd;
840 font-size: 80%;
841 text-align:right;
842
843 width: 100%;
844 padding-top: 10px;
845 position: absolute;
846 bottom: 0px;
847 left: 0px;
848
849 background: url('/gfx/footing_bg.png') transparent;
850}
851*/
852
853
854
855 /****************** /
856 / nasty ie tweaks /
857/ ******************/
858
859/*
860div.heading, div.navheader {
861 width:expression(document.body.clientWidth + "px");
862}
863
864div.footing, div.navfooter {
865 width:expression(document.body.clientWidth + "px");
866 margin-left:expression("-5em");
867}
868body {
869 padding:expression("4em 5em 0em 5em");
870}
871*/
872
873 /**************************************** /
874 / mozilla vendor specific css extensions /
875/ ****************************************/
876/*
877div.navfooter, div.footing{
878 -moz-opacity: 0.8em;
879}
880
881div.figure,
882div.table,
883div.informalfigure,
884div.informaltable,
885div.informalexample,
886div.example,
887.tip,
888.warning,
889.caution,
890.note {
891 -moz-border-radius: 0.5em;
892}
893
894b.keycap,
895.keycap {
896 -moz-border-radius: 0.3em;
897}
898*/
899
900table tr td table tr td {
901 display: none;
902}
903
904
905hr {
906 display: none;
907}
908
909table {
910 border: 0em;
911}
912
913 .photo {
914 float: right;
915 margin-left: 1.5em;
916 margin-bottom: 1.5em;
917 margin-top: 0em;
918 max-width: 17em;
919 border: 1px solid gray;
920 padding: 3px;
921 background: white;
922}
923 .seperator {
924 padding-top: 2em;
925 clear: both;
926 }
927
928 #validators {
929 margin-top: 5em;
930 text-align: right;
931 color: #777;
932 }
933 @media print {
934 body {
935 font-size: 8pt;
936 }
937 .noprint {
938 display: none;
939 }
940 }
941
942
943.tip,
944.note {
945 background: #f0f0f2;
946 color: #333;
947 padding: 20px;
948 margin: 20px;
949}
950
951.tip h3,
952.note h3 {
953 padding: 0em;
954 margin: 0em;
955 font-size: 2em;
956 font-weight: bold;
957 color: #333;
958}
959
960.tip a,
961.note a {
962 color: #333;
963 text-decoration: underline;
964}
965
966.footnote {
967 font-size: small;
968 color: #333;
969}
970
971/* Changes the announcement text */
972.tip h3,
973.warning h3,
974.caution h3,
975.note h3 {
976 font-size:large;
977 color: #00557D;
978}
979
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
12 of their function and contents.
13</para>
14
15<glossary id='ref-variables-glossary'>
16
17
18 <para>
19 <link linkend='var-ALLOW_EMPTY'>A</link>
20 <link linkend='var-B'>B</link>
21 <link linkend='var-CFLAGS'>C</link>
22 <link linkend='var-D'>D</link>
23 <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link>
24 <link linkend='var-FILES'>F</link>
25<!-- <link linkend='var-glossary-g'>G</link> -->
26 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-IMAGE_FEATURES'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KBRANCH'>K</link>
30 <link linkend='var-LAYERDIR'>L</link>
31 <link linkend='var-MACHINE'>M</link>
32<!-- <link linkend='var-glossary-n'>N</link> -->
33 <link linkend='var-OE_TERMINAL'>O</link>
34 <link linkend='var-P'>P</link>
35<!-- <link linkend='var-glossary-q'>Q</link> -->
36 <link linkend='var-RCONFLICTS'>R</link>
37 <link linkend='var-S'>S</link>
38 <link linkend='var-T'>T</link>
39<!-- <link linkend='var-glossary-u'>U</link> -->
40<!-- <link linkend='var-glossary-v'>V</link> -->
41 <link linkend='var-WORKDIR'>W</link>
42<!-- <link linkend='var-glossary-x'>X</link> -->
43<!-- <link linkend='var-glossary-y'>Y</link> -->
44<!-- <link linkend='var-glossary-z'>Z</link>-->
45 </para>
46
47 <glossdiv id='var-glossary-a'><title>A</title>
48
49 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
50 <glossdef>
51 <para>
52 Specifies if an output package should still be produced if it is empty.
53 By default, BitBake does not produce empty packages.
54 This default behavior can cause issues when there is an
55 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
56 some other runtime hard-requirement on the existence of the package.
57 </para>
58
59 <para>
60 Like all package-controlling variables, you must always use them in
61 conjunction with a package name override.
62 Here is an example:
63 <literallayout class='monospaced'>
64 ALLOW_EMPTY_${PN} = "1"
65 </literallayout>
66 </para>
67 </glossdef>
68 </glossentry>
69
70 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
71 <glossdef>
72 <para>The email address used to contact the original author or authors in
73 order to send patches, forward bugs, etc.</para>
74 </glossdef>
75 </glossentry>
76
77 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
78 <glossdef>
79 <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
80 is set to the value of this variable, it specifies that the latest
81 source revision in the repository should be used. Here is an example:
82 <literallayout class='monospaced'>
83 SRCREV = "${AUTOREV}"
84 </literallayout>
85 </para>
86 </glossdef>
87 </glossentry>
88
89 </glossdiv>
90
91 <glossdiv id='var-glossary-b'><title>B</title>
92
93 <glossentry id='var-B'><glossterm>B</glossterm>
94 <glossdef>
95 <para>
96 The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
97 The OpenEmbedded build system places generated objects into the Build Directory
98 during a recipe's build process.
99 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
100 directory:
101 <literallayout class='monospaced'>
102 B = ${WORKDIR}/${BPN}/{PV}/
103 </literallayout>
104 You can separate the (<filename>S</filename>) directory and the directory pointed to
105 by the <filename>B</filename> variable.
106 Most autotools-based recipes support separating these directories.
107 The build system defaults to using separate directories for <filename>gcc</filename>
108 and some kernel recipes.
109 </para>
110 </glossdef>
111 </glossentry>
112
113 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
114 <glossdef>
115 <para>
116 A list of packages not to install despite being recommended by a recipe.
117 Support for this variable exists only when using the
118 <filename>ipk</filename> packaging backend.
119 </para>
120 </glossdef>
121 </glossentry>
122
123 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
124 <glossdef>
125 <para>
126 Monitors disk space and available inodes during the build
127 and allows you to control the build based on these
128 parameters.
129 </para>
130
131 <para>
132 Disk space monitoring is disabled by default.
133 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
134 variable to your <filename>conf/local.conf</filename> file found in the
135 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
136 Use the following form:
137 <literallayout class='monospaced'>
138 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
139
140 where:
141
142 &lt;action&gt; is:
143 ABORT: Immediately abort the build when
144 a threshold is broken.
145 STOPTASKS: Stop the build after the currently
146 executing tasks have finished when
147 a threshold is broken.
148 WARN: Issue a warning but continue the
149 build when a threshold is broken.
150 Subsequent warnings are issued as
151 defined by the
152 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
153 which must be defined in the
154 conf/local.conf file.
155
156 &lt;dir&gt; is:
157 Any directory you choose. You can specify one or
158 more directories to monitor by separating the
159 groupings with a space. If two directories are
160 on the same device, only the first directory
161 is monitored.
162
163 &lt;threshold&gt; is:
164 Either the minimum available disk space,
165 the minimum number of free inodes, or
166 both. You must specify at least one. To
167 omit one or the other, simply omit the value.
168 Specify the threshold using G, M, K for Gbytes,
169 Mbytes, and Kbytes, respectively. If you do
170 not specify G, M, or K, Kbytes is assumed by
171 default. Do not use GB, MB, or KB.
172 </literallayout>
173 </para>
174
175 <para>
176 Here are some examples:
177 <literallayout class='monospaced'>
178 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
179 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
180 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
181 </literallayout>
182 The first example works only if you also provide
183 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
184 in the <filename>conf/local.conf</filename>.
185 This example causes the build system to immediately
186 abort when either the disk space in <filename>${TMPDIR}</filename> drops
187 below 1 Gbyte or the available free inodes drops below
188 100 Kbytes.
189 Because two directories are provided with the variable, the
190 build system also issue a
191 warning when the disk space in the
192 <filename>${SSTATE_DIR}</filename> directory drops
193 below 1 Gbyte or the number of free inodes drops
194 below 100 Kbytes.
195 Subsequent warnings are issued during intervals as
196 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
197 variable.
198 </para>
199
200 <para>
201 The second example stops the build after all currently
202 executing tasks complete when the minimum disk space
203 in the <filename>${TMPDIR}</filename> directory drops
204 below 1 Gbyte.
205 No disk monitoring occurs for the free inodes in this case.
206 </para>
207
208 <para>
209 The final example immediately aborts the build when the
210 number of free inodes in the <filename>${TMPDIR}</filename> directory
211 drops below 100 Kbytes.
212 No disk space monitoring for the directory itself occurs
213 in this case.
214 </para>
215 </glossdef>
216 </glossentry>
217
218 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
219 <glossdef>
220 <para>
221 Defines the disk space and free inode warning intervals.
222 To set these intervals, define the variable in your
223 <filename>conf/local.conf</filename> file in the
224 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
225 </para>
226
227 <para>
228 If you are going to use the
229 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
230 also use the
231 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
232 and define its action as "WARN".
233 During the build, subsequent warnings are issued each time
234 disk space or number of free inodes further reduces by
235 the respective interval.
236 </para>
237
238 <para>
239 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
240 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
241 the "WARN" action, the disk monitoring interval defaults to
242 the following:
243 <literallayout class='monospaced'>
244 BB_DISKMON_WARNINTERVAL = "50M,5K"
245 </literallayout>
246 </para>
247
248 <para>
249 When specifying the variable in your configuration file,
250 use the following form:
251 <literallayout class='monospaced'>
252 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
253
254 where:
255
256 &lt;disk_space_interval&gt; is:
257 An interval of memory expressed in either
258 G, M, or K for Gbytes, Mbytes, or Kbytes,
259 respectively. You cannot use GB, MB, or KB.
260
261 &lt;disk_inode_interval&gt; is:
262 An interval of free inodes expressed in either
263 G, M, or K for Gbytes, Mbytes, or Kbytes,
264 respectively. You cannot use GB, MB, or KB.
265 </literallayout>
266 </para>
267
268 <para>
269 Here is an example:
270 <literallayout class='monospaced'>
271 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
272 BB_DISKMON_WARNINTERVAL = "50M,5K"
273 </literallayout>
274 These variables cause the OpenEmbedded build system to
275 issue subsequent warnings each time the available
276 disk space further reduces by 50 Mbytes or the number
277 of free inodes further reduces by 5 Kbytes in the
278 <filename>${SSTATE_DIR}</filename> directory.
279 Subsequent warnings based on the interval occur each time
280 a respective interval is reached beyond the intial warning
281 (i.e. 1 Gbytes and 100 Kbytes).
282 </para>
283 </glossdef>
284 </glossentry>
285
286 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
287 <glossdef>
288 <para>
289 Allows you to extend a recipe so that it builds variants of the software.
290 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
291 which is a copy of quilt built to run on the build system;
292 "crosses" such as <filename>gcc-cross</filename>,
293 which is a compiler built to run on the build machine but produces binaries
294 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
295 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
296 and "mulitlibs" in the form "<filename>multilib:&lt;multilib_name&gt;</filename>".
297 </para>
298
299 <para>
300 To build a different variant of the recipe with a minimal amount of code, it usually
301 is as simple as adding the following to your recipe:
302 <literallayout class='monospaced'>
303 BBCLASSEXTEND =+ "native nativesdk"
304 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
305 </literallayout>
306 </para>
307 </glossdef>
308 </glossentry>
309
310 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
311 <glossdef>
312 <para>Prevents BitBake from processing recipes and recipe append files.
313 You can use the <filename>BBMASK</filename> variable to "hide"
314 these <filename>.bb</filename> and <filename>.bbappend</filename> files.
315 BitBake ignores any recipe or recipe append files that match the expression.
316 It is as if BitBake does not see them at all.
317 Consequently, matching files are not parsed or otherwise used by
318 BitBake.</para>
319 <para>The value you provide is passed to python's regular expression compiler.
320 For complete syntax information, see python's documentation at
321 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
322 The expression is compared against the full paths to the files.
323 For example, the following uses a complete regular expression to tell
324 BitBake to ignore all recipe and recipe append files in the
325 <filename>.*/meta-ti/recipes-misc/</filename> directory:
326 <literallayout class='monospaced'>
327 BBMASK = ".*/meta-ti/recipes-misc/"
328 </literallayout></para>
329 <para>Use the <filename>BBMASK</filename> variable from within the
330 <filename>conf/local.conf</filename> file found
331 in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.</para>
332 </glossdef>
333 </glossentry>
334
335 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
336 <glossdef>
337 <para>The maximum number of tasks BitBake should run in parallel at any one time.
338 If your host development system supports multiple cores a good rule of thumb
339 is to set this variable to twice the number of cores.</para>
340 </glossdef>
341 </glossentry>
342
343 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
344 <glossdef>
345 <para>Lists the names of configured layers.
346 These names are used to find the other <filename>BBFILE_*</filename>
347 variables.
348 Typically, each layer will append its name to this variable in its
349 <filename>conf/layer.conf</filename> file.
350 </para>
351 </glossdef>
352 </glossentry>
353
354 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
355 <glossdef>
356 <para>Variable that expands to match files from <filename>BBFILES</filename> in a particular layer.
357 This variable is used in the <filename>conf/layer.conf</filename> file and must
358 be suffixed with the name of the specific layer (e.g.
359 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
360 </glossdef>
361 </glossentry>
362
363 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
364 <glossdef>
365 <para>Assigns the priority for recipe files in each layer.</para>
366 <para>This variable is useful in situations where the same recipe appears in
367 more than one layer.
368 Setting this variable allows you to prioritize a
369 layer against other layers that contain the same recipe - effectively
370 letting you control the precedence for the multiple layers.
371 The precedence established through this variable stands regardless of a
372 recipe's version (<filename>PV</filename> variable).
373 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
374 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
375 lower precedence.</para>
376 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
377 precedence.
378 For example, the value 6 has a higher precedence than the value 5.
379 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
380 dependencies (see the
381 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
382 more information.
383 The default priority, if unspecified
384 for a layer with no dependencies, is the lowest defined priority + 1
385 (or 1 if no priorities are defined).</para>
386 <tip>
387 You can use the command <filename>bitbake-layers show_layers</filename> to list
388 all configured layers along with their priorities.
389 </tip>
390 </glossdef>
391 </glossentry>
392
393 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
394 <glossdef>
395 <para>List of recipe files used by BitBake to build software</para>
396 </glossdef>
397 </glossentry>
398
399 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
400 <glossdef>
401 <para>Used by BitBake to locate <filename>.bbclass</filename> and configuration files.
402 This variable is analogous to the <filename>PATH</filename> variable.</para>
403 </glossdef>
404 </glossentry>
405
406 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
407 <glossdef>
408 <para>Variable that controls how BitBake displays logs on build failure.</para>
409 </glossdef>
410 </glossentry>
411
412 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
413 <glossdef>
414 <para>Lists the layers to enable during the build.
415 This variable is defined in the <filename>bblayers.conf</filename> configuration
416 file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
417 Here is an example:
418 <literallayout class='monospaced'>
419 BBLAYERS = " \
420 /home/scottrif/poky/meta \
421 /home/scottrif/poky/meta-yocto \
422 /home/scottrif/poky/meta-yocto-bsp \
423 /home/scottrif/poky/meta-mykernel \
424 "
425
426 BBLAYERS_NON_REMOVABLE ?= " \
427 /home/scottrif/poky/meta \
428 /home/scottrif/poky/meta-yocto \
429 "
430 </literallayout>
431 This example enables four layers, one of which is a custom, user-defined layer
432 named <filename>meta-mykernel</filename>.
433 </para>
434 </glossdef>
435 </glossentry>
436
437 <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm>
438 <glossdef>
439Core layer for images cannot be removed
440 <para>Lists core layers that cannot be removed from the
441 <filename>bblayers.conf</filename> file.
442 In order for BitBake to build your image, your
443 <filename>bblayers.conf</filename> file must include the
444 <filename>meta</filename> and <filename>meta-yocto</filename>
445 core layers.
446 Here is an example that shows these two layers listed in
447 the <filename>BBLAYERS_NON_REMOVABLE</filename> statement:
448 <literallayout class='monospaced'>
449 BBLAYERS = " \
450 /home/scottrif/poky/meta \
451 /home/scottrif/poky/meta-yocto \
452 /home/scottrif/poky/meta-yocto-bsp \
453 /home/scottrif/poky/meta-mykernel \
454 "
455
456 BBLAYERS_NON_REMOVABLE ?= " \
457 /home/scottrif/poky/meta \
458 /home/scottrif/poky/meta-yocto \
459 "
460 </literallayout>
461 </para>
462 </glossdef>
463 </glossentry>
464
465 <glossentry id='var-BP'><glossterm>BP</glossterm>
466 <glossdef>
467 <para>The base recipe name and version but without any special
468 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
469 and so forth).
470 <filename>BP</filename> is comprised of the following:
471 <literallayout class="monospaced">
472 ${BPN}-${PV}
473 </literallayout></para>
474 </glossdef>
475 </glossentry>
476
477 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
478 <glossdef>
479 <para>The bare name of the recipe.
480 This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
481 but removes common suffixes such as "-native" and "-cross" as well
482 as removes common prefixes such as multilib's "lib64-" and "lib32-".
483 The exact list of suffixes removed is specified by the
484 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
485 The exact list of prefixes removed is specified by the
486 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
487 Prefixes are removed for multilib and nativesdk cases.</para>
488 </glossdef>
489 </glossentry>
490
491 </glossdiv>
492
493 <glossdiv id='var-glossary-c'><title>C</title>
494
495 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
496 <glossdef>
497 <para>
498 Flags passed to C compiler for the target system.
499 This variable evaluates to the same as
500 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>.
501 </para>
502 </glossdef>
503 </glossentry>
504
505 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
506 <glossdef>
507 <para>A set of features common between
508 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
509 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
510 See the glossary descriptions for these variables for more information.</para>
511 </glossdef>
512 </glossentry>
513
514 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
515 <glossdef>
516 <para>A regular expression which evaluates to match the machines the recipe
517 works with.
518 It stops recipes being run on machines for which they are not compatible.
519 This is particularly useful with kernels.
520 It also helps to increase parsing speed as further parsing of the recipe is skipped
521 if it is found the current machine is not compatible.</para>
522 </glossdef>
523 </glossentry>
524
525 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
526 <glossdef>
527 <para>
528 Identifies editable or configurable files that are part of a package.
529 If the Package Management System (PMS) is being used to update
530 packages on the target system, it is possible that
531 configuration files you have changed after the original installation
532 and that you now want to remain unchanged are overwritten.
533 In other words, editable files might exist in the package that you do not
534 want reset as part of the package update process.
535 You can use the <filename>CONFFILES</filename> variable to list the files in the
536 package that you wish to prevent the PMS from overwriting during this update process.
537 </para>
538
539 <para>
540 To use the <filename>CONFFILES</filename> variable, provide a package name
541 override that identifies the resulting package.
542 Then, provide a space-separated list of files.
543 Here is an example:
544 <literallayout class='monospaced'>
545 CONFFILES_${PN} += "${sysconfdir}/file1 \
546 ${sysconfdir}/file2 ${sysconfdir}/file3"
547 </literallayout>
548 </para>
549
550 <para>
551 A relationship exists between the <filename>CONFFILES</filename> and
552 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
553 The files listed within <filename>CONFFILES</filename> must be a subset of
554 the files listed within <filename>FILES</filename>.
555 Because the configuration files you provide with <filename>CONFFILES</filename>
556 are simply being identified so that the PMS will not overwrite them,
557 it makes sense that
558 the files must already be included as part of the package through the
559 <filename>FILES</filename> variable.
560 </para>
561
562 <note>
563 When specifying paths as part of the <filename>CONFFILES</filename> variable,
564 it is good practice to use appropriate path variables.
565 For example, <filename>${sysconfdir}</filename> rather than
566 <filename>/etc</filename> or <filename>${bindir}</filename> rather
567 than <filename>/usr/bin</filename>.
568 You can find a list of these variables at the top of the
569 <filename>/meta/conf/bitbake.conf</filename> file in the
570 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
571 </note>
572 </glossdef>
573 </glossentry>
574
575 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
576 <glossdef>
577 <para>
578 A list of files that contains <filename>autoconf</filename> test results relevant
579 to the current build.
580 This variable is used by the Autotools utilities when running
581 <filename>configure</filename>.
582 </para>
583 </glossdef>
584 </glossentry>
585
586 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
587 <glossdef>
588 <para>
589 Specifies the list of packages to be added to the image.
590 This variable should only be set in the <filename>local.conf</filename>
591 configuration file found in the
592 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
593 </para>
594
595 <para>
596 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
597 </para>
598 </glossdef>
599 </glossentry>
600
601 </glossdiv>
602
603 <glossdiv id='var-glossary-d'><title>D</title>
604
605 <glossentry id='var-D'><glossterm>D</glossterm>
606 <glossdef>
607 <para>The destination directory.</para>
608 </glossdef>
609 </glossentry>
610
611 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
612 <glossdef>
613 <para>
614 Specifies to build packages with debugging information.
615 This influences the value of the
616 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
617 variable.
618 </para>
619 </glossdef>
620 </glossentry>
621
622 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
623 <glossdef>
624 <para>
625 The options to pass in
626 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
627 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
628 a system for debugging.
629 This variable defaults to "-O -fno-omit-frame-pointer -g".
630 </para>
631 </glossdef>
632 </glossentry>
633
634 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
635 <glossdef>
636 <para>Specifies the priority of recipes.</para>
637 </glossdef>
638 </glossentry>
639
640 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
641 <glossdef>
642 <para>
643 Lists a recipe's build-time dependencies
644 (i.e. other recipe files).
645 The system ensures that all the dependencies listed
646 have been built and have their contents in the appropriate
647 sysroots before the recipe's configure task is executed.
648 </para>
649 </glossdef>
650 </glossentry>
651
652 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
653 <glossdef>
654 <para>The package description used by package managers.
655 If not set, <filename>DESCRIPTION</filename> takes
656 the value of the
657 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
658 variable.
659 </para>
660 </glossdef>
661 </glossentry>
662
663 <glossentry id='var-DESTDIR'><glossterm>DESTDIR</glossterm>
664 <glossdef>
665 <para>the destination directory.</para>
666 </glossdef>
667 </glossentry>
668
669 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
670 <glossdef>
671 <para>
672 The short name of the distribution.
673 This variable corresponds to a file with the
674 extension <filename>.conf</filename>
675 located in a <filename>conf/distro</filename> directory
676 within the metadata that contains the distribution configuration.
677 The
678 value must not contain spaces, and is typically all lower-case.
679 </para>
680 <para>
681 If the variable is blank, a set of default configuration
682 will be used, which is specified
683 within <filename>meta/conf/distro/defaultsetup.conf</filename>.
684 </para>
685 </glossdef>
686 </glossentry>
687
688 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
689 <glossdef>
690 <para>
691 Specifies a list of distro-specific packages to add to all images.
692 This variable takes affect through
693 <filename>packagegroup-base</filename> so the
694 variable only really applies to the more full-featured
695 images that include <filename>packagegroup-base</filename>.
696 You can use this variable to keep distro policy out of
697 generic images.
698 As with all other distro variables, you set this variable
699 in the distro <filename>.conf</filename> file.
700 </para>
701 </glossdef>
702 </glossentry>
703
704 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
705 <glossdef>
706 <para>
707 Specifies a list of distro-specific packages to add to all images
708 if the packages exist.
709 The packages might not exist or be empty (e.g. kernel modules).
710 The list of packages are automatically installed but can be
711 removed by the user.
712 </para>
713 </glossdef>
714 </glossentry>
715
716 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
717 <glossdef>
718 <para>The features enabled for the distribution.
719 For a list of features supported by the Yocto Project as shipped,
720 see the "<link linkend='ref-features-distro'>Distro</link>"
721 section.
722 </para>
723 </glossdef>
724 </glossentry>
725
726 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
727 <glossdef>
728 <para>Features to be added to
729 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
730 if not also present in
731 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
732 </para>
733
734 <para>
735 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
736 It is not intended to be user-configurable.
737 It is best to just reference the variable to see which distro features are
738 being backfilled for all distro configurations.
739 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
740 more information.
741 </para>
742 </glossdef>
743 </glossentry>
744
745 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
746 <glossdef>
747 <para>Features from
748 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
749 that should not backfilled (i.e. added to
750 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
751 during the build.
752 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
753 more information.
754 </para>
755 </glossdef>
756 </glossentry>
757
758 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
759 <glossdef>
760 <para>The long name of the distribution.</para>
761 </glossdef>
762 </glossentry>
763
764 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
765 <glossdef>
766 <para>Alias names used for the recipe in various Linux distributions.</para>
767 <para>See the
768 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
769 a Package Name Alias</ulink>" section in the Yocto Project Development
770 Manual for more information.</para>
771 </glossdef>
772 </glossentry>
773
774 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
775 <glossdef>
776 <para>the version of the distribution.</para>
777 </glossdef>
778 </glossentry>
779
780 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
781 <glossdef>
782 <para>
783 The central download directory used by the build process to store downloads.
784 You can set this directory by defining the <filename>DL_DIR</filename>
785 variable in the <filename>/conf/local.conf</filename> file.
786 This directory is self-maintaining and you should not have
787 to touch it.
788 By default, the directory is <filename>downloads</filename> in the
789 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
790 <literallayout class='monospaced'>
791 #DL_DIR ?= "${TOPDIR}/downloads"
792 </literallayout>
793 To specify a different download directory, simply uncomment the line
794 and provide your directory.
795 </para>
796
797 <para>
798 During a first build, the system downloads many different source code
799 tarballs from various upstream projects.
800 Downloading can take a while, particularly if your network
801 connection is slow.
802 Tarballs are all stored in the directory defined by
803 <filename>DL_DIR</filename> and the build system looks there first
804 to find source tarballs.
805 <note>
806 When wiping and rebuilding, you can preserve this directory to speed
807 up this part of subsequent builds.
808 </note>
809 </para>
810
811 <para>
812 You can safely share this directory between multiple builds on the
813 same development machine.
814 For additional information on how the build process gets source files
815 when working behind a firewall or proxy server, see the
816 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
817 chapter.
818 </para>
819 </glossdef>
820
821 </glossentry>
822 </glossdiv>
823
824 <glossdiv id='var-glossary-e'><title>E</title>
825
826 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
827 <glossdef>
828 <para></para>
829 <para>Variable that controls which locales for <filename>eglibc</filename> are
830 to be generated during the build (useful if the target device has 64Mbytes
831 of RAM or less).</para>
832 </glossdef>
833 </glossentry>
834
835 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
836 <glossdef>
837 <para>
838 Used with file and pathnames to create a prefix for a recipe's
839 version based on the recipe's
840 <link linkend='var-PE'><filename>PE</filename></link> value.
841 If <filename>PE</filename> is set and greater than zero for a recipe,
842 <filename>EXTENDPE</filename> becomes that value (e.g if
843 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
844 becomes "1_").
845 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
846 zero, <filename>EXTENDPE</filename> becomes "".</para>
847 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
848 variable for an example.
849 </para>
850 </glossdef>
851 </glossentry>
852
853 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
854 <glossdef>
855 <para>Allows extra packages to be added to the generated images.
856 You set this variable in the <filename>local.conf</filename>
857 configuration file.
858 Note that some image features are also added using the
859 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
860 variable generally configured in image recipes.
861 You can use this variable to add more features in addition to those.
862 Here are some examples of features you can add:</para>
863 <literallayout class='monospaced'>
864"dbg-pkgs" - Adds -dbg packages for all installed packages
865 including symbol information for debugging and
866 profiling.
867
868"dev-pkgs" - Adds -dev packages for all installed packages.
869 This is useful if you want to develop against
870 the libraries in the image.
871
872"tools-sdk" - Adds development tools such as gcc, make,
873 pkgconfig and so forth.
874
875"tools-debug" - Adds debugging tools such as gdb and
876 strace.
877
878"tools-profile" - Adds profiling tools such as oprofile,
879 exmap, lttng and valgrind (x86 only).
880
881"tools-testapps" - Adds useful testing tools such as
882 ts_print, aplay, arecord and so
883 forth.
884
885"debug-tweaks" - Makes an image suitable for development.
886 For example, ssh root access has a blank
887 password. You should remove this feature
888 before you produce a production image.
889 </literallayout>
890
891 <para>There are other valid features too, see the
892 <link linkend='ref-features-image'>Images</link>
893 section for more details.</para>
894 </glossdef>
895 </glossentry>
896
897 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
898 <glossdef>
899 <para>A list of recipes to be built that do not provide packages to be installed in
900 the root filesystem.
901 </para>
902 <para>Sometimes a recipe is required to build the final image but is not
903 needed in the root filesystem.
904 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
905 list these recipes and thus, specify the dependencies.
906 A typical example is a required bootloader in a machine configuration.
907 </para>
908 <note>
909 To add packages to the root filesystem, see the various
910 <filename>*DEPENDS</filename> and <filename>*RECOMMENDS</filename>
911 variables.
912 </note>
913 </glossdef>
914 </glossentry>
915
916 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
917 <glossdef>
918 <para>Additional <filename>cmake</filename> options.</para>
919 </glossdef>
920 </glossentry>
921
922 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
923 <glossdef>
924 <para>Additional <filename>configure</filename> script options.</para>
925 </glossdef>
926 </glossentry>
927
928 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
929 <glossdef>
930 <para>Additional GNU <filename>make</filename> options.</para>
931 </glossdef>
932 </glossentry>
933
934 </glossdiv>
935
936 <glossdiv id='var-glossary-f'><title>F</title>
937
938 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
939 <glossdef>
940 <para>
941 The list of directories or files that are placed in packages.
942 </para>
943
944 <para>
945 To use the <filename>FILES</filename> variable, provide a package name
946 override that identifies the resulting package.
947 Then, provide a space-separated list of files or paths that identifies the
948 files you want included as part of the resulting package.
949 Here is an example:
950 <literallayout class='monospaced'>
951 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
952 </literallayout>
953 </para>
954
955 <note>
956 When specifying paths as part of the <filename>FILES</filename> variable,
957 it is good practice to use appropriate path variables.
958 For example, <filename>${sysconfdir}</filename> rather than
959 <filename>/etc</filename> or <filename>${bindir}</filename> rather
960 than <filename>/usr/bin</filename>.
961 You can find a list of these variables at the top of the
962 <filename>/meta/conf/bitbake.conf</filename> file in the
963 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
964 </note>
965
966 <para>
967 If some of the files you provide with the <filename>FILES</filename> variable
968 are editable and you know they should not be
969 overwritten during the package update process by the Package Management
970 System (PMS), you can identify these files so that the PMS will not
971 overwrite them.
972 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
973 variable for information on how to identify these files to the PMS.
974 </para>
975
976 </glossdef>
977 </glossentry>
978
979 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
980 <glossdef>
981 <para>
982 Extends the search path the OpenEmbedded build system uses when
983 looking for files and patches as it processes recipes.
984 The directories BitBake uses when it processes recipes is defined by the
985 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> variable.
986 You can add directories to the search path by defining the
987 <filename>FILESEXTRAPATHS</filename> variable.
988 </para>
989
990 <para>
991 To add paths to the search order, provide a list of directories and separate
992 each path using a colon character as follows:
993 <literallayout class='monospaced'>
994 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
995 </literallayout>
996 Typically, you want your directories searched first.
997 To make sure that happens, use <filename>_prepend</filename> and
998 the immediate expansion (<filename>:=</filename>) operator as shown in the
999 previous example.
1000 Finally, to maintain the integrity of the <filename>FILESPATH</filename> variable,
1001 you must include the appropriate beginning or ending (as needed) colon character.
1002 </para>
1003
1004 <para>
1005 The <filename>FILESEXTRAPATHS</filename> variable is intended for use in
1006 <filename>.bbappend</filename> files to include any additional files provided in that layer.
1007 You typically accomplish this with the following:
1008 <literallayout class='monospaced'>
1009 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1010 </literallayout>
1011 </para>
1012 </glossdef>
1013 </glossentry>
1014
1015 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
1016 <glossdef>
1017 <para>
1018 The default set of directories the OpenEmbedded build system uses
1019 when searching for patches and files.
1020 During the build process, BitBake searches each directory in
1021 <filename>FILESPATH</filename> in the specified order when looking for
1022 files and patches specified by each <filename>file://</filename> URI in a recipe.
1023 </para>
1024
1025 <para>
1026 The default value for the <filename>FILESPATH</filename> variable is defined
1027 in the <filename>base.bbclass</filename> class found in
1028 <filename>meta/classes</filename> in the
1029 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
1030 <literallayout class='monospaced'>
1031FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1032 "${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \
1033 "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \
1034 "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}"
1035 </literallayout>
1036 Do not hand-edit the <filename>FILESPATH</filename> variable.
1037 If you want to extend the set of pathnames that BitBake uses when searching for
1038 files and patches, use the
1039 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> variable.
1040 </para>
1041 </glossdef>
1042 </glossentry>
1043
1044 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
1045 <glossdef>
1046 <para>Allows you to define your own file permissions settings table as part of
1047 your configuration for the packaging process.
1048 For example, suppose you need a consistent set of custom permissions for
1049 a set of groups and users across an entire work project.
1050 It is best to do this in the packages themselves but this is not always
1051 possible.
1052 </para>
1053 <para>
1054 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
1055 is located in the <filename>meta/files</filename> folder in the
1056 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1057 If you create your own file permissions setting table, you should place it in your
1058 layer or the distros layer.
1059 </para>
1060 <para>
1061 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
1062 <filename>conf/local.conf</filename> file, which is found in the
1063 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
1064 point to your custom <filename>fs-perms.txt</filename>.
1065 You can specify more than a single file permissions setting table.
1066 The paths you specify to these files must be defined within the
1067 <filename>BBPATH</filename> variable.
1068 </para>
1069 <para>
1070 For guidance on how to create your own file permissions settings table file,
1071 examine the existing <filename>fs-perms.txt</filename>.
1072 </para>
1073 </glossdef>
1074 </glossentry>
1075
1076 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
1077 <glossdef>
1078 <para>
1079 The options to pass in
1080 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1081 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
1082 when compiling an optimized system.
1083 This variable defaults to
1084 "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
1085 </para>
1086 </glossdef>
1087 </glossentry>
1088
1089 </glossdiv>
1090
1091<!-- <glossdiv id='var-glossary-g'><title>G</title>-->
1092<!-- </glossdiv>-->
1093
1094 <glossdiv id='var-glossary-h'><title>H</title>
1095
1096 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
1097 <glossdef>
1098 <para>Website where more information about the software the recipe is building
1099 can be found.</para>
1100 </glossdef>
1101 </glossentry>
1102
1103 </glossdiv>
1104
1105 <glossdiv id='var-glossary-i'><title>I</title>
1106
1107 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
1108 <glossdef>
1109 <para>The list of features to include in an image.
1110 Typically, you configure this variable in an image recipe.
1111 Note that you can also add extra features to the image by using the
1112 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
1113 See the "<link linkend="ref-features-image">Images</link>" section for the
1114 full list of features that can be included in images built by the
1115 OpenEmbedded build system.</para>
1116 </glossdef>
1117 </glossentry>
1118
1119 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
1120 <glossdef>
1121 <para>Formats of root filesystem images that you want to have created.</para>
1122 </glossdef>
1123 </glossentry>
1124
1125 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
1126 <glossdef>
1127 <para>
1128 Specifies the packages to install into an image.
1129 The <filename>IMAGE_INSTALL</filename> variable is a mechanism for an image
1130 recipe and you should use it with care to avoid ordering issues.
1131 </para>
1132
1133 <para>
1134 Image recipes set <filename>IMAGE_INSTALL</filename> to specify the
1135 packages to install into an image through <filename>image.bbclass</filename>.
1136 Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>,
1137 that can take
1138 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists
1139 and turn these into auto-generated entries in
1140 <filename>IMAGE_INSTALL</filename> in addition to its default contents.
1141 </para>
1142
1143 <para>
1144 Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename>
1145 operator from the <filename>/conf/local.conf</filename> file or from within
1146 an image recipe is not recommended as it can cause ordering issues.
1147 Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename>
1148 to a default value using the <filename>?=</filename> operator, using a
1149 <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename>
1150 will result in unexpected behavior when used in
1151 <filename>/conf/local.conf</filename>.
1152 Furthermore, the same operation from with an image recipe may or may not
1153 succeed depending on the specific situation.
1154 In both these cases, the behavior is contrary to how most users expect
1155 the <filename>+=</filename> operator to work.
1156 </para>
1157
1158 <para>
1159 When you use this variable, it is best to use it as follows:
1160 <literallayout class='monospaced'>
1161 IMAGE_INSTALL_append = " package-name"
1162 </literallayout>
1163 Be sure to include the space between the quotation character and the start of the
1164 package name.
1165 </para>
1166 </glossdef>
1167 </glossentry>
1168
1169 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
1170 <glossdef>
1171 <para>
1172 Defines a multiplier that the build system applies to the initial image
1173 size for cases when the multiplier times the returned disk usage value
1174 for the image is greater than the sum of
1175 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
1176 and
1177 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
1178 The result of the multiplier applied to the initial image size creates
1179 free disk space in the image as overhead.
1180 By default, the build process uses a multiplier of 1.3 for this variable.
1181 This default value results in 30% free disk space added to the image when this
1182 method is used to determine the final generated image size.
1183 You should be aware that post install scripts and the package management
1184 system uses disk space inside this overhead area.
1185 Consequently, the multiplier does not produce an image with
1186 all the theoretical free disk space.
1187 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
1188 for information on how the build system determines the overall image size.
1189 </para>
1190
1191 <para>
1192 The default 30% free disk space typically gives the image enough room to boot
1193 and allows for basic post installs while still leaving a small amount of
1194 free disk space.
1195 If 30% free space is inadequate, you can increase the default value.
1196 For example, the following setting gives you 50% free space added to the image:
1197 <literallayout class='monospaced'>
1198 IMAGE_OVERHEAD_FACTOR = "1.5"
1199 </literallayout>
1200 </para>
1201
1202 <para>
1203 Alternatively, you can ensure a specific amount of free disk space is added
1204 to the image by using
1205 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
1206 the variable.
1207 </para>
1208 </glossdef>
1209 </glossentry>
1210
1211 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
1212 <glossdef>
1213 <para>
1214 Defines additional free disk space created in the image in Kbytes.
1215 By default, this variable is set to "0".
1216 This free disk space is added to the image after the build system determines
1217 the image size as described in
1218 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
1219 </para>
1220
1221 <para>
1222 This variable is particularly useful when you want to ensure that a
1223 specific amount of free disk space is available on a device after an image
1224 is installed and running.
1225 For example, to be sure 5 Gbytes of free disk space is available, set the
1226 variable as follows:
1227 <literallayout class='monospaced'>
1228 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
1229 </literallayout>
1230 </para>
1231 </glossdef>
1232 </glossentry>
1233
1234 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
1235 <glossdef>
1236 <para>
1237 Defines the size in Kbytes for the generated image.
1238 The OpenEmbedded build system determines the final size for the generated
1239 image using an algorithm that takes into account the initial disk space used
1240 for the generated image, a requested size for the image, and requested
1241 additional free disk space to be added to the image.
1242 Programatically, the build system determines the final size of the
1243 generated image as follows:
1244 <literallayout class='monospaced'>
1245 if (image-du * overhead) &lt; rootfs-size:
1246 internal-rootfs-size = rootfs-size + xspace
1247 else:
1248 internal-rootfs-size = (image-du * overhead) + xspace
1249
1250 where:
1251
1252 image-du = Returned value of the du command on
1253 the image.
1254
1255 overhead = IMAGE_OVERHEAD_FACTOR
1256
1257 rootfs-size = IMAGE_ROOTFS_SIZE
1258
1259 internal-rootfs-size = Initial root filesystem
1260 size before any modifications.
1261
1262 xspace = IMAGE_ROOTFS_EXTRA_SPACE
1263 </literallayout>
1264<!-- In the above example, <filename>overhead</filename> is defined by the
1265 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
1266 variable, <filename>xspace</filename> is defined by the
1267 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
1268 variable, and <filename>du</filename> is the results of the disk usage command
1269 on the initially generated image. -->
1270 </para>
1271 </glossdef>
1272 </glossentry>
1273
1274 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
1275 <glossdef>
1276 <para>Helps define the recipe revision for recipes that share
1277 a common <filename>include</filename> file.
1278 You can think of this variable as part of the recipe revision
1279 as set from within an include file.</para>
1280 <para>Suppose, for example, you have a set of recipes that
1281 are used across several projects.
1282 And, within each of those recipes the revision
1283 (its <filename>PR</filename> value) is set accordingly.
1284 In this case, when the revision of those recipes changes
1285 the burden is on you to find all those recipes and
1286 be sure that they get changed to reflect the updated
1287 version of the recipe.
1288 In this scenario, it can get complicated when recipes
1289 used in many places and that provide common functionality
1290 are upgraded to a new revision.</para>
1291 <para>A more efficient way of dealing with this situation is
1292 to set the <filename>INC_PR</filename> variable inside
1293 the <filename>include</filename> files that the recipes
1294 share and then expand the <filename>INC_PR</filename>
1295 variable within the recipes to help
1296 define the recipe revision.
1297 </para>
1298 <para>
1299 The following provides an example that shows how to use
1300 the <filename>INC_PR</filename> variable
1301 given a common <filename>include</filename> file that
1302 defines the variable.
1303 Once the variable is defined in the
1304 <filename>include</filename> file, you can use the
1305 variable to set the <filename>PR</filename> values in
1306 each recipe.
1307 You will notice that when you set a recipe's
1308 <filename>PR</filename> you can provide more granular
1309 revisioning by appending values to the
1310 <filename>INC_PR</filename> variable:
1311 <literallayout class='monospaced'>
1312recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
1313recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
1314recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
1315recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1316 </literallayout>
1317 The first line of the example establishes the baseline
1318 revision to be used for all recipes that use the
1319 <filename>include</filename> file.
1320 The remaining lines in the example are from individual
1321 recipes and show how the <filename>PR</filename> value
1322 is set.</para>
1323 </glossdef>
1324 </glossentry>
1325
1326 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
1327 <glossdef>
1328 <para>
1329 Causes the build to not strip binaries in resulting packages.
1330 </para>
1331 </glossdef>
1332 </glossentry>
1333
1334
1335 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
1336 <glossdef>
1337 <para>
1338 Causes the named class to be inherited at
1339 this point during parsing.
1340 The variable is only valid in configuration files.
1341 </para>
1342 </glossdef>
1343 </glossentry>
1344
1345
1346 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
1347 <glossdef>
1348 <para>
1349 A list of the packages that contain initscripts.
1350 If multiple packages are specified, you need to append the package name
1351 to the other <filename>INITSCRIPT_*</filename> as an override.</para>
1352 <para>
1353 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
1354 The variable is optional and defaults to the <filename>PN</filename> variable.
1355 </para>
1356 </glossdef>
1357 </glossentry>
1358
1359 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
1360 <glossdef>
1361 <para>
1362 The filename of the initscript (as installed to <filename>${etcdir}/init.d)</filename>.
1363 </para>
1364 <para>
1365 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
1366 The variable is Mandatory.
1367 </para>
1368 </glossdef>
1369 </glossentry>
1370
1371 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
1372 <glossdef>
1373 <para>
1374 Specifies the options to pass to <filename>update-rc.d</filename>.
1375 An example is <filename>start 99 5 2 . stop 20 0 1 6 .</filename>, which gives the script a
1376 runlevel of 99, starts the script in initlevels 2 and 5, and
1377 stops the script in levels 0, 1 and 6.
1378 </para>
1379 <para>
1380 The variable is mandatory and is used in recipes when using
1381 <filename>update-rc.d.bbclass</filename>.
1382 </para>
1383 </glossdef>
1384 </glossentry>
1385
1386
1387 </glossdiv>
1388
1389<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
1390<!-- </glossdiv>-->
1391
1392 <glossdiv id='var-glossary-k'><title>K</title>
1393
1394 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
1395 <glossdef>
1396 <para>
1397 A regular expression used by the build process to explicitly identify the kernel
1398 branch that is validated, patched and configured during a build.
1399 The <filename>KBRANCH</filename> variable is optional.
1400 You can use it to trigger checks to ensure the exact kernel branch you want is
1401 being used by the build process.
1402 </para>
1403
1404 <para>
1405 Values for this variable are set in the kernel's recipe file and the kernel's
1406 append file.
1407 For example, if you are using the Yocto Project kernel that is based on the
1408 Linux 3.4 kernel, the kernel recipe file is the
1409 <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> file.
1410 Following is the default value for <filename>KBRANCH</filename> and the default
1411 override for the architectures the Yocto Project supports:
1412 <literallayout class='monospaced'>
1413 KBRANCH_DEFAULT = "standard/base"
1414 KBRANCH = "${KBRANCH_DEFAULT}"
1415 </literallayout>
1416 This branch exists in the <filename>linux-yocto-3.4</filename> kernel Git
1417 repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
1418 </para>
1419
1420 <para>
1421 This variable is also used from the kernel's append file to identify the kernel
1422 branch specific to a particular machine or target hardware.
1423 The kernel's append file is located in the BSP layer for a given machine.
1424 For example, the kernel append file for the Crown Bay BSP is in the
1425 <filename>meta-intel</filename> Git repository and is named
1426 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>.
1427 Here are the related statements from the append file:
1428 <literallayout class='monospaced'>
1429 COMPATIBLE_MACHINE_crownbay = "crownbay"
1430 KMACHINE_crownbay = "crownbay"
1431 KBRANCH_crownbay = "standard/crownbay"
1432
1433 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
1434 KMACHINE_crownbay-noemgd = "crownbay"
1435 KBRANCH_crownbay-noemgd = "standard/crownbay"
1436 </literallayout>
1437 The <filename>KBRANCH_*</filename> statements identify the kernel branch to
1438 use when building for the Crown Bay BSP.
1439 In this case there are two identical statements: one for each type of
1440 Crown Bay machine.
1441 </para>
1442 </glossdef>
1443 </glossentry>
1444
1445 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
1446 <glossdef>
1447 <para>Includes additional metadata from the Yocto Project kernel Git repository.
1448 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
1449 metadata is provided through
1450 the <filename>KMACHINE</filename> and <filename>KBRANCH</filename> variables.
1451 You can use the <filename>KERNEL_FEATURES</filename> variable to further
1452 add metadata for all BSPs.</para>
1453 <para>The metadata you add through this variable includes config fragments and
1454 features descriptions,
1455 which usually includes patches as well as config fragments.
1456 You typically override the <filename>KERNEL_FEATURES</filename> variable
1457 for a specific machine.
1458 In this way, you can provide validated, but optional, sets of kernel
1459 configurations and features.</para>
1460 <para>For example, the following adds <filename>netfilter</filename> to all
1461 the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
1462 machine:
1463 <literallayout class='monospaced'>
1464 # Add netfilter to all linux-yocto kernels
1465 KERNEL_FEATURES="features/netfilter"
1466
1467 # Add sound support to the qemux86 machine
1468 KERNEL_FEATURES_append_qemux86=" cfg/sound"
1469 </literallayout></para>
1470 </glossdef>
1471 </glossentry>
1472
1473 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
1474 <glossdef>
1475 <para>The type of kernel to build for a device, usually set by the
1476 machine configuration files and defaults to "zImage".
1477 This variable is used
1478 when building the kernel and is passed to <filename>make</filename> as the target to
1479 build.</para>
1480 </glossdef>
1481 </glossentry>
1482
1483 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
1484 <glossdef>
1485 <para>
1486 The machine as known by the kernel.
1487 Sometimes the machine name used by the kernel does not match the machine name
1488 used by the OpenEmbedded build system.
1489 For example, the machine name that the OpenEmbedded build system understands as
1490 <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
1491 The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
1492 For cases like these, the <filename>KMACHINE</filename> variable maps the
1493 kernel machine name to the OpenEmbedded build system machine name.
1494 </para>
1495
1496 <para>
1497 Kernel machine names are initially defined in the
1498 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Yocto Linux Kernel</ulink> in
1499 the <filename>meta</filename> branch.
1500 From the <filename>meta</filename> branch, look in
1501 the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
1502 For example, from the <filename>meta</filename> branch in the
1503 <filename>linux-yocto-3.0</filename> kernel, the
1504 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
1505 has the following:
1506 <literallayout class='monospaced'>
1507 define KMACHINE cedartrail
1508 define KTYPE standard
1509 define KARCH i386
1510
1511 include ktypes/standard
1512 branch cedartrail
1513
1514 include cedartrail.scc
1515 </literallayout>
1516 You can see that the kernel understands the machine name for the Cedar Trail BSP as
1517 <filename>cedartrail</filename>.
1518 </para>
1519
1520 <para>
1521 If you look in the Cedar Trail BSP layer in the <filename>meta-intel</filename> source
1522 repository at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
1523 you will find the following statements among others:
1524 <literallayout class='monospaced'>
1525 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
1526 KMACHINE_cedartrail = "cedartrail"
1527 KBRANCH_cedartrail = "yocto/standard/cedartrail"
1528 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
1529 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
1530
1531 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
1532 KMACHINE_cedartrail-nopvr = "cedartrail"
1533 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
1534 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
1535 </literallayout>
1536 The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
1537 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
1538 names.
1539 </para>
1540
1541 <para>
1542 This append file uses two <filename>KMACHINE</filename> statements.
1543 The first is not really necessary but does ensure that the machine known to the
1544 OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
1545 in the kernel also known as <filename>cedartrail</filename>:
1546 <literallayout class='monospaced'>
1547 KMACHINE_cedartrail = "cedartrail"
1548 </literallayout>
1549 </para>
1550
1551 <para>
1552 The second statement is a good example of why the <filename>KMACHINE</filename> variable
1553 is needed.
1554 In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
1555 machine name to refer to the Cedar Trail BSP that does not support the propriatory
1556 PowerVR driver.
1557 The kernel, however, uses the machine name <filename>cedartrail</filename>.
1558 Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
1559 the kernel's <filename>cedartrail</filename> name:
1560 <literallayout class='monospaced'>
1561 KMACHINE_cedartrail-nopvr = "cedartrail"
1562 </literallayout>
1563 </para>
1564
1565 <para>
1566 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
1567 Project kernel machine names and the OpenEmbedded machine names.
1568 Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
1569 name you use is different than that used in the kernel.
1570 </para>
1571 </glossdef>
1572 </glossentry>
1573
1574 </glossdiv>
1575
1576 <glossdiv id='var-glossary-l'><title>L</title>
1577
1578 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
1579 <glossdef>
1580 <para>Lists the layers that this recipe depends upon, separated by spaces.
1581 Optionally, you can specify a specific layer version for a dependency
1582 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
1583 to be compared against <filename>LAYERVERSION_anotherlayer</filename> in this case).
1584 An error will be produced if any dependency is missing or
1585 the version numbers do not match exactly (if specified).
1586 This variable is used in the <filename>conf/layer.conf</filename> file
1587 and must be suffixed with the name of the specific layer (e.g.
1588 <filename>LAYERDEPENDS_mylayer</filename>).</para>
1589 </glossdef>
1590 </glossentry>
1591
1592 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
1593 <glossdef>
1594 <para>When used inside the <filename>layer.conf</filename> configuration
1595 file, this variable provides the path of the current layer.
1596 This variable requires immediate expansion
1597 (see the BitBake manual) as lazy expansion can result in
1598 the expansion happening in the wrong directory and therefore
1599 giving the wrong value.</para>
1600 </glossdef>
1601 </glossentry>
1602
1603 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
1604 <glossdef>
1605 <para>Optionally specifies the version of a layer as a single number.
1606 You can use this within <filename>LAYERDEPENDS</filename> for another layer in order to
1607 depend on a specific version of the layer.
1608 This variable is used in the <filename>conf/layer.conf</filename> file
1609 and must be suffixed with the name of the specific layer (e.g.
1610 <filename>LAYERVERSION_mylayer</filename>).</para>
1611 </glossdef>
1612 </glossentry>
1613
1614 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
1615 <glossdef>
1616 <para>Checksums of the license text in the recipe source code.</para>
1617 <para>This variable tracks changes in license text of the source
1618 code files.
1619 If the license text is changed, it will trigger a build
1620 failure, which gives the developer an opportunity to review any
1621 license change.</para>
1622 <para>
1623 This variable must be defined for all recipes (unless <filename>LICENSE</filename>
1624 is set to "CLOSED")</para>
1625 <para>For more information, see the
1626 <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
1627 Tracking License Changes</link> section</para>
1628 </glossdef>
1629 </glossentry>
1630
1631 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
1632 <glossdef>
1633 <para>
1634 The list of source licenses for the recipe.
1635 Follow these rules:
1636 <itemizedlist>
1637 <listitem><para>Do not use spaces within individual
1638 license names.</para></listitem>
1639 <listitem><para>Separate license names using
1640 | (pipe) when there is a choice between licenses.
1641 </para></listitem>
1642 <listitem><para>Separate license names using
1643 &amp; (ampersand) when multiple licenses exist
1644 that cover different parts of the source.
1645 </para></listitem>
1646 <listitem><para>You can use spaces between license
1647 names.</para></listitem>
1648 </itemizedlist>
1649 </para>
1650
1651 <para>
1652 Here are some examples:
1653 <literallayout class='monospaced'>
1654 LICENSE = "LGPLv2.1 | GPLv3"
1655 LICENSE = "MPL-1 &amp; LGPLv2.1"
1656 LICENSE = "GPLv2+"
1657 </literallayout>
1658 The first example is from the recipes for Qt, which the user
1659 may choose to distribute under either the LGPL version
1660 2.1 or GPL version 3.
1661 The second example is from Cairo where two licenses cover
1662 different parts of the source code.
1663 The final example is from <filename>sysstat</filename>,
1664 which presents a single license.
1665 </para>
1666 </glossdef>
1667 </glossentry>
1668
1669 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
1670 <glossdef>
1671 <para>Path to additional licenses used during the build.
1672 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
1673 to define the directory that holds common license text used during the build.
1674 The <filename>LICENSE_PATH</filename> variable allows you to extend that
1675 location to other areas that have additional licenses:
1676 <literallayout class='monospaced'>
1677 LICENSE_PATH += "/path/to/additional/common/licenses"
1678 </literallayout></para>
1679 </glossdef>
1680 </glossentry>
1681
1682 </glossdiv>
1683
1684 <glossdiv id='var-glossary-m'><title>M</title>
1685
1686 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
1687 <glossdef>
1688 <para>
1689 Specifies the target device for which the image is built.
1690 You define <filename>MACHINE</filename> in the
1691 <filename>local.conf</filename> file found in the
1692 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1693 By default, <filename>MACHINE</filename> is set to
1694 "qemux86", which is an x86-based architecture machine to
1695 be emulated using QEMU:
1696 <literallayout class='monospaced'>
1697 MACHINE ?= "qemux86"
1698 </literallayout>
1699 The variable corresponds to a machine configuration file of the
1700 same name, through which machine-specific configurations are set.
1701 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
1702 exists the corresponding <filename>qemux86.conf</filename> machine
1703 configuration file, which can be found in the
1704 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
1705 in <filename>meta/conf/machine</filename>.
1706 </para>
1707
1708 <para>
1709 The list of machines supported by the Yocto Project as
1710 shipped include the following:
1711 <literallayout class='monospaced'>
1712 MACHINE ?= "qemuarm"
1713 MACHINE ?= "qemumips"
1714 MACHINE ?= "qemuppc"
1715 MACHINE ?= "qemux86"
1716 MACHINE ?= "qemux86-64"
1717 MACHINE ?= "atom-pc"
1718 MACHINE ?= "beagleboard"
1719 MACHINE ?= "mpc8315e-rdb"
1720 MACHINE ?= "routerstationpro"
1721 </literallayout>
1722 The last four are Yocto Project reference hardware boards, which
1723 are provided in the <filename>meta-yocto-bsp</filename> layer.
1724 <note>Adding additional Board Support Package (BSP) layers
1725 to your configuration adds new possible settings for
1726 <filename>MACHINE</filename>.
1727 </note>
1728 </para>
1729 </glossdef>
1730 </glossentry>
1731
1732 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
1733 <glossdef>
1734 <para></para>
1735 <para>
1736 A list of required machine-specific packages to install as part of
1737 the image being built.
1738 The build process depends on these packages being present.
1739 Furthermore, because this is a "machine essential" variable, the list of
1740 packages are essential for the machine to boot.
1741 The impact of this variable affects images based on
1742 <filename>packagegroup-core-boot</filename>,
1743 including the <filename>core-image-minimal</filename> image.
1744 </para>
1745 <para>
1746 This variable is similar to the
1747 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
1748 variable with the exception that the image being built has a build
1749 dependency on the variable's list of packages.
1750 In other words, the image will not build if a file in this list is not found.
1751 </para>
1752 <para>
1753 As an example, suppose the machine for which you are building requires
1754 <filename>example-init</filename> to be run during boot to initialize the hardware.
1755 In this case, you would use the following in the machine's
1756 <filename>.conf</filename> configuration file:
1757 <literallayout class='monospaced'>
1758 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
1759 </literallayout>
1760 </para>
1761 </glossdef>
1762 </glossentry>
1763
1764 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
1765 <glossdef>
1766 <para></para>
1767 <para>
1768 A list of recommended machine-specific packages to install as part of
1769 the image being built.
1770 The build process does not depend on these packages being present.
1771 However, because this is a "machine essential" variable, the list of
1772 packages are essential for the machine to boot.
1773 The impact of this variable affects images based on
1774 <filename>packagegroup-core-boot</filename>,
1775 including the <filename>core-image-minimal</filename> image.
1776 </para>
1777 <para>
1778 This variable is similar to the
1779 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
1780 variable with the exception that the image being built does not have a build
1781 dependency on the variable's list of packages.
1782 In other words, the image will still build if a package in this list is not found.
1783 Typically, this variable is used to handle essential kernel modules, whose
1784 functionality may be selected to be built into the kernel rather than as a module,
1785 in which case a package will not be produced.
1786 </para>
1787 <para>
1788 Consider an example where you have a custom kernel where a specific touchscreen
1789 driver is required for the machine to be usable.
1790 However, the driver can be built as a module or
1791 into the kernel depending on the kernel configuration.
1792 If the driver is built as a module, you want it to be installed.
1793 But, when the driver is built into the kernel, you still want the
1794 build to succeed.
1795 This variable sets up a "recommends" relationship so that in the latter case,
1796 the build will not fail due to the missing package.
1797 To accomplish this, assuming the package for the module was called
1798 <filename>kernel-module-ab123</filename>, you would use the
1799 following in the machine's <filename>.conf</filename> configuration
1800 file:
1801 <literallayout class='monospaced'>
1802 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
1803 </literallayout>
1804 </para>
1805 <para>
1806 Some examples of these machine essentials are flash, screen, keyboard, mouse,
1807 or touchscreen drivers (depending on the machine).
1808 </para>
1809 </glossdef>
1810 </glossentry>
1811
1812 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
1813 <glossdef>
1814 <para>
1815 A list of machine-specific packages to install as part of the
1816 image being built that are not essential for the machine to boot.
1817 However, the build process for more fully-featured images
1818 depends on the packages being present.
1819 </para>
1820 <para>
1821 This variable affects all images based on
1822 <filename>packagegroup-base</filename>, which does not include the
1823 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
1824 images.
1825 </para>
1826 <para>
1827 The variable is similar to the
1828 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
1829 variable with the exception that the image being built has a build
1830 dependency on the variable's list of packages.
1831 In other words, the image will not build if a file in this list is not found.
1832 </para>
1833 <para>
1834 An example is a machine that has WiFi capability but is not essential
1835 For the machine to boot the image.
1836 However, if you are building a more fully-featured image, you want to enable
1837 the WiFi.
1838 The package containing the firmware for the WiFi hardware is always
1839 expected to exist, so it is acceptable for the build process to depend upon
1840 finding the package.
1841 In this case, assuming the package for the firmware was called
1842 <filename>wifidriver-firmware</filename>, you would use the following in the
1843 <filename>.conf</filename> file for the machine:
1844 <literallayout class='monospaced'>
1845 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
1846 </literallayout>
1847 </para>
1848 </glossdef>
1849 </glossentry>
1850
1851 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
1852 <glossdef>
1853 <para></para>
1854 <para>
1855 A list of machine-specific packages to install as part of the
1856 image being built that are not essential for booting the machine.
1857 The image being built has no build dependency on this list of packages.
1858 </para>
1859 <para>
1860 This variable affects only images based on
1861 <filename>packagegroup-base</filename>, which does not include the
1862 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
1863 images.
1864 </para>
1865 <para>
1866 This variable is similar to the
1867 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
1868 variable with the exception that the image being built does not have a build
1869 dependency on the variable's list of packages.
1870 In other words, the image will build if a file in this list is not found.
1871 </para>
1872 <para>
1873 An example is a machine that has WiFi capability but is not essential
1874 For the machine to boot the image.
1875 However, if you are building a more fully-featured image, you want to enable
1876 WiFi.
1877 In this case, the package containing the WiFi kernel module will not be produced
1878 if the WiFi driver is built into the kernel, in which case you still want the
1879 build to succeed instead of failing as a result of the package not being found.
1880 To accomplish this, assuming the package for the module was called
1881 <filename>kernel-module-examplewifi</filename>, you would use the
1882 following in the <filename>.conf</filename> file for the machine:
1883 <literallayout class='monospaced'>
1884 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
1885 </literallayout>
1886 </para>
1887 </glossdef>
1888 </glossentry>
1889
1890 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
1891 <glossdef>
1892 <para>Specifies the list of hardware features the
1893 <link linkend='var-MACHINE'>MACHINE</link> supports.
1894 For example, including the "bluetooth" feature causes the
1895 <filename>bluez</filename> bluetooth daemon to be built and
1896 added to the image.
1897 It also causes the <filename>connman</filename> recipe
1898 to look at <filename>MACHINE_FEATURES</filename> and when it
1899 finds "bluetooth" there it enables the bluetooth
1900 support in ConnMan.
1901 </para>
1902
1903 <para>
1904 For a list of features supported by the Yocto Project as shipped,
1905 see the "<link linkend='ref-features-machine'>Machine</link>" section.
1906 </para>
1907 </glossdef>
1908 </glossentry>
1909
1910 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
1911 <glossdef>
1912 <para>Features to be added to
1913 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
1914 if not also present in
1915 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
1916 </para>
1917
1918 <para>
1919 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
1920 It is not intended to be user-configurable.
1921 It is best to just reference the variable to see which machine features are
1922 being backfilled for all machine configurations.
1923 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1924 more information.
1925 </para>
1926 </glossdef>
1927 </glossentry>
1928
1929 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
1930 <glossdef>
1931 <para>Features from
1932 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
1933 that should not be backfilled (i.e. added to
1934 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
1935 during the build.
1936 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1937 more information.
1938 </para>
1939 </glossdef>
1940 </glossentry>
1941
1942 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
1943 <glossdef>
1944 <para>The email address of the distribution maintainer.</para>
1945 </glossdef>
1946 </glossentry>
1947
1948 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
1949 <glossdef>
1950 <para>
1951 Specifies a prefix has been added to
1952 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
1953 of a recipe or package, such as a multilib version.
1954 The variable is used in places where the prefix needs to be
1955 added to or removed from a the name (e.g. the
1956 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
1957 <filename>MLPREFIX</filename> gets set when a prefix has been
1958 added to <filename>PN</filename>.
1959 </para>
1960 </glossdef>
1961 </glossentry>
1962
1963 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
1964 <glossdef>
1965 <para>
1966 Separates files for different machines such that you can build
1967 for multiple target machines using the same output directories.
1968 See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable
1969 for an example.
1970 </para>
1971 </glossdef>
1972 </glossentry>
1973
1974 </glossdiv>
1975
1976<!-- <glossdiv id='var-glossary-n'><title>N</title>-->
1977<!-- </glossdiv>-->
1978
1979 <glossdiv id='var-glossary-o'><title>O</title>
1980
1981 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
1982 <glossdef>
1983 <para>
1984 Controls how the OpenEmbedded build system spawns
1985 interactive terminals on the host development system
1986 (e.g. using the BitBake command with the
1987 <filename>-c devshell</filename> command-line option).
1988 For more information, see the
1989 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
1990 in the Yocto Project Development Manual.
1991 </para>
1992
1993 <para>
1994 You can use the following values for the
1995 <filename>OE_TERMINAL</filename> variable:
1996 <literallayout class='monospaced'>
1997 auto
1998 gnome
1999 xfce
2000 rxvt
2001 screen
2002 konsole
2003 none
2004 </literallayout>
2005 <note>Konsole support only works for KDE 3.x.
2006 Also, "auto" is the default behavior for
2007 <filename>OE_TERMINAL</filename></note>
2008 </para>
2009 </glossdef>
2010 </glossentry>
2011 </glossdiv>
2012
2013 <glossdiv id='var-glossary-p'><title>P</title>
2014
2015 <glossentry id='var-P'><glossterm>P</glossterm>
2016 <glossdef>
2017 <para>The recipe name and version.
2018 <filename>P</filename> is comprised of the following:
2019 <literallayout class='monospaced'>
2020 ${PN}-${PV}
2021 </literallayout></para>
2022 </glossdef>
2023 </glossentry>
2024
2025 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
2026 <glossdef>
2027 <para>The architecture of the resulting package or packages.</para>
2028 </glossdef>
2029 </glossentry>
2030
2031 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
2032 <glossdef>
2033 <para>Enables easily adding packages to
2034 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
2035 before <filename>${PN}</filename> so that the packages can pick
2036 up files that would normally be included in the default package.</para>
2037 </glossdef>
2038 </glossentry>
2039
2040 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
2041 <glossdef>
2042 <para>This variable, which is set in the <filename>local.conf</filename> configuration
2043 file found in the <filename>conf</filename> folder of the
2044 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
2045 specifies the package manager to use when packaging data.
2046 You can provide one or more arguments for the variable with the first
2047 argument being the package manager used to create images:
2048 <literallayout class='monospaced'>
2049 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
2050 </literallayout>
2051 For information on build performance effects as a result of the
2052 package manager use, see
2053 <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link>
2054 in this manual.
2055 </para>
2056 </glossdef>
2057 </glossentry>
2058
2059 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
2060 <glossdef>
2061 <para>Specifies the list of architectures compatible with the device CPU.
2062 This variable is useful when you build for several different devices that use
2063 miscellaneous processors such as XScale and ARM926-EJS).</para>
2064 </glossdef>
2065 </glossentry>
2066
2067 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
2068 <glossdef>
2069 <para>
2070 This variable provides a means of enabling or disabling
2071 features of a recipe on a per-recipe basis.
2072 The <filename>PACKAGECONFIG</filename>
2073 variable itself specifies a space-separated list of the
2074 features to enable.
2075 The features themselves are specified as flags on the
2076 <filename>PACKAGECONFIG</filename> variable.
2077 You can provide up to four arguments, which are separated by
2078 commas, to determine the behavior of each feature
2079 when it is enabled or disabled.
2080 You can omit any argument you like but must retain the
2081 separating commas.
2082 The arguments specify the following:
2083 <orderedlist>
2084 <listitem><para>Extra arguments
2085 that should be added to the configure script argument list
2086 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
2087 if the feature is enabled.</para></listitem>
2088 <listitem><para>Extra arguments
2089 that should be added to <filename>EXTRA_OECONF</filename>
2090 if the feature is disabled.
2091 </para></listitem>
2092 <listitem><para>Additional build dependencies
2093 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
2094 that should be added if the feature is enabled.
2095 </para></listitem>
2096 <listitem><para>Additional runtime dependencies
2097 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
2098 that should be added if the feature is enabled.
2099 </para></listitem>
2100 </orderedlist>
2101 </para>
2102
2103 <para>
2104 Consider the following example taken from the
2105 <filename>librsvg</filename> recipe.
2106 In this example the feature is <filename>croco</filename>, which
2107 has three arguments that determine the feature's behavior.
2108 <literallayout class='monospaced'>
2109 PACKAGECONFIG ??= "croco"
2110 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
2111 </literallayout>
2112 The <filename>--with-croco</filename> and
2113 <filename>libcroco</filename> arguments apply only if
2114 the feature is enabled.
2115 In this case, <filename>--with-croco</filename> is
2116 added to the configure script argument list and
2117 <filename>libcroco</filename> is added to
2118 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
2119 On the other hand, if the feature is disabled say through
2120 a <filename>.bbappend</filename> file in another layer, then
2121 the second argument <filename>--without-croco</filename> is
2122 added to the configure script rather than
2123 <filename>--with-croco</filename>.
2124 </para>
2125 </glossdef>
2126 </glossentry>
2127
2128 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
2129 <glossdef>
2130 <para>The list of packages to be created from the recipe.
2131 The default value is the following:
2132 <literallayout class='monospaced'>
2133 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
2134 </literallayout></para>
2135 </glossdef>
2136 </glossentry>
2137
2138 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
2139 <glossdef>
2140 <para>
2141 A promise that your recipe satisfies runtime dependencies
2142 for optional modules that are found in other recipes.
2143 <filename>PACKAGES_DYNAMIC</filename>
2144 does not actually satisfy the dependencies, it only states that
2145 they should be satisfied.
2146 For example, if a hard, runtime dependency
2147 (<filename>RDEPENDS</filename>) of another package is satisfied
2148 at build time through the <filename>PACKAGES_DYNAMIC</filename>
2149 variable, but a package with the module name is never actually
2150 produced, then the other package will be broken.
2151 Thus, if you attempt to include that package in an image,
2152 you will get a dependency failure from the packaging system
2153 during <filename>do_rootfs</filename>.
2154 Typically, if there is a chance that such a situation can
2155 occur and the package that is not created is valid
2156 without the dependency being satisfied, then you should use
2157 <filename>RRECOMMENDS</filename> (a soft runtime dependency)
2158 instead of <filename>RDEPENDS</filename>.
2159 </para>
2160
2161 <para>
2162 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
2163 variable when you are splitting packages, see the
2164 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
2165 in the Yocto Project Development Manual.
2166 </para>
2167 </glossdef>
2168 </glossentry>
2169
2170 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
2171 <glossdef>
2172 <para>Specifies extra options that are passed to the <filename>make</filename> command during the
2173 compile tasks.
2174 This variable is usually in the form <filename>-j 4</filename>, where the number
2175 represents the maximum number of parallel threads make can run.
2176 If you development host supports multiple cores a good rule of thumb is to set
2177 this variable to twice the number of cores on the host.</para>
2178 </glossdef>
2179 </glossentry>
2180
2181 <glossentry id='var-PF'><glossterm>PF</glossterm>
2182 <glossdef>
2183 <para>Specifies the recipe or package name and includes all version and revision
2184 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
2185 <filename>bash-4.2-r1/</filename>).
2186 This variable is comprised of the following:
2187 <literallayout class='monospaced'>
2188 ${PN}-${EXTENDPE}${PV}-${PR}
2189 </literallayout></para>
2190 </glossdef>
2191 </glossentry>
2192
2193 <glossentry id='var-PN'><glossterm>PN</glossterm>
2194 <glossdef>
2195 <para>This variable can have two separate functions depending on the context: a recipe
2196 name or a resulting package name.</para>
2197 <para><filename>PN</filename> refers to a recipe name in the context of a file used
2198 by the OpenEmbedded build system as input to create a package.
2199 The name is normally extracted from the recipe file name.
2200 For example, if the recipe is named
2201 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
2202 will be "expat".</para>
2203 <para>
2204 The variable refers to a package name in the context of a file created or produced by the
2205 OpenEmbedded build system.</para>
2206 <para>If applicable, the <filename>PN</filename> variable also contains any special
2207 suffix or prefix.
2208 For example, using <filename>bash</filename> to build packages for the native
2209 machine, <filename>PN</filename> is <filename>bash-native</filename>.
2210 Using <filename>bash</filename> to build packages for the target and for Multilib,
2211 <filename>PN</filename> would be <filename>bash</filename> and
2212 <filename>lib64-bash</filename>, respectively.
2213 </para>
2214 </glossdef>
2215 </glossentry>
2216
2217 <glossentry id='var-PR'><glossterm>PR</glossterm>
2218 <glossdef>
2219 <para>The revision of the recipe.
2220 The default value for this variable is "r0".
2221 </para>
2222 </glossdef>
2223 </glossentry>
2224
2225 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
2226 <glossdef>
2227 <para>Causes the <filename>PR</filename> variable of
2228 <filename>.bbappend</filename> files to dynamically increment.
2229 This increment minimizes the impact of layer ordering.</para>
2230 <para>In order to ensure multiple <filename>.bbappend</filename> files can co-exist,
2231 <filename>PRINC</filename> should be self referencing.
2232 This variable defaults to 0.</para>
2233 <para>Following is an example that increments <filename>PR</filename> by two:
2234 <literallayout class='monospaced'>
2235 PRINC := "${@int(PRINC) + 2}"
2236 </literallayout>
2237 It is adviseable not to use strings such as ".= '.1'" with the variable because
2238 this usage is very sensitive to layer ordering.
2239 Explicit assignments should be avoided as they cannot adequately represent multiple
2240 <filename>.bbappend</filename> files.</para>
2241 </glossdef>
2242 </glossentry>
2243
2244 <glossentry id='var-PV'><glossterm>PV</glossterm>
2245 <glossdef>
2246 <para>The version of the recipe.
2247 The version is normally extracted from the recipe filename.
2248 For example, if the recipe is named
2249 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
2250 will be "2.0.1".
2251 <filename>PV</filename> is generally not overridden within
2252 a recipe unless it is building an unstable (i.e. development) version from a source code repository
2253 (e.g. Git or Subversion).
2254 </para>
2255 </glossdef>
2256 </glossentry>
2257
2258 <glossentry id='var-PE'><glossterm>PE</glossterm>
2259 <glossdef>
2260 <para>
2261 the epoch of the recipe.
2262 The default value is "0".
2263 The field is used to make upgrades possible when the versioning scheme changes in
2264 some backwards incompatible way.
2265 </para>
2266 </glossdef>
2267 </glossentry>
2268
2269 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
2270 <glossdef>
2271 <para>
2272 If multiple recipes provide an item, this variable
2273 determines which recipe should be given preference.
2274 The variable must always be suffixed with the name of the
2275 provided item, and should be set to the
2276 <filename>PN</filename> of the recipe
2277 to which you want to give precedence.
2278 Here is an example:
2279 <literallayout class='monospaced'>
2280 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
2281 </literallayout>
2282 </para>
2283 </glossdef>
2284 </glossentry>
2285
2286 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
2287 <glossdef>
2288 <para>
2289 If there are multiple versions of recipes available, this
2290 variable determines which recipe should be given preference.
2291 The variable must always be suffixed with the <filename>PN</filename>
2292 for which to select, and should be set to the
2293 <filename>PV</filename> to which you want to give precedence.
2294 You can use the "<filename>%</filename>" character as a wildcard
2295 to match any number of characters, which can be useful when
2296 specifying versions that contain long revision number that could
2297 potentially change.
2298 Here are two examples:
2299 <literallayout class='monospaced'>
2300 PREFERRED_VERSION_python = "2.6.6"
2301 PREFERRED_VERSION_linux-yocto = "3.0+git%"
2302 </literallayout>
2303 </para>
2304 </glossdef>
2305 </glossentry>
2306
2307 </glossdiv>
2308
2309<!-- <glossdiv id='var-glossary-q'><title>Q</title>-->
2310<!-- </glossdiv>-->
2311
2312 <glossdiv id='var-glossary-r'><title>R</title>
2313
2314 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
2315 <glossdef>
2316 <para>The list of packages that conflict with a package.
2317 Note that the package will not be installed if the conflicting packages are not
2318 first removed.</para>
2319 <para>
2320 Like all package-controlling variables, you must always use them in
2321 conjunction with a package name override.
2322 Here is an example:
2323 <literallayout class='monospaced'>
2324 RCONFLICTS_${PN} = "another-conflicting-package-name"
2325 </literallayout>
2326 </para>
2327 </glossdef>
2328 </glossentry>
2329
2330 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
2331 <glossdef>
2332 <para>
2333 Lists a package's run-time dependencies (i.e. other packages)
2334 that must be installed for the package to be built.
2335 In other words, in order for the package to be built and
2336 run correctly, it depends on the listed packages.
2337 If a package in this list cannot be found, it is probable
2338 that a dependency error would occur before the build.
2339 </para>
2340
2341 <para>
2342 The names of the variables you list with
2343 <filename>RDEPENDS</filename> must be the names of other
2344 packages as listed in the
2345 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
2346 variable.
2347 You should not list recipe names (<filename>PN</filename>).
2348 </para>
2349
2350 <para>
2351 Because the <filename>RDEPENDS</filename> variable applies
2352 to packages being built, you should
2353 always attach a package name to the variable to specify the
2354 particular run-time package that has the dependency.
2355 For example, suppose you are building a development package
2356 that depends on the <filename>perl</filename> package.
2357 In this case, you would use the following
2358 <filename>RDEPENDS</filename> statement:
2359 <literallayout class='monospaced'>
2360 RDEPENDS_${PN}-dev += "perl"
2361 </literallayout>
2362 In the example, the package name
2363 (<filename>${PN}-dev</filename>) must appear as it would
2364 in the
2365 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
2366 namespace before any renaming of the output package by
2367 classes like <filename>debian.bbclass</filename>.
2368 </para>
2369
2370 <para>
2371 In many cases you do not need to explicitly add dependencies
2372 to <filename>RDEPENDS</filename> since some automatic
2373 handling occurs:
2374 <itemizedlist>
2375 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If
2376 a run-time package contains a shared library
2377 (<filename>.so</filename>), the build
2378 processes the library in order to determine other
2379 libraries to which it is dynamically linked.
2380 The build process adds these libraries to
2381 <filename>RDEPENDS</filename> when creating the run-time
2382 package.</para></listitem>
2383 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
2384 the package ships a <filename>pkg-config</filename>
2385 information file, the build process uses this file
2386 to add items to the <filename>RDEPENDS</filename>
2387 variable to create the run-time packages.
2388 </para></listitem>
2389 </itemizedlist>
2390 </para>
2391 </glossdef>
2392 </glossentry>
2393
2394 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
2395 <glossdef>
2396 <para>
2397 A list of packages that extend the usability of a package being
2398 built.
2399 The package being built does not depend on this list of packages in
2400 order to successfully build, but needs them for the extended usability.
2401 To specify runtime dependencies for packages, see the
2402 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variable.
2403 </para>
2404 <para>
2405 The OpenEmbedded build process automatically installs the list of packages
2406 as part of the built package.
2407 However, you can remove them later if you want.
2408 If, during the build, a package from the list cannot be found, the build
2409 process continues without an error.
2410 </para>
2411 <para>
2412 Because the <filename>RRECOMMENDS</filename> variable applies to packages
2413 being built, you should
2414 always attach an override to the variable to specify the particular package
2415 whose usability is being extended.
2416 For example, suppose you are building a development package that is extended
2417 to support wireless functionality.
2418 In this case, you would use the following:
2419 <literallayout class='monospaced'>
2420 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
2421 </literallayout>
2422 In the example, the package name (<filename>${PN}-dev</filename>) must
2423 appear as it would in the
2424 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any
2425 renaming of the output package by classes like <filename>debian.bbclass</filename>.
2426 </para>
2427 </glossdef>
2428 </glossentry>
2429
2430 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
2431 <glossdef>
2432 <para>The list of packages that are replaced with this package.</para>
2433 </glossdef>
2434 </glossentry>
2435
2436 </glossdiv>
2437
2438 <glossdiv id='var-glossary-s'><title>S</title>
2439
2440 <glossentry id='var-S'><glossterm>S</glossterm>
2441 <glossdef>
2442 <para>
2443 The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
2444 where unpacked package source code resides.
2445 This location is within the working directory
2446 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>), which
2447 is not static.
2448 The unpacked source location depends on the package name
2449 (<filename><link linkend='var-PN'>PN</link></filename>) and
2450 package version (<filename><link linkend='var-PV'>PV</link></filename>) as
2451 follows:
2452 <literallayout class='monospaced'>
2453 ${WORKDIR}/${PN}/${PV}
2454 </literallayout>
2455 As an example, assume a
2456 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level
2457 folder named <filename>poky</filename>
2458 and a default <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
2459 at <filename>poky/build</filename>.
2460 In this case, the working directory the build system uses to build
2461 the <filename>db</filename> package is the following:
2462 <literallayout class='monospaced'>
2463 ~/poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
2464 </literallayout>
2465 </para>
2466 </glossdef>
2467 </glossentry>
2468
2469 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
2470 <glossdef>
2471 <para>Equivalent to
2472 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
2473 However, this variable applies to the SDK generated from an image using
2474 <filename>bitbake -c populate_sdk imagename</filename>).
2475 </para>
2476 </glossdef>
2477 </glossentry>
2478
2479 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
2480 <glossdef>
2481 <para>The section in which packages should be categorized.
2482 Package management utilities can make use of this variable.</para>
2483 </glossdef>
2484 </glossentry>
2485
2486 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
2487 <glossdef>
2488 <para>
2489 The variable takes the value of
2490 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
2491 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
2492 In this case the value of
2493 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
2494 </para>
2495 </glossdef>
2496 </glossentry>
2497
2498
2499 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
2500 <glossdef>
2501 <para>The speed and device for the serial port used to attach the serial console.
2502 This variable is given to the kernel as the "console"
2503 parameter and after booting occurs <filename>getty</filename> is started on that port
2504 so remote login is possible.</para>
2505 </glossdef>
2506 </glossentry>
2507
2508 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
2509 <glossdef>
2510 <para>
2511 Specifies the endian byte order of the target system.
2512 The value should be either "le" for little-endian or "be" for big-endian.
2513 </para>
2514 </glossdef>
2515 </glossentry>
2516
2517 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
2518 <glossdef>
2519 <para>
2520 Specifies the number of bits for the target system CPU.
2521 The value should be either "32" or "64".
2522 </para>
2523 </glossdef>
2524 </glossentry>
2525
2526 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
2527 <glossdef>
2528 <para>
2529 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
2530 OpenEmbedded build system to create variants of recipes or packages.
2531 The list specifies the prefixes to strip off during certain circumstances
2532 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
2533 </para>
2534 </glossdef>
2535 </glossentry>
2536
2537 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
2538 <glossdef>
2539 <para>The list of source files - local or remote.
2540 This variable tells the OpenEmbedded build system which bits to pull
2541 in for the build and how to pull them in.
2542 For example, if the recipe only needs to fetch a tarball from the
2543 internet, the recipe uses a single <filename>SRC_URI</filename> entry.
2544 On the other hand, if the recipe needs to fetch a tarball, apply
2545 two patches, and include a custom file, the recipe would include four
2546 instances of the variable.</para>
2547 <para>The following list explains the available URI protocols:
2548 <itemizedlist>
2549 <listitem><para><emphasis><filename>file://</filename> -</emphasis> Fetches files, which is usually
2550 a file shipped with the metadata, from the local machine.
2551 The path is relative to the
2552 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
2553 variable.
2554 Thus, the build system searches, in order, from the following directories,
2555 which are assumed to be a subdirectories of the directory in which the
2556 recipe file resides:
2557 <itemizedlist>
2558 <listitem><para><emphasis><filename>${PN}</filename> -</emphasis> The recipe name
2559 with any special suffix or prefix, if applicable.
2560 For example, using <filename>bash</filename> to build for the native
2561 machine, <filename>PN</filename> is <filename>bash-native</filename>.
2562 Using <filename>bash</filename> to build for the target and for Multilib,
2563 <filename>PN</filename> would be <filename>bash</filename> and
2564 <filename>lib64-bash</filename>, respectively.
2565 </para></listitem>
2566 <listitem><para><emphasis><filename>${PF}</filename> - </emphasis>
2567 <filename>${PN}-${EXTENDPE}${PV}-${PR}</filename>.
2568 The recipe name including all version and revision numbers
2569 (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
2570 <filename>bash-4.2-r1/</filename>).</para></listitem>
2571 <listitem><para><emphasis><filename>${P}</filename> -</emphasis>
2572 <filename>${PN}-${PV}</filename>.
2573 The recipe name and version (i.e. <filename>bash-4.2</filename>).
2574 </para></listitem>
2575 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis> The
2576 base recipe name without any special suffix or version numbers.
2577 </para></listitem>
2578 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
2579 <filename>${BPN}-${PV}</filename>.
2580 The base recipe name and version but without any special
2581 package name suffix.</para></listitem>
2582 <listitem><para><emphasis>Files -</emphasis> Files beneath the directory in which the recipe
2583 resides.</para></listitem>
2584 <listitem><para><emphasis>Directory -</emphasis> The directory itself in which the recipe
2585 resides.</para></listitem>
2586 </itemizedlist></para></listitem>
2587 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
2588 Bazaar revision control repository.</para></listitem>
2589 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
2590 Git revision control repository.</para></listitem>
2591 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
2592 an OSC (OpenSuse Build service) revision control repository.</para></listitem>
2593 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
2594 a repo (Git) repository.</para></listitem>
2595 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
2596 an SVK revision control repository.</para></listitem>
2597 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
2598 the Internet using <filename>http</filename>.</para></listitem>
2599 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
2600 from the Internet using <filename>https</filename>.</para></listitem>
2601 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
2602 from the Internet using <filename>ftp</filename>.</para></listitem>
2603 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
2604 a CVS revision control repository.</para></listitem>
2605 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
2606 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
2607 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
2608 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
2609 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
2610 a secure shell.</para></listitem>
2611 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
2612 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
2613 </itemizedlist>
2614 </para>
2615 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
2616 Here are standard options:
2617 <itemizedlist>
2618 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
2619 the patch or not.
2620 The default action is to apply the patch.</para></listitem>
2621 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
2622 striplevel to use when applying the patch.
2623 The default level is 1.</para></listitem>
2624 </itemizedlist>
2625 </para>
2626 <para>Here are options specific to recipes building code from a revision control system:
2627 <itemizedlist>
2628 <listitem><para><emphasis><filename>mindate</filename> -</emphasis> Only applies
2629 the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
2630 is equal to or greater than <filename>mindate</filename>.</para></listitem>
2631 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis> Only applies
2632 the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
2633 is not later than <filename>mindate</filename>.</para></listitem>
2634 <listitem><para><emphasis><filename>minrev</filename> -</emphasis> Only applies
2635 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2636 is equal to or greater than <filename>minrev</filename>.</para></listitem>
2637 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis> Only applies
2638 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2639 is not later than <filename>maxrev</filename>.</para></listitem>
2640 <listitem><para><emphasis><filename>rev</filename> -</emphasis> Only applies the
2641 patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2642 is equal to <filename>rev</filename>.</para></listitem>
2643 <listitem><para><emphasis><filename>notrev</filename> -</emphasis> Only applies
2644 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2645 is not equal to <filename>rev</filename>.</para></listitem>
2646 </itemizedlist>
2647 </para>
2648 <para>Here are some additional options worth mentioning:
2649 <itemizedlist>
2650 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
2651 whether or not to unpack the file if it is an archive.
2652 The default action is to upack the file.</para></listitem>
2653 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
2654 (or extracts its contents) into the specified
2655 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
2656 This option is useful for unusual tarballs or other archives that
2657 don't have their files already in a subdirectory within the archive.
2658 </para></listitem>
2659 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
2660 name to be used for association with <filename>SRC_URI</filename> checksums
2661 when you have more than one file specified in <filename>SRC_URI</filename>.
2662 </para></listitem>
2663 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
2664 the filename used when storing the downloaded file.</para></listitem>
2665 </itemizedlist>
2666 </para>
2667 </glossdef>
2668 </glossentry>
2669
2670 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
2671 <glossdef>
2672 <para></para>
2673 <para>
2674 By default, the OpenEmbedded build system automatically detects whether
2675 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
2676 contains files that are machine-specific.
2677 If so, the build system automatically changes
2678 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
2679 Setting this variable to "0" disables this behavior.
2680 </para>
2681 </glossdef>
2682 </glossentry>
2683
2684 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
2685 <glossdef>
2686 <para>
2687 The date of the source code used to build the package.
2688 This variable applies only if the source was fetched from a Source Code Manager (SCM).
2689 </para>
2690 </glossdef>
2691 </glossentry>
2692
2693 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
2694 <glossdef>
2695 <para>
2696 The revision of the source code used to build the package.
2697 This variable applies to Subversion, Git, Mercurial and Bazaar
2698 only.
2699 Note that if you wish to build a fixed revision and you wish
2700 to avoid performing a query on the remote repository every time
2701 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
2702 full revision identifier and not just a tag.
2703 </para>
2704 </glossdef>
2705 </glossentry>
2706
2707 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
2708 <glossdef>
2709 <para>The directory for the shared state.</para>
2710 </glossdef>
2711 </glossentry>
2712
2713 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
2714 <glossdef>
2715 <para>
2716 Configures the OpenEmbedded build system to search other
2717 mirror locations for prebuilt cache data objects before
2718 building out the data.
2719 This variable works like fetcher
2720 <filename>MIRRORS</filename>/<filename>PREMIRRORS</filename>
2721 and points to the cache locations to check for the shared
2722 objects.
2723 </para>
2724
2725 <para>
2726 You can specify a filesystem directory or a remote URL such
2727 as HTTP or FTP.
2728 The locations you specify need to contain the shared state
2729 cache (sstate-cache) results from previous builds.
2730 The sstate-cache you point to can also be from builds on
2731 other machines.
2732 </para>
2733
2734 <para>
2735 If a mirror uses the same structure as
2736 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
2737 you need to add
2738 "PATH" at the end as shown in the examples below.
2739 The build system substitues the correct path within the
2740 directory structure.
2741 <literallayout class='monospaced'>
2742 SSTATE_MIRRORS ?= "\
2743 file://.* http://someserver.tld/share/sstate/PATH \n \
2744 file://.* file:///some/local/dir/sstate/PATH"
2745 </literallayout>
2746 </para>
2747 </glossdef>
2748 </glossentry>
2749
2750 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
2751 <glossdef>
2752 <para>
2753 The directory with kernel headers that are required to build out-of-tree
2754 modules.
2755 </para>
2756 </glossdef>
2757 </glossentry>
2758
2759 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
2760 <glossdef>
2761 <para>
2762 Specifies the base path used to create recipe stamp files.
2763 The path to an actual stamp file is constructed by evaluating this
2764 string and then appending additional information.
2765 Currently, the default assignment for <filename>STAMP</filename>
2766 as set in the <filename>meta/conf/bitbake.conf</filename> file
2767 is:
2768 <literallayout class='monospaced'>
2769 STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
2770 </literallayout>
2771 See <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
2772 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
2773 <link linkend='var-PN'><filename>PN</filename></link>,
2774 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
2775 <link linkend='var-PV'><filename>PV</filename></link>, and
2776 <link linkend='var-PR'><filename>PR</filename></link> for related variable
2777 information.
2778 </para>
2779 </glossdef>
2780 </glossentry>
2781
2782 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
2783 <glossdef>
2784 <para>The short (72 characters or less) summary of the binary package for packaging
2785 systems such as <filename>opkg</filename>, <filename>rpm</filename> or
2786 <filename>dpkg</filename>.
2787 By default, <filename>SUMMARY</filename> is used to define
2788 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
2789 variable if <filename>DESCRIPTION</filename> is not set
2790 in the recipe.
2791 </para>
2792 </glossdef>
2793 </glossentry>
2794
2795 </glossdiv>
2796
2797 <glossdiv id='var-glossary-t'><title>T</title>
2798
2799 <glossentry id='var-T'><glossterm>T</glossterm>
2800 <glossdef>
2801 <para>This variable points to a directory were Bitbake places temporary
2802 files when building a particular package.
2803 It is typically set as follows:
2804 <literallayout class='monospaced'>
2805 T = ${WORKDIR}/temp
2806 </literallayout>
2807 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
2808 is the directory into which Bitbake unpacks and builds the package.
2809 The default <filename>bitbake.conf</filename> file sets this variable.</para>
2810 <para>The <filename>T</filename> variable is not to be confused with
2811 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
2812 which points to the root of the directory tree where Bitbake
2813 places the output of an entire build.
2814 </para>
2815 </glossdef>
2816 </glossentry>
2817
2818 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
2819 <glossdef>
2820 <para>The architecture of the device being built.
2821 While a number of values are possible, the OpenEmbedded build system primarily supports
2822 <filename>arm</filename> and <filename>i586</filename>.</para>
2823 </glossdef>
2824 </glossentry>
2825
2826 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
2827 <glossdef>
2828 <para>
2829 Flags passed to the C compiler for the target system.
2830 This variable evaluates to the same as
2831 <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>.
2832 </para>
2833 </glossdef>
2834 </glossentry>
2835
2836
2837 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
2838 <glossdef>
2839 <para>Specifies the method for handling FPU code.
2840 For FPU-less targets, which include most ARM CPUs, the variable must be
2841 set to "soft".
2842 If not, the kernel emulation gets used, which results in a performance penalty.</para>
2843 </glossdef>
2844 </glossentry>
2845
2846 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
2847 <glossdef>
2848 <para>Specifies the target's operating system.
2849 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
2850 to "linux-uclibc" for <filename>uclibc</filename>.
2851 For ARM/EABI targets, there are also "linux-gnueabi" and
2852 "linux-uclibc-gnueabi" values possible.</para>
2853 </glossdef>
2854 </glossentry>
2855
2856 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
2857 <glossdef>
2858 <para>
2859 Specifies which variant of the GNU standard C library (<filename>libc</filename>)
2860 to use during the build process.
2861 This variable replaces <filename>POKYLIBC</filename>, which is no longer
2862 supported.
2863 </para>
2864 <para>
2865 You can select <filename>eglibc</filename> or <filename>uclibc</filename>.
2866 <note>
2867 This release of the Yocto Project does not support the
2868 <filename>glibc</filename> implementation of <filename>libc</filename>.
2869 </note>
2870 </para>
2871 </glossdef>
2872 </glossentry>
2873
2874 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
2875 <glossdef>
2876 <para>
2877 The toolchain selector.
2878 This variable replaces <filename>POKYMODE</filename>, which is no longer
2879 supported.
2880 </para>
2881 <para>
2882 The <filename>TCMODE</filename> variable selects the external toolchain
2883 built using the OpenEmbedded build system or a few supported combinations of
2884 the upstream GCC or CodeSourcery Labs toolchain.
2885 The variable identifies the <filename>tcmode-*</filename> files used in
2886 the <filename>meta/conf/distro/include</filename> directory, which is found in the
2887 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2888 </para>
2889 <para>
2890 By default, <filename>TCMODE</filename> is set to "default", which
2891 chooses the <filename>tcmode-default.inc</filename> file.
2892 The variable is similar to
2893 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls
2894 the variant of the GNU standard C library (<filename>libc</filename>)
2895 used during the build process: <filename>eglibc</filename> or <filename>uclibc</filename>.
2896 </para>
2897 </glossdef>
2898 </glossentry>
2899
2900 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
2901 <glossdef>
2902 <para>
2903 This variable is the temporary directory the OpenEmbedded build system
2904 uses when it does its work building images.
2905 By default, the <filename>TMPDIR</filename> variable is named
2906 <filename>tmp</filename> within the
2907 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2908 </para>
2909
2910 <para>
2911 If you want to establish this directory in a location other than the
2912 default, you can uncomment the following statement in the
2913 <filename>conf/local.conf</filename> file in the
2914 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
2915 <literallayout class='monospaced'>
2916 #TMPDIR = "${TOPDIR}/tmp"
2917 </literallayout>
2918 </para>
2919 </glossdef>
2920 </glossentry>
2921
2922 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
2923 <glossdef>
2924 <para>
2925 This variable is the
2926 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2927 BitBake automatically sets this variable.
2928 The OpenEmbedded build system uses the Build Directory when building images.
2929 </para>
2930 </glossdef>
2931 </glossentry>
2932
2933 </glossdiv>
2934
2935<!-- <glossdiv id='var-glossary-u'><title>U</title>-->
2936<!-- </glossdiv>-->
2937
2938<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
2939<!-- </glossdiv>-->
2940
2941 <glossdiv id='var-glossary-w'><title>W</title>
2942
2943 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
2944 <glossdef>
2945 <para>
2946 The pathname of the working directory in which the OpenEmbedded build system
2947 builds a recipe.
2948 This directory is located within the
2949 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes
2950 as different packages are built.
2951 </para>
2952
2953 <para>
2954 The actual <filename>WORKDIR</filename> directory depends on several things:
2955 <itemizedlist>
2956 <listitem>The temporary directory - <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link></listitem>
2957 <listitem>The package architecture - <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link></listitem>
2958 <listitem>The target machine - <link linkend='var-MACHINE'><filename>MACHINE</filename></link></listitem>
2959 <listitem>The target operating system - <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link></listitem>
2960 <listitem>The recipe name - <link linkend='var-PN'><filename>PN</filename></link></listitem>
2961 <listitem>The recipe version - <link linkend='var-PV'><filename>PV</filename></link></listitem>
2962 <listitem>The recipe revision - <link linkend='var-PR'><filename>PR</filename></link></listitem>
2963 </itemizedlist>
2964 </para>
2965
2966 <para>
2967 For packages that are not dependent on a particular machine,
2968 <filename>WORKDIR</filename> is defined as follows:
2969 <literallayout class='monospaced'>
2970 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
2971 </literallayout>
2972 As an example, assume a
2973 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level
2974 folder name <filename>poky</filename> and a default
2975 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
2976 at <filename>poky/build</filename>.
2977 In this case, the working directory the build system uses to build
2978 the <filename>v86d</filename> package is the following:
2979 <literallayout class='monospaced'>
2980 ~/poky/build/tmp/work/qemux86-poky-linux/v86d/01.9-r0
2981 </literallayout>
2982 </para>
2983
2984 <para>
2985 For packages that are dependent on a particular machine, <filename>WORKDIR</filename>
2986 is defined slightly different:
2987 <literallayout class='monospaced'>
2988 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
2989 </literallayout>
2990 As an example, again assume a Source Directory top-level folder
2991 named <filename>poky</filename> and a default Build Directory
2992 at <filename>poky/build</filename>.
2993 In this case, the working directory the build system uses to build
2994 the <filename>acl</filename> recipe, which is being built for a
2995 MIPS-based device, is the following:
2996 <literallayout class='monospaced'>
2997 ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2
2998 </literallayout>
2999 </para>
3000 </glossdef>
3001 </glossentry>
3002
3003 </glossdiv>
3004
3005<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
3006<!-- </glossdiv>-->
3007
3008<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
3009<!-- </glossdiv>-->
3010
3011<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
3012<!-- </glossdiv>-->
3013
3014</glossary>
3015</chapter>
3016<!--
3017vim: expandtab tw=80 ts=4
3018-->
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-varlocality'>
6 <title>Variable Context</title>
7
8 <para>
9 While most variables can be used in almost any context such as
10 <filename>.conf</filename>, <filename>.bbclass</filename>,
11 <filename>.inc</filename>, and <filename>.bb</filename> files,
12 some variables are often associated with a particular locality or context.
13 This chapter describes some common associations.
14 </para>
15
16 <section id='ref-varlocality-configuration'>
17 <title>Configuration</title>
18
19 <para>
20 The following subsections provide lists of variables whose context is
21 configuration: distribution, machine, and local.
22 </para>
23
24 <section id='ref-varlocality-config-distro'>
25 <title>Distribution (Distro)</title>
26
27 <para>
28 This section lists variables whose context is the distribution, or distro.
29 <itemizedlist>
30 <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename></para></listitem>
31 <listitem><para><filename><link linkend='var-DISTRO_NAME'>DISTRO_NAME</link></filename>
32 </para></listitem>
33 <listitem><para><filename><link linkend='var-DISTRO_VERSION'>DISTRO_VERSION</link>
34 </filename></para></listitem>
35 <listitem><para><filename><link linkend='var-MAINTAINER'>MAINTAINER</link></filename>
36 </para></listitem>
37 <listitem><para><filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link>
38 </filename></para></listitem>
39 <listitem><para><filename><link linkend='var-TARGET_OS'>TARGET_OS</link></filename>
40 </para></listitem>
41 <listitem><para><filename><link linkend='var-TARGET_FPU'>TARGET_FPU</link></filename>
42 </para></listitem>
43 <listitem><para><filename><link linkend='var-TCMODE'>TCMODE</link></filename>
44 </para></listitem>
45 <listitem><para><filename><link linkend='var-TCLIBC'>TCLIBC</link></filename>
46 </para></listitem>
47 </itemizedlist>
48 </para>
49 </section>
50
51 <section id='ref-varlocality-config-machine'>
52 <title>Machine</title>
53
54 <para>
55 This section lists variables whose context is the machine.
56 <itemizedlist>
57 <listitem><para><filename><link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></filename>
58 </para></listitem>
59 <listitem><para><filename><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE</link>
60 </filename></para></listitem>
61 <listitem><para><filename><link linkend='var-PACKAGE_EXTRA_ARCHS'>PACKAGE_EXTRA_ARCHS</link>
62 </filename></para></listitem>
63 <listitem><para><filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link>
64 </filename></para></listitem>
65 <listitem><para><filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link>
66 </filename></para></listitem>
67 <listitem><para><filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS
68 </link></filename></para></listitem>
69 <listitem><para><filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS
70 </link></filename></para></listitem>
71 <listitem><para><filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS
72 </link></filename></para></listitem>
73 <listitem><para><filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>
74 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename></para></listitem>
75 </itemizedlist>
76 </para>
77 </section>
78
79 <section id='ref-varlocality-config-local'>
80 <title>Local</title>
81
82 <para>
83 This section lists variables whose context is the local configuration through the
84 <filename>local.conf</filename> file.
85 <itemizedlist>
86 <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename>
87 </para></listitem>
88 <listitem><para><filename><link linkend='var-MACHINE'>MACHINE</link></filename>
89 </para></listitem>
90 <listitem><para><filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>
91 </para></listitem>
92 <listitem><para><filename><link linkend='var-BBFILES'>BBFILES</link></filename>
93 </para></listitem>
94 <listitem><para><filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES
95 </link></filename></para></listitem>
96 <listitem><para><filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link>
97 </filename></para></listitem>
98 <listitem><para><filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link>
99 </filename></para></listitem>
100 <listitem><para><filename><link linkend='var-BBINCLUDELOGS'>BBINCLUDELOGS</link>
101 </filename></para></listitem>
102 <listitem><para><filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>
103 ENABLE_BINARY_LOCALE_GENERATION</link></filename></para></listitem>
104 </itemizedlist>
105 </para>
106 </section>
107 </section>
108
109 <section id='ref-varlocality-recipes'>
110 <title>Recipes</title>
111
112 <para>
113 The following subsections provide lists of variables whose context is
114 recipes: required, dependencies, path, and extra build information.
115 </para>
116
117 <section id='ref-varlocality-recipe-required'>
118 <title>Required</title>
119
120 <para>
121 This section lists variables that are required for recipes.
122 <itemizedlist>
123 <listitem><para><filename><link linkend='var-LICENSE'>LICENSE</link>
124 </filename></para></listitem>
125 <listitem><para><filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
126 </filename></para></listitem>
127 <listitem><para><filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> - used
128 in recipes that fetch local or remote files.
129 </para></listitem>
130 </itemizedlist>
131 </para>
132 </section>
133
134 <section id='ref-varlocality-recipe-dependencies'>
135 <title>Dependencies</title>
136
137 <para>
138 This section lists variables that define recipe dependencies.
139 <itemizedlist>
140 <listitem><para><filename><link linkend='var-DEPENDS'>DEPENDS</link>
141 </filename></para></listitem>
142 <listitem><para><filename><link linkend='var-RDEPENDS'>RDEPENDS</link>
143 </filename></para></listitem>
144 <listitem><para><filename><link linkend='var-RRECOMMENDS'>RRECOMMENDS</link>
145 </filename></para></listitem>
146 <listitem><para><filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link>
147 </filename></para></listitem>
148 <listitem><para><filename><link linkend='var-RREPLACES'>RREPLACES</link>
149 </filename></para></listitem>
150 </itemizedlist>
151 </para>
152 </section>
153
154 <section id='ref-varlocality-recipe-paths'>
155 <title>Paths</title>
156
157 <para>
158 This section lists variables that define recipe paths.
159 <itemizedlist>
160 <listitem><para><filename><link linkend='var-WORKDIR'>WORKDIR</link>
161 </filename></para></listitem>
162 <listitem><para><filename><link linkend='var-S'>S</link>
163 </filename></para></listitem>
164 <listitem><para><filename><link linkend='var-FILES'>FILES</link>
165 </filename></para></listitem>
166 </itemizedlist>
167 </para>
168 </section>
169
170 <section id='ref-varlocality-recipe-build'>
171 <title>Extra Build Information</title>
172
173 <para>
174 This section lists variables that define extra build information for recipes.
175 <itemizedlist>
176 <listitem><para><filename><link linkend='var-EXTRA_OECMAKE'>EXTRA_OECMAKE</link>
177 </filename></para></listitem>
178 <listitem><para><filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link>
179 </filename></para></listitem>
180 <listitem><para><filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link>
181 </filename></para></listitem>
182 <listitem><para><filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
183 </para></listitem>
184 <listitem><para><filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE
185 </link></filename></para></listitem>
186 </itemizedlist>
187 </para>
188 </section>
189 </section>
190</chapter>
191<!--
192vim: expandtab tw=80 ts=4 spell spelllang=en_gb
193-->
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='resources'>
6<title>Contributing to the Yocto Project</title>
7
8<section id='resources-intro'>
9 <title>Introduction</title>
10 <para>
11 The Yocto Project team is happy for people to experiment with the Yocto Project.
12 A number of places exist to find help if you run into difficulties or find bugs.
13 To find out how to download source code,
14 see the "<ulink url='&YOCTO_DOCS_DEV_URL;#local-yp-release'>Yocto Project Release</ulink>"
15 list item in the Yocto Project Development Manual.
16 </para>
17</section>
18
19<section id='resources-bugtracker'>
20 <title>Tracking Bugs</title>
21
22 <para>
23 If you find problems with the Yocto Project, you should report them using the
24 Bugzilla application at <ulink url='&YOCTO_BUGZILLA_URL;'></ulink>.
25 </para>
26</section>
27
28<section id='resources-mailinglist'>
29 <title>Mailing lists</title>
30
31 <para>
32 There are a number of mailing lists maintained by the Yocto Project as well as
33 related OpenEmbedded mailing lists for discussion, patch submission and announcements.
34 To subscribe to one of the following mailing lists, click on the appropriate URL
35 in the following list and follow the instructions:
36 <itemizedlist>
37 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> -
38 General Yocto Project discussion mailing list. </para></listitem>
39 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'></ulink> -
40 Discussion mailing list about OpenEmbedded-Core (the core metadata).</para></listitem>
41 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'></ulink> -
42 Discussion mailing list about OpenEmbedded.</para></listitem>
43 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'></ulink> -
44 Discussion mailing list about the BitBake build tool.</para></listitem>
45 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> -
46 Discussion mailing list about Poky.</para></listitem>
47 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink> -
48 Mailing list to receive official Yocto Project release and milestone
49 announcements.</para></listitem>
50 </itemizedlist>
51 </para>
52</section>
53
54<section id='resources-irc'>
55 <title>Internet Relay Chat (IRC)</title>
56
57 <para>
58 Two IRC channels on freenode are available for the Yocto Project and Poky discussions:
59 <itemizedlist>
60 <listitem><para><filename>#yocto</filename></para></listitem>
61 <listitem><para><filename>#poky</filename></para></listitem>
62 </itemizedlist>
63 </para>
64</section>
65
66<section id='resources-links'>
67 <title>Links</title>
68
69 <para>
70 Following is a list of resources you will find helpful:
71 <itemizedlist>
72 <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;'>The Yocto Project website</ulink>:
73 </emphasis> The home site for the Yocto Project.</para></listitem>
74<!-- <listitem><para><emphasis><ulink url='&OH_HOME_URL;'>OpenedHand</ulink>:</emphasis>
75 The company where the Yocto Project build system Poky was first developed.
76 OpenedHand has since been acquired by Intel Corporation.</para></listitem> -->
77 <listitem><para><emphasis><ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis>
78 The company who acquired OpenedHand in 2008 and began development on the
79 Yocto Project.</para></listitem>
80 <listitem><para><emphasis><ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis>
81 The upstream, generic, embedded distribution used as the basis for the build system in the
82 Yocto Project.
83 Poky derives from and contributes back to the OpenEmbedded project.</para></listitem>
84 <listitem><para><emphasis><ulink url='http://developer.berlios.de/projects/bitbake/'>
85 BitBake</ulink>:</emphasis> The tool used to process metadata.</para></listitem>
86 <listitem><para><emphasis>BitBake User Manual:</emphasis>
87 A comprehensive guide to the BitBake tool.
88 You can find the BitBake User Manual in the <filename>bitbake/doc/manual</filename>
89 directory, which is found in the
90 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
91 </para></listitem>
92 <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Index.html'>QEMU</ulink>:
93 </emphasis> An open source machine emulator and virtualizer.</para></listitem>
94 </itemizedlist>
95 </para>
96</section>
97
98<section id='resources-contributions'>
99 <title>Contributions</title>
100
101 <para>
102 The Yocto Project gladly accepts contributions.
103 You can submit changes to the project either by creating and sending pull requests,
104 or by submitting patches through email.
105 For information on how to do both, see the
106 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
107 section in the Yocto Project Development Manual.
108 </para>
109</section>
110
111</chapter>
112<!--
113vim: expandtab tw=80 ts=4
114-->
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='technical-details'>
6<title>Technical Details</title>
7
8 <para>
9 This chapter provides technical details for various parts of the Yocto Project.
10 Currently, topics include Yocto Project components and shared state (sstate) cache.
11 </para>
12
13<section id='usingpoky-components'>
14 <title>Yocto Project Components</title>
15
16 <para>
17 The BitBake task executor together with various types of configuration files form the
18 OpenEmbedded Core.
19 This section overviews the BitBake task executor and the
20 configuration files by describing what they are used for and how they interact.
21 </para>
22
23 <para>
24 BitBake handles the parsing and execution of the data files.
25 The data itself is of various types:
26 <itemizedlist>
27 <listitem><para><emphasis>Recipes:</emphasis> Provides details about particular
28 pieces of software</para></listitem>
29 <listitem><para><emphasis>Class Data:</emphasis> An abstraction of common build
30 information (e.g. how to build a Linux kernel).</para></listitem>
31 <listitem><para><emphasis>Configuration Data:</emphasis> Defines machine-specific settings,
32 policy decisions, etc.
33 Configuration data acts as the glue to bind everything together.</para></listitem>
34 </itemizedlist>
35 For more information on data, see the
36 "<ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-terms'>Yocto Project Terms</ulink>"
37 section in the Yocto Project Development Manual.
38 </para>
39
40 <para>
41 BitBake knows how to combine multiple data sources together and refers to each data source
42 as a layer.
43 For information on layers, see the
44 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
45 Creating Layers</ulink>" section of the Yocto Project Development Manual.
46 </para>
47
48 <para>
49 Following are some brief details on these core components.
50 For more detailed information on these components see the
51 "<link linkend='ref-structure'>Directory Structure</link>" chapter.
52 </para>
53
54 <section id='usingpoky-components-bitbake'>
55 <title>BitBake</title>
56
57 <para>
58 BitBake is the tool at the heart of the OpenEmbedded build system and is responsible
59 for parsing the metadata, generating a list of tasks from it,
60 and then executing those tasks.
61 To see a list of the options BitBake supports, use the following help command:
62 <literallayout class='monospaced'>
63 $ bitbake --help
64 </literallayout>
65 </para>
66
67 <para>
68 The most common usage for BitBake is <filename>bitbake &lt;packagename&gt;</filename>, where
69 <filename>packagename</filename> is the name of the package you want to build
70 (referred to as the "target" in this manual).
71 The target often equates to the first part of a <filename>.bb</filename> filename.
72 So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
73 might type the following:
74 <literallayout class='monospaced'>
75 $ bitbake matchbox-desktop
76 </literallayout>
77 Several different versions of <filename>matchbox-desktop</filename> might exist.
78 BitBake chooses the one selected by the distribution configuration.
79 You can get more details about how BitBake chooses between different
80 target versions and providers in the
81 "<link linkend='ref-bitbake-providers'>Preferences and Providers</link>" section.
82 </para>
83
84 <para>
85 BitBake also tries to execute any dependent tasks first.
86 So for example, before building <filename>matchbox-desktop</filename>, BitBake
87 would build a cross compiler and <filename>eglibc</filename> if they had not already
88 been built.
89 <note>This release of the Yocto Project does not support the <filename>glibc</filename>
90 GNU version of the Unix standard C library. By default, the OpenEmbedded build system
91 builds with <filename>eglibc</filename>.</note>
92 </para>
93
94 <para>
95 A useful BitBake option to consider is the <filename>-k</filename> or
96 <filename>--continue</filename> option.
97 This option instructs BitBake to try and continue processing the job as much
98 as possible even after encountering an error.
99 When an error occurs, the target that
100 failed and those that depend on it cannot be remade.
101 However, when you use this option other dependencies can still be processed.
102 </para>
103 </section>
104
105 <section id='usingpoky-components-metadata'>
106 <title>Metadata (Recipes)</title>
107
108 <para>
109 The <filename>.bb</filename> files are usually referred to as "recipes."
110 In general, a recipe contains information about a single piece of software.
111 The information includes the location from which to download the source patches
112 (if any are needed), which special configuration options to apply,
113 how to compile the source files, and how to package the compiled output.
114 </para>
115
116 <para>
117 The term "package" can also be used to describe recipes.
118 However, since the same word is used for the packaged output from the OpenEmbedded
119 build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files),
120 this document avoids using the term "package" when referring to recipes.
121 </para>
122 </section>
123
124 <section id='usingpoky-components-classes'>
125 <title>Classes</title>
126
127 <para>
128 Class files (<filename>.bbclass</filename>) contain information that is useful to share
129 between metadata files.
130 An example is the Autotools class, which contains
131 common settings for any application that Autotools uses.
132 The "<link linkend='ref-classes'>Classes</link>" chapter provides details
133 about common classes and how to use them.
134 </para>
135 </section>
136
137 <section id='usingpoky-components-configuration'>
138 <title>Configuration</title>
139
140 <para>
141 The configuration files (<filename>.conf</filename>) define various configuration variables
142 that govern the OpenEmbedded build process.
143 These files fall into several areas that define machine configuration options,
144 distribution configuration options, compiler tuning options, general common configuration
145 options and user configuration options (<filename>local.conf</filename>, which is found
146 in the <ulink url='build-directory'>Build Directory</ulink>).
147 </para>
148 </section>
149</section>
150
151<section id="shared-state-cache">
152 <title>Shared State Cache</title>
153
154 <para>
155 By design, the OpenEmbedded build system builds everything from scratch unless
156 BitBake can determine that parts don't need to be rebuilt.
157 Fundamentally, building from scratch is attractive as it means all parts are
158 built fresh and there is no possibility of stale data causing problems.
159 When developers hit problems, they typically default back to building from scratch
160 so they know the state of things from the start.
161 </para>
162
163 <para>
164 Building an image from scratch is both an advantage and a disadvantage to the process.
165 As mentioned in the previous paragraph, building from scratch ensures that
166 everything is current and starts from a known state.
167 However, building from scratch also takes much longer as it generally means
168 rebuilding things that don't necessarily need rebuilt.
169 </para>
170
171 <para>
172 The Yocto Project implements shared state code that supports incremental builds.
173 The implementation of the shared state code answers the following questions that
174 were fundamental roadblocks within the OpenEmbedded incremental build support system:
175 <itemizedlist>
176 <listitem>What pieces of the system have changed and what pieces have not changed?</listitem>
177 <listitem>How are changed pieces of software removed and replaced?</listitem>
178 <listitem>How are pre-built components that don't need to be rebuilt from scratch
179 used when they are available?</listitem>
180 </itemizedlist>
181 </para>
182
183 <para>
184 For the first question, the build system detects changes in the "inputs" to a given task by
185 creating a checksum (or signature) of the task's inputs.
186 If the checksum changes, the system assumes the inputs have changed and the task needs to be
187 rerun.
188 For the second question, the shared state (sstate) code tracks which tasks add which output
189 to the build process.
190 This means the output from a given task can be removed, upgraded or otherwise manipulated.
191 The third question is partly addressed by the solution for the second question
192 assuming the build system can fetch the sstate objects from remote locations and
193 install them if they are deemed to be valid.
194 </para>
195
196 <para>
197 The rest of this section goes into detail about the overall incremental build
198 architecture, the checksums (signatures), shared state, and some tips and tricks.
199 </para>
200
201 <section id='overall-architecture'>
202 <title>Overall Architecture</title>
203
204 <para>
205 When determining what parts of the system need to be built, BitBake
206 uses a per-task basis and does not use a per-recipe basis.
207 You might wonder why using a per-task basis is preferred over a per-recipe basis.
208 To help explain, consider having the IPK packaging backend enabled and then switching to DEB.
209 In this case, <filename>do_install</filename> and <filename>do_package</filename>
210 output are still valid.
211 However, with a per-recipe approach, the build would not include the
212 <filename>.deb</filename> files.
213 Consequently, you would have to invalidate the whole build and rerun it.
214 Rerunning everything is not the best situation.
215 Also in this case, the core must be "taught" much about specific tasks.
216 This methodology does not scale well and does not allow users to easily add new tasks
217 in layers or as external recipes without touching the packaged-staging core.
218 </para>
219 </section>
220
221 <section id='checksums'>
222 <title>Checksums (Signatures)</title>
223
224 <para>
225 The shared state code uses a checksum, which is a unique signature of a task's
226 inputs, to determine if a task needs to be run again.
227 Because it is a change in a task's inputs that triggers a rerun, the process
228 needs to detect all the inputs to a given task.
229 For shell tasks, this turns out to be fairly easy because
230 the build process generates a "run" shell script for each task and
231 it is possible to create a checksum that gives you a good idea of when
232 the task's data changes.
233 </para>
234
235 <para>
236 To complicate the problem, there are things that should not be included in
237 the checksum.
238 First, there is the actual specific build path of a given task -
239 the <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
240 It does not matter if the working directory changes because it should not
241 affect the output for target packages.
242 Also, the build process has the objective of making native/cross packages relocatable.
243 The checksum therefore needs to exclude <filename>WORKDIR</filename>.
244 The simplistic approach for excluding the working directory is to set
245 <filename>WORKDIR</filename> to some fixed value and create the checksum
246 for the "run" script.
247 </para>
248
249 <para>
250 Another problem results from the "run" scripts containing functions that
251 might or might not get called.
252 The incremental build solution contains code that figures out dependencies
253 between shell functions.
254 This code is used to prune the "run" scripts down to the minimum set,
255 thereby alleviating this problem and making the "run" scripts much more
256 readable as a bonus.
257 </para>
258
259 <para>
260 So far we have solutions for shell scripts.
261 What about python tasks?
262 The same approach applies even though these tasks are more difficult.
263 The process needs to figure out what variables a python function accesses
264 and what functions it calls.
265 Again, the incremental build solution contains code that first figures out
266 the variable and function dependencies, and then creates a checksum for the data
267 used as the input to the task.
268 </para>
269
270 <para>
271 Like the <filename>WORKDIR</filename> case, situations exist where dependencies
272 should be ignored.
273 For these cases, you can instruct the build process to ignore a dependency
274 by using a line like the following:
275 <literallayout class='monospaced'>
276 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
277 </literallayout>
278 This example ensures that the <filename>PACKAGE_ARCHS</filename> variable does not
279 depend on the value of <filename>MACHINE</filename>, even if it does reference it.
280 </para>
281
282 <para>
283 Equally, there are cases where we need to add dependencies BitBake is not able to find.
284 You can accomplish this by using a line like the following:
285 <literallayout class='monospaced'>
286 PACKAGE_ARCHS[vardeps] = "MACHINE"
287 </literallayout>
288 This example explicitly adds the <filename>MACHINE</filename> variable as a
289 dependency for <filename>PACKAGE_ARCHS</filename>.
290 </para>
291
292 <para>
293 Consider a case with inline python, for example, where BitBake is not
294 able to figure out dependencies.
295 When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake
296 produces output when it discovers something for which it cannot figure out
297 dependencies.
298 The Yocto Project team has currently not managed to cover those dependencies
299 in detail and is aware of the need to fix this situation.
300 </para>
301
302 <para>
303 Thus far, this section has limited discussion to the direct inputs into a task.
304 Information based on direct inputs is referred to as the "basehash" in the
305 code.
306 However, there is still the question of a task's indirect inputs - the
307 things that were already built and present in the Build Directory.
308 The checksum (or signature) for a particular task needs to add the hashes
309 of all the tasks on which the particular task depends.
310 Choosing which dependencies to add is a policy decision.
311 However, the effect is to generate a master checksum that combines the basehash
312 and the hashes of the task's dependencies.
313 </para>
314
315 <para>
316 At the code level, there are a variety of ways both the basehash and the
317 dependent task hashes can be influenced.
318 Within the BitBake configuration file, we can give BitBake some extra information
319 to help it construct the basehash.
320 The following statements effectively result in a list of global variable
321 dependency excludes - variables never included in any checksum:
322 <literallayout class='monospaced'>
323 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH"
324 BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS"
325 BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER"
326 BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET"
327 </literallayout>
328 The previous example actually excludes
329 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
330 since it is actually constructed as a path within
331 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on
332 the whitelist.
333 </para>
334
335 <para>
336 The rules for deciding which hashes of dependent tasks to include through
337 dependency chains are more complex and are generally accomplished with a
338 python function.
339 The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples
340 of this and also illustrates how you can insert your own policy into the system
341 if so desired.
342 This file defines the two basic signature generators <filename>OE-Core</filename>
343 uses: "OEBasic" and "OEBasicHash".
344 By default, there is a dummy "noop" signature handler enabled in BitBake.
345 This means that behavior is unchanged from previous versions.
346 <filename>OE-Core</filename> uses the "OEBasic" signature handler by default
347 through this setting in the <filename>bitbake.conf</filename> file:
348 <literallayout class='monospaced'>
349 BB_SIGNATURE_HANDLER ?= "OEBasic"
350 </literallayout>
351 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
352 "OEBasic" version but adds the task hash to the stamp files.
353 This results in any metadata change that changes the task hash, automatically
354 causing the task to be run again.
355 This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link>
356 values and changes to metadata automatically ripple across the build.
357 Currently, this behavior is not the default behavior for <filename>OE-Core</filename>
358 but is the default in <filename>poky</filename>.
359 </para>
360
361 <para>
362 It is also worth noting that the end result of these signature generators is to
363 make some dependency and hash information available to the build.
364 This information includes:
365 <literallayout class='monospaced'>
366 BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe
367 BB_BASEHASH_&lt;filename:taskname&gt; - the base hashes for each dependent task
368 BBHASHDEPS_&lt;filename:taskname&gt; - The task dependencies for each task
369 BB_TASKHASH - the hash of the currently running task
370 </literallayout>
371 </para>
372 </section>
373
374 <section id='shared-state'>
375 <title>Shared State</title>
376
377 <para>
378 Checksums and dependencies, as discussed in the previous section, solve half the
379 problem.
380 The other part of the problem is being able to use checksum information during the build
381 and being able to reuse or rebuild specific components.
382 </para>
383
384 <para>
385 The shared state class (<filename>sstate.bbclass</filename>)
386 is a relatively generic implementation of how to "capture" a snapshot of a given task.
387 The idea is that the build process does not care about the source of a task's output.
388 Output could be freshly built or it could be downloaded and unpacked from
389 somewhere - the build process doesn't need to worry about its source.
390 </para>
391
392 <para>
393 There are two types of output, one is just about creating a directory
394 in <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
395 A good example is the output of either <filename>do_install</filename> or
396 <filename>do_package</filename>.
397 The other type of output occurs when a set of data is merged into a shared directory
398 tree such as the sysroot.
399 </para>
400
401 <para>
402 The Yocto Project team has tried to keep the details of the implementation hidden in
403 <filename>sstate.bbclass</filename>.
404 From a user's perspective, adding shared state wrapping to a task
405 is as simple as this <filename>do_deploy</filename> example taken from
406 <filename>do_deploy.bbclass</filename>:
407 <literallayout class='monospaced'>
408 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
409 SSTATETASKS += "do_deploy"
410 do_deploy[sstate-name] = "deploy"
411 do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
412 do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
413
414 python do_deploy_setscene () {
415 sstate_setscene(d)
416 }
417 addtask do_deploy_setscene
418 </literallayout>
419 In the example, we add some extra flags to the task, a name field ("deploy"), an
420 input directory where the task sends data, and the output
421 directory where the data from the task should eventually be copied.
422 We also add a <filename>_setscene</filename> variant of the task and add the task
423 name to the <filename>SSTATETASKS</filename> list.
424 </para>
425
426 <para>
427 If you have a directory whose contents you need to preserve, you can do this with
428 a line like the following:
429 <literallayout class='monospaced'>
430 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
431 </literallayout>
432 This method, as well as the following example, also works for multiple directories.
433 <literallayout class='monospaced'>
434 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
435 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
436 do_package[sstate-lockfile] = "${PACKAGELOCK}"
437 </literallayout>
438 These methods also include the ability to take a lockfile when manipulating
439 shared state directory structures since some cases are sensitive to file
440 additions or removals.
441 </para>
442
443 <para>
444 Behind the scenes, the shared state code works by looking in
445 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> and
446 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
447 for shared state files.
448 Here is an example:
449 <literallayout class='monospaced'>
450 SSTATE_MIRRORS ?= "\
451 file://.* http://someserver.tld/share/sstate/PATH \n \
452 file://.* file:///some/local/dir/sstate/PATH"
453 </literallayout>
454 <note>
455 The shared state directory (<filename>SSTATE_DIR</filename>) is
456 organized into two-character subdirectories, where the subdirectory
457 names are based on the first two characters of the hash.
458 If the shared state directory structure for a mirror has the
459 same structure as <filename>SSTATE_DIR</filename>, you must
460 specify "PATH" as part of the URI to enable the build system
461 to map to the appropriate subdirectory.
462 </note>
463 </para>
464
465 <para>
466 The shared state package validity can be detected just by looking at the
467 filename since the filename contains the task checksum (or signature) as
468 described earlier in this section.
469 If a valid shared state package is found, the build process downloads it
470 and uses it to accelerate the task.
471 </para>
472
473 <para>
474 The build processes uses the <filename>*_setscene</filename> tasks
475 for the task acceleration phase.
476 BitBake goes through this phase before the main execution code and tries
477 to accelerate any tasks for which it can find shared state packages.
478 If a shared state package for a task is available, the shared state
479 package is used.
480 This means the task and any tasks on which it is dependent are not
481 executed.
482 </para>
483
484 <para>
485 As a real world example, the aim is when building an IPK-based image,
486 only the <filename>do_package_write_ipk</filename> tasks would have their
487 shared state packages fetched and extracted.
488 Since the sysroot is not used, it would never get extracted.
489 This is another reason why a task-based approach is preferred over a
490 recipe-based approach, which would have to install the output from every task.
491 </para>
492 </section>
493
494 <section id='tips-and-tricks'>
495 <title>Tips and Tricks</title>
496
497 <para>
498 The code in the build system that supports incremental builds is not
499 simple code.
500 This section presents some tips and tricks that help you work around
501 issues related to shared state code.
502 </para>
503
504 <section id='debugging'>
505 <title>Debugging</title>
506
507 <para>
508 When things go wrong, debugging needs to be straightforward.
509 Because of this, the Yocto Project team included strong debugging
510 tools:
511 <itemizedlist>
512 <listitem><para>Whenever a shared state package is written out, so is a
513 corresponding <filename>.siginfo</filename> file.
514 This practice results in a pickled python database of all
515 the metadata that went into creating the hash for a given shared state
516 package.</para></listitem>
517 <listitem><para>If BitBake is run with the <filename>--dump-signatures</filename>
518 (or <filename>-S</filename>) option, BitBake dumps out
519 <filename>.siginfo</filename> files in
520 the stamp directory for every task it would have executed instead of
521 building the specified target package.</para></listitem>
522 <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that
523 can process these <filename>.siginfo</filename> files.
524 If one file is specified, it will dump out the dependency
525 information in the file.
526 If two files are specified, it will compare the two files and dump out
527 the differences between the two.
528 This allows the question of "What changed between X and Y?" to be
529 answered easily.</para></listitem>
530 </itemizedlist>
531 </para>
532 </section>
533
534 <section id='invalidating-shared-state'>
535 <title>Invalidating Shared State</title>
536
537 <para>
538 The shared state code uses checksums and shared state
539 cache to avoid unnecessarily rebuilding tasks.
540 As with all schemes, this one has some drawbacks.
541 It is possible that you could make implicit changes that are not factored
542 into the checksum calculation, but do affect a task's output.
543 A good example is perhaps when a tool changes its output.
544 Let's say that the output of <filename>rpmdeps</filename> needed to change.
545 The result of the change should be that all the "package", "package_write_rpm",
546 and "package_deploy-rpm" shared state cache items would become invalid.
547 But, because this is a change that is external to the code and therefore implicit,
548 the associated shared state cache items do not become invalidated.
549 In this case, the build process would use the cached items rather than running the
550 task again.
551 Obviously, these types of implicit changes can cause problems.
552 </para>
553
554 <para>
555 To avoid these problems during the build, you need to understand the effects of any
556 change you make.
557 Note that any changes you make directly to a function automatically are factored into
558 the checksum calculation and thus, will invalidate the associated area of sstate cache.
559 You need to be aware of any implicit changes that are not obvious changes to the
560 code and could affect the output of a given task.
561 Once you are aware of such a change, you can take steps to invalidate the cache
562 and force the task to run.
563 The step to take is as simple as changing a function's comments in the source code.
564 For example, to invalidate package shared state files, change the comment statements
565 of <filename>do_package</filename> or the comments of one of the functions it calls.
566 The change is purely cosmetic, but it causes the checksum to be recalculated and
567 forces the task to be run again.
568 </para>
569
570 <note>
571 For an example of a commit that makes a cosmetic change to invalidate
572 a shared state, see this
573 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
574 </note>
575 </section>
576 </section>
577</section>
578
579<section id='x32'>
580 <title>x32</title>
581
582 <para>
583 x32 is a new processor-specific Application Binary Interface (psABI) for x86_64.
584 An ABI defines the calling conventions between functions in a processing environment.
585 The interface determines what registers are used and what the sizes are for various C data types.
586 </para>
587
588 <para>
589 Some processing environments prefer using 32-bit applications even when running
590 on Intel 64-bit platforms.
591 Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
592 The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
593 leaving the system underutilized.
594 Now consider the x86_64 psABI.
595 This ABI is newer and uses 64-bits for data sizes and program pointers.
596 The extra bits increase the footprint size of the programs, libraries,
597 and also increases the memory and file system size requirements.
598 Executing under the x32 psABI enables user programs to utilize CPU and system resources
599 more efficiently while keeping the memory footprint of the applications low.
600 Extra bits are used for registers but not for addressing mechanisms.
601 </para>
602
603 <section id='support'>
604 <title>Support</title>
605
606 <para>
607 While the x32 psABI specifications are not fully finalized, this Yocto Project
608 release supports current development specifications of x32 psABI.
609 As of this release of the Yocto Project, x32 psABI support exists as follows:
610 <itemizedlist>
611 <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets.
612 </para></listitem>
613 <listitem><para>You can use the x32 psABI support through the <filename>meta-x32</filename>
614 layer on top of the OE-core/Yocto layer.</para></listitem>
615 <listitem><para>The toolchain from the <filename>experimental/meta-x32</filename> layer
616 is used for building x32 psABI program binaries.</para></listitem>
617 <listitem><para>You can successfully build many recipes with the x32 toolchain.</para></listitem>
618 <listitem><para>You can create and boot <filename>core-image-minimal</filename> and
619 <filename>core-image-sato</filename> images.</para></listitem>
620 </itemizedlist>
621 </para>
622 </section>
623
624 <section id='future-development-and-limitations'>
625 <title>Future Development and Limitations</title>
626
627 <para>
628 As of this Yocto Project release, the x32 psABI kernel and library interfaces
629 specifications are not finalized.
630 </para>
631
632 <para>
633 Future Plans for the x32 psABI in the Yocto Project include the following:
634 <itemizedlist>
635 <listitem><para>Enhance and fix the few remaining recipes so they
636 work with and support x32 toolchains.</para></listitem>
637 <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem>
638 <listitem><para>Support larger images.</para></listitem>
639 <listitem><para>Integrate x32 recipes, toolchain, and kernel changes from
640 <filename>experimental/meta-x32</filename> into OE-core.</para></listitem>
641 </itemizedlist>
642 </para>
643 </section>
644
645 <section id='using-x32-right-now'>
646 <title>Using x32 Right Now</title>
647
648 <para>
649 Despite the fact the x32 psABI support is in development state for this release of the
650 Yocto Project, you can follow these steps to use the x32 spABI:
651 <itemizedlist>
652 <listitem><para>Add the <filename>experimental/meta-x32</filename> layer to your local
653 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
654 You can find the <filename>experimental/meta-x32</filename> source repository at
655 <ulink url='&YOCTO_GIT_URL;'></ulink>.</para></listitem>
656 <listitem><para>Edit your <filename>conf/bblayers.conf</filename> file so that it includes
657 the <filename>meta-x32</filename>.
658 Here is an example:
659 <literallayout class='monospaced'>
660 BBLAYERS ?= " \
661 /home/nitin/prj/poky.git/meta \
662 /home/nitin/prj/poky.git/meta-yocto \
663 /home/nitin/prj/poky.git/meta-yocto-bsp \
664 /home/nitin/prj/meta-x32.git \
665 "
666 BBLAYERS_NON_REMOVABLE ?= " \
667 /home/nitin/prj/poky.git/meta \
668 /home/nitin/prj/poky.git/meta-yocto \
669 "
670 </literallayout></para></listitem>
671 <listitem><para>Enable the x32 psABI tuning file for <filename>x86_64</filename>
672 machines by editing the <filename>conf/local.conf</filename> like this:
673 <literallayout class='monospaced'>
674 MACHINE = "qemux86-64"
675 DEFAULTTUNE = "x86-64-x32"
676 baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
677 or 'INVALID'), True) or 'lib'}"
678 #MACHINE = "atom-pc"
679 #DEFAULTTUNE = "core2-64-x32"
680 </literallayout></para></listitem>
681 <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI.
682 Here is an example:
683 <literallayout class='monospaced'>
684 $ bitake core-image-sato
685 </literallayout></para></listitem>
686 <listitem><para>As usual, run your image using QEMU:
687 <literallayout class='monospaced'>
688 $ runqemu qemux86-64 core-image-sato
689 </literallayout></para></listitem>
690 </itemizedlist>
691 </para>
692 </section>
693</section>
694
695<section id="licenses">
696 <title>Licenses</title>
697
698 <para>
699 This section describes the mechanism by which the OpenEmbedded build system
700 tracks changes to licensing text.
701 The section also describes how to enable commercially licensed recipes,
702 which by default are disabled.
703 </para>
704
705 <para>
706 For information that can help you maintain compliance with various open
707 source licensing during the lifecycle of the product, see the
708 "<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
709 in the Yocto Project Development Manual.
710 </para>
711
712 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
713 <title>Tracking License Changes</title>
714
715 <para>
716 The license of an upstream project might change in the future.
717 In order to prevent these changes going unnoticed, the
718 <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
719 variable tracks changes to the license text. The checksums are validated at the end of the
720 configure step, and if the checksums do not match, the build will fail.
721 </para>
722
723 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
724 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
725
726 <para>
727 The <filename>LIC_FILES_CHKSUM</filename>
728 variable contains checksums of the license text in the source code for the recipe.
729 Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>:
730 <literallayout class='monospaced'>
731 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
732 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
733 file://licfile2.txt;endline=50;md5=zzzz \
734 ..."
735 </literallayout>
736 </para>
737
738 <para>
739 The build system uses the
740 <filename><link linkend='var-S'>S</link></filename> variable as the
741 default directory used when searching files listed in
742 <filename>LIC_FILES_CHKSUM</filename>.
743 The previous example employs the default directory.
744 </para>
745
746 <para>
747 You can also use relative paths as shown in the following example:
748 <literallayout class='monospaced'>
749 LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
750 md5=bb14ed3c4cda583abc85401304b5cd4e"
751 LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
752 </literallayout>
753 </para>
754
755 <para>
756 In this example, the first line locates a file in
757 <filename>${S}/src/ls.c</filename>.
758 The second line refers to a file in
759 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, which is the parent
760 of <filename><link linkend='var-S'>S</link></filename>.
761 </para>
762 <para>
763 Note that this variable is mandatory for all recipes, unless the
764 <filename>LICENSE</filename> variable is set to "CLOSED".
765 </para>
766 </section>
767
768 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
769 <title>Explanation of Syntax</title>
770 <para>
771 As mentioned in the previous section, the
772 <filename>LIC_FILES_CHKSUM</filename> variable lists all the
773 important files that contain the license text for the source code.
774 It is possible to specify a checksum for an entire file, or a specific section of a
775 file (specified by beginning and ending line numbers with the "beginline" and "endline"
776 parameters, respectively).
777 The latter is useful for source files with a license notice header,
778 README documents, and so forth.
779 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
780 first line of the file.
781 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
782 ends with the last line of the file.
783 </para>
784
785 <para>
786 The "md5" parameter stores the md5 checksum of the license text.
787 If the license text changes in any way as compared to this parameter
788 then a mismatch occurs.
789 This mismatch triggers a build failure and notifies the developer.
790 Notification allows the developer to review and address the license text changes.
791 Also note that if a mismatch occurs during the build, the correct md5
792 checksum is placed in the build log and can be easily copied to the recipe.
793 </para>
794
795 <para>
796 There is no limit to how many files you can specify using the
797 <filename>LIC_FILES_CHKSUM</filename> variable.
798 Generally, however, every project requires a few specifications for license tracking.
799 Many projects have a "COPYING" file that stores the license information for all the source
800 code files.
801 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
802 </para>
803
804 <tip>
805 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
806 error and displays the correct "md5" parameter value during the build.
807 The correct parameter is also captured in the build log.
808 </tip>
809
810 <tip>
811 If the whole file contains only license text, you do not need to use the "beginline" and
812 "endline" parameters.
813 </tip>
814 </section>
815 </section>
816
817 <section id="enabling-commercially-licensed-recipes">
818 <title>Enabling Commercially Licensed Recipes</title>
819
820 <para>
821 By default, the OpenEmbedded build system disables
822 components that have commercial or other special licensing
823 requirements.
824 Such requirements are defined on a
825 recipe-by-recipe basis through the <filename>LICENSE_FLAGS</filename> variable
826 definition in the affected recipe.
827 For instance, the
828 <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
829 recipe contains the following statement:
830 <literallayout class='monospaced'>
831 LICENSE_FLAGS = "commercial"
832 </literallayout>
833 Here is a slightly more complicated example that contains both an
834 explicit recipe name and version (after variable expansion):
835 <literallayout class='monospaced'>
836 LICENSE_FLAGS = "license_${PN}_${PV}"
837 </literallayout>
838 In order for a component restricted by a <filename>LICENSE_FLAGS</filename>
839 definition to be enabled and included in an image, it
840 needs to have a matching entry in the global
841 <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable
842 typically defined in your <filename>local.conf</filename> file.
843 For example, to enable
844 the <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
845 package, you could add either the string
846 "commercial_gst-plugins-ugly" or the more general string
847 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
848 See the
849 "<link linkend='license-flag-matching'>License Flag Matching</link>" section
850 for a full explanation of how <filename>LICENSE_FLAGS</filename> matching works.
851 Here is the example:
852 <literallayout class='monospaced'>
853 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
854 </literallayout>
855 Likewise, to additionally enable the package built from the recipe containing
856 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, and assuming
857 that the actual recipe name was <filename>emgd_1.10.bb</filename>,
858 the following string would enable that package as well as
859 the original <filename>gst-plugins-ugly</filename> package:
860 <literallayout class='monospaced'>
861 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
862 </literallayout>
863 As a convenience, you do not need to specify the complete license string
864 in the whitelist for every package.
865 you can use an abbreviated form, which consists
866 of just the first portion or portions of the license string before
867 the initial underscore character or characters.
868 A partial string will match
869 any license that contains the given string as the first
870 portion of its license.
871 For example, the following
872 whitelist string will also match both of the packages
873 previously mentioned as well as any other packages that have
874 licenses starting with "commercial" or "license".
875 <literallayout class='monospaced'>
876 LICENSE_FLAGS_WHITELIST = "commercial license"
877 </literallayout>
878 </para>
879
880 <section id="license-flag-matching">
881 <title>License Flag Matching</title>
882
883 <para>
884 The definition of 'matching' in reference to a
885 recipe's <filename>LICENSE_FLAGS</filename> setting is simple.
886 However, some things exist that you should know about in order to
887 correctly and effectively use it.
888 </para>
889
890 <para>
891 Before a flag
892 defined by a particular recipe is tested against the
893 contents of the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, the
894 string <filename>_${PN}</filename> (with
895 <link linkend='var-PN'><filename>PN</filename></link> expanded of course) is
896 appended to the flag, thus automatically making each
897 <filename>LICENSE_FLAGS</filename> value recipe-specific.
898 That string is
899 then matched against the whitelist.
900 So if you specify <filename>LICENSE_FLAGS = "commercial"</filename> in recipe
901 "foo" for example, the string <filename>"commercial_foo"</filename>
902 would normally be what is specified in the whitelist in order for it to
903 match.
904 </para>
905
906 <para>
907 You can broaden the match by
908 putting any "_"-separated beginning subset of a
909 <filename>LICENSE_FLAGS</filename> flag in the whitelist, which will also
910 match.
911 For example, simply specifying "commercial" in
912 the whitelist would match any expanded <filename>LICENSE_FLAGS</filename>
913 definition starting with "commercial" such as
914 "commercial_foo" and "commercial_bar", which are the
915 strings that would be automatically generated for
916 hypothetical "foo" and "bar" recipes assuming those
917 recipes had simply specified the following:
918 <literallayout class='monospaced'>
919 LICENSE_FLAGS = "commercial"
920 </literallayout>
921 </para>
922
923 <para>
924 Broadening the match allows for a range of specificity for the items
925 in the whitelist, from more general to perfectly
926 specific.
927 So you have the choice of exhaustively
928 enumerating each license flag in the whitelist to
929 allow only those specific recipes into the image, or
930 of using a more general string to pick up anything
931 matching just the first component or components of the specified
932 string.
933 </para>
934
935 <para>
936 This scheme works even if the flag already
937 has <filename>_${PN}</filename> appended - the extra <filename>_${PN}</filename> is
938 redundant, but does not affect the outcome.
939 For example, a license flag of "commercial_1.2_foo" would
940 turn into "commercial_1.2_foo_foo" and would match
941 both the general "commercial" and the specific
942 "commercial_1.2_foo", as expected.
943 The flag would also match
944 "commercial_1.2_foo_foo" and "commercial_1.2", which
945 does not make much sense regarding use in the whitelist.
946 </para>
947
948 <para>
949 For a versioned string, you could instead specify
950 "commercial_foo_1.2", which would turn into
951 "commercial_foo_1.2_foo".
952 And, as expected, this flag allows
953 you to pick up this package along with
954 anything else "commercial" when you specify "commercial"
955 in the whitelist.
956 Or, the flag allows you to pick up this package along with anything "commercial_foo"
957 regardless of version when you use "commercial_foo" in the whitelist.
958 Finally, you can be completely specific about the package and version and specify
959 "commercial_foo_1.2" package and version.
960 </para>
961 </section>
962
963 <section id="other-variables-related-to-commercial-licenses">
964 <title>Other Variables Related to Commercial Licenses</title>
965
966 <para>
967 Other helpful variables related to commercial
968 license handling exist and are defined in the
969 <filename>$HOME/poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
970 <literallayout class='monospaced'>
971 COMMERCIAL_AUDIO_PLUGINS ?= ""
972 COMMERCIAL_VIDEO_PLUGINS ?= ""
973 COMMERCIAL_QT = ""
974 </literallayout>
975 If you want to enable these components, you can do so by making sure you have
976 the following statements in your <filename>local.conf</filename> configuration file:
977 <literallayout class='monospaced'>
978 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
979 gst-plugins-ugly-mpegaudioparse"
980 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
981 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
982 COMMERCIAL_QT ?= "qmmp"
983 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
984 </literallayout>
985 Of course, you could also create a matching whitelist
986 for those components using the more general "commercial"
987 in the whitelist, but that would also enable all the
988 other packages with <filename>LICENSE_FLAGS</filename> containing
989 "commercial", which you may or may not want:
990 <literallayout class='monospaced'>
991 LICENSE_FLAGS_WHITELIST = "commercial"
992 </literallayout>
993 </para>
994
995 <para>
996 Specifying audio and video plug-ins as part of the
997 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
998 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
999 or commercial qt components as part of
1000 the <filename>COMMERCIAL_QT</filename> statement (along
1001 with the enabling <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
1002 plug-ins or components into built images, thus adding
1003 support for media formats or components.
1004 </para>
1005 </section>
1006 </section>
1007</section>
1008</chapter>
1009<!--
1010vim: expandtab tw=80 ts=4
1011-->
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='usingpoky'>
6<title>Using the Yocto Project</title>
7
8 <para>
9 This chapter describes common usage for the Yocto Project.
10 The information is introductory in nature as other manuals in the Yocto Project
11 documentation set provide more details on how to use the Yocto Project.
12 </para>
13
14<section id='usingpoky-build'>
15 <title>Running a Build</title>
16
17 <para>
18 This section provides a summary of the build process and provides information
19 for less obvious aspects of the build process.
20 For general information on how to build an image using the OpenEmbedded build
21 system, see the
22 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
23 section of the Yocto Project Quick Start.
24 </para>
25
26 <section id='build-overview'>
27 <title>Build Overview</title>
28
29 <para>
30 The first thing you need to do is set up the OpenEmbedded build environment by sourcing
31 the <link linkend='structure-core-script'>environment setup script</link> as follows:
32 <literallayout class='monospaced'>
33 $ source &OE_INIT_FILE; [build_dir]
34 </literallayout>
35 </para>
36
37 <para>
38 The <filename>build_dir</filename> is optional and specifies the directory the
39 OpenEmbedded build system uses for the build -
40 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
41 If you do not specify a Build Directory it defaults to <filename>build</filename>
42 in your current working directory.
43 A common practice is to use a different Build Directory for different targets.
44 For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
45 target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
46 See <link linkend="structure-core-script">&OE_INIT_FILE;</link>
47 for more information on this script.
48 </para>
49
50 <para>
51 Once the build environment is set up, you can build a target using:
52 <literallayout class='monospaced'>
53 $ bitbake &lt;target&gt;
54 </literallayout>
55 </para>
56
57 <para>
58 The <filename>target</filename> is the name of the recipe you want to build.
59 Common targets are the images in <filename>meta/recipes-core/images</filename>,
60 <filename>/meta/recipes-sato/images</filename>, etc. all found in the
61 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
62 Or, the target can be the name of a recipe for a specific piece of software such as
63 <application>busybox</application>.
64 For more details about the images the OpenEmbedded build system supports, see the
65 "<link linkend="ref-images">Images</link>" chapter.
66 </para>
67
68 <note>
69 Building an image without GNU General Public License Version 3 (GPLv3) components
70 is only supported for minimal and base images.
71 See the "<link linkend='ref-images'>Images</link>" chapter for more information.
72 </note>
73 </section>
74
75 <section id='building-an-image-using-gpl-components'>
76 <title>Building an Image Using GPL Components</title>
77
78 <para>
79 When building an image using GPL components, you need to maintain your original
80 settings and not switch back and forth applying different versions of the GNU
81 General Public License.
82 If you rebuild using different versions of GPL, dependency errors might occur
83 due to some components not being rebuilt.
84 </para>
85 </section>
86</section>
87
88<section id='usingpoky-install'>
89 <title>Installing and Using the Result</title>
90
91 <para>
92 Once an image has been built, it often needs to be installed.
93 The images and kernels built by the OpenEmbedded build system are placed in the
94 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in
95 <filename class="directory">tmp/deploy/images</filename>.
96 For information on how to run pre-built images such as <filename>qemux86</filename>
97 and <filename>qemuarm</filename>, see the
98 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
99 section in the Yocto Project Quick Start.
100 For information about how to install these images, see the documentation for your
101 particular board/machine.
102 </para>
103</section>
104
105<section id='usingpoky-debugging'>
106 <title>Debugging Build Failures</title>
107
108 <para>
109 The exact method for debugging build failures depends on the nature of the
110 problem and on the system's area from which the bug originates.
111 Standard debugging practices such as comparison against the last
112 known working version with examination of the changes and the re-application of steps
113 to identify the one causing the problem are
114 valid for the Yocto Project just as they are for any other system.
115 Even though it is impossible to detail every possible potential failure,
116 this section provides some general tips to aid in debugging.
117 </para>
118
119 <section id='usingpoky-debugging-taskfailures'>
120 <title>Task Failures</title>
121
122 <para>The log file for shell tasks is available in
123 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
124 For example, the <filename>compile</filename> task for the QEMU minimal image for the x86
125 machine (<filename>qemux86</filename>) might be
126 <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</filename>.
127 To see what BitBake runs to generate that log, look at the corresponding
128 <filename>run.do_taskname.pid</filename> file located in the same directory.
129 </para>
130
131 <para>
132 Presently, the output from Python tasks is sent directly to the console.
133 </para>
134 </section>
135
136 <section id='usingpoky-debugging-taskrunning'>
137 <title>Running Specific Tasks</title>
138
139 <para>
140 Any given package consists of a set of tasks.
141 The standard BitBake behavior in most cases is: <filename>fetch</filename>,
142 <filename>unpack</filename>,
143 <filename>patch</filename>, <filename>configure</filename>,
144 <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>,
145 <filename>package_write</filename>, and <filename>build</filename>.
146 The default task is <filename>build</filename> and any tasks on which it depends
147 build first.
148 Some tasks exist, such as <filename>devshell</filename>, that are not part of the
149 default build chain.
150 If you wish to run a task that is not part of the default build chain, you can use the
151 <filename>-c</filename> option in BitBake as follows:
152 <literallayout class='monospaced'>
153 $ bitbake matchbox-desktop -c devshell
154 </literallayout>
155 </para>
156
157 <para>
158 If you wish to rerun a task, use the <filename>-f</filename> force option.
159 For example, the following sequence forces recompilation after changing files in the
160 working directory.
161 <literallayout class='monospaced'>
162 $ bitbake matchbox-desktop
163 .
164 .
165 [make some changes to the source code in the working directory]
166 .
167 .
168 $ bitbake matchbox-desktop -c compile -f
169 $ bitbake matchbox-desktop
170 </literallayout>
171 </para>
172
173 <para>
174 This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it.
175 The last command reruns all tasks (basically the packaging tasks) after the compile.
176 BitBake recognizes that the <filename>compile</filename> task was rerun and therefore
177 understands that the other tasks also need to be run again.
178 </para>
179
180 <para>
181 You can view a list of tasks in a given package by running the
182 <filename>listtasks</filename> task as follows:
183 <literallayout class='monospaced'>
184 $ bitbake matchbox-desktop -c listtasks
185 </literallayout>
186 The results are in the file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
187 </para>
188 </section>
189
190 <section id='usingpoky-debugging-dependencies'>
191 <title>Dependency Graphs</title>
192
193 <para>
194 Sometimes it can be hard to see why BitBake wants to build some other packages before a given
195 package you have specified.
196 The <filename>bitbake -g targetname</filename> command creates the
197 <filename>depends.dot</filename>, <filename>package-depends.dot</filename>,
198 and <filename>task-depends.dot</filename> files in the current directory.
199 These files show the package and task dependencies and are useful for debugging problems.
200 You can use the <filename>bitbake -g -u depexp targetname</filename> command to
201 display the results in a more human-readable form.
202 </para>
203 </section>
204
205 <section id='usingpoky-debugging-bitbake'>
206 <title>General BitBake Problems</title>
207
208 <para>
209 You can see debug output from BitBake by using the <filename>-D</filename> option.
210 The debug output gives more information about what BitBake
211 is doing and the reason behind it.
212 Each <filename>-D</filename> option you use increases the logging level.
213 The most common usage is <filename>-DDD</filename>.
214 </para>
215
216 <para>
217 The output from <filename>bitbake -DDD -v targetname</filename> can reveal why
218 BitBake chose a certain version of a package or why BitBake
219 picked a certain provider.
220 This command could also help you in a situation where you think BitBake did something
221 unexpected.
222 </para>
223 </section>
224
225 <section id='usingpoky-debugging-buildfile'>
226 <title>Building with No Dependencies</title>
227 <para>
228 If you really want to build a specific <filename>.bb</filename> file, you can use
229 the command form <filename>bitbake -b &lt;somepath/somefile.bb&gt;</filename>.
230 This command form does not check for dependencies so you should use it
231 only when you know its dependencies already exist.
232 You can also specify fragments of the filename.
233 In this case, BitBake checks for a unique match.
234 </para>
235 </section>
236
237 <section id='usingpoky-debugging-variables'>
238 <title>Variables</title>
239 <para>
240 The <filename>-e</filename> option dumps the resulting environment for
241 either the configuration (no package specified) or for a
242 specific package when specified; or <filename>-b recipename</filename>
243 to show the environment from parsing a single recipe file only.
244 </para>
245 </section>
246
247 <section id='recipe-logging-mechanisms'>
248 <title>Recipe Logging Mechanisms</title>
249 <para>
250 Best practices exist while writing recipes that both log build progress and
251 act on build conditions such as warnings and errors.
252 Both Python and Bash language bindings exist for the logging mechanism:
253 <itemizedlist>
254 <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake
255 supports several loglevels: <filename>bb.fatal</filename>,
256 <filename>bb.error</filename>, <filename>bb.warn</filename>,
257 <filename>bb.note</filename>, <filename>bb.plain</filename>,
258 and <filename>bb.debug</filename>.</para></listitem>
259 <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set
260 of loglevels exist and are accessed with a similar syntax:
261 <filename>bbfatal</filename>, <filename>bberror</filename>,
262 <filename>bbwarn</filename>, <filename>bbnote</filename>,
263 <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem>
264 </itemizedlist>
265 </para>
266
267 <para>
268 For guidance on how logging is handled in both Python and Bash recipes, see the
269 <filename>logging.bbclass</filename> file in the
270 <filename>meta/classes</filename> folder of the
271 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
272 </para>
273
274 <section id='logging-with-python'>
275 <title>Logging With Python</title>
276 <para>
277 When creating recipes using Python and inserting code that handles build logs
278 keep in mind the goal is to have informative logs while keeping the console as
279 "silent" as possible.
280 Also, if you want status messages in the log use the "debug" loglevel.
281 </para>
282
283 <para>
284 Following is an example written in Python.
285 The code handles logging for a function that determines the number of tasks
286 needed to be run:
287 <literallayout class='monospaced'>
288 python do_listtasks() {
289 bb.debug(2, "Starting to figure out the task list")
290 if noteworthy_condition:
291 bb.note("There are 47 tasks to run")
292 bb.debug(2, "Got to point xyz")
293 if warning_trigger:
294 bb.warn("Detected warning_trigger, this might be a problem later.")
295 if recoverable_error:
296 bb.error("Hit recoverable_error, you really need to fix this!")
297 if fatal_error:
298 bb.fatal("fatal_error detected, unable to print the task list")
299 bb.plain("The tasks present are abc")
300 bb.debug(2, "Finished figuring out the tasklist")
301 }
302 </literallayout>
303 </para>
304 </section>
305
306 <section id='logging-with-bash'>
307 <title>Logging With Bash</title>
308 <para>
309 When creating recipes using Bash and inserting code that handles build
310 logs you have the same goals - informative with minimal console output.
311 The syntax you use for recipes written in Bash is similar to that of
312 recipes written in Python described in the previous section.
313 </para>
314
315 <para>
316 Following is an example written in Bash.
317 The code logs the progress of the <filename>do_my_function</filename> function.
318 <literallayout class='monospaced'>
319 do_my_function() {
320 bbdebug 2 "Running do_my_function"
321 if [ exceptional_condition ]; then
322 bbnote "Hit exceptional_condition"
323 fi
324 bbdebug 2 "Got to point xyz"
325 if [ warning_trigger ]; then
326 bbwarn "Detected warning_trigger, this might cause a problem later."
327 fi
328 if [ recoverable_error ]; then
329 bberror "Hit recoverable_error, correcting"
330 fi
331 if [ fatal_error ]; then
332 bbfatal "fatal_error detected"
333 fi
334 bbdebug 2 "Completed do_my_function"
335 }
336 </literallayout>
337 </para>
338 </section>
339 </section>
340
341 <section id='usingpoky-debugging-others'>
342 <title>Other Tips</title>
343
344 <para>
345 Here are some other tips that you might find useful:
346 <itemizedlist>
347 <listitem><para>When adding new packages, it is worth watching for
348 undesirable items making their way into compiler command lines.
349 For example, you do not want references to local system files like
350 <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
351 </para></listitem>
352 <listitem><para>If you want to remove the psplash boot splashscreen,
353 add <filename>psplash=false</filename> to the kernel command line.
354 Doing so prevents psplash from loading and thus allows you to see the console.
355 It is also possible to switch out of the splashscreen by
356 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
357 </para></listitem>
358 </itemizedlist>
359 </para>
360 </section>
361</section>
362
363<section id='maintaining-build-output-quality'>
364 <title>Maintaining Build Output Quality</title>
365
366 <para>
367 A build's quality can be influenced by many things.
368 For example, if you upgrade a recipe to use a new version of an upstream software
369 package or you experiment with some new configuration options, subtle changes
370 can occur that you might not detect until later.
371 Consider the case where your recipe is using a newer version of an upstream package.
372 In this case, a new version of a piece of software might introduce an optional
373 dependency on another library, which is auto-detected.
374 If that library has already been built when the software is building,
375 then the software will link to the built library and that library will be pulled
376 into your image along with the new software even if you did not want the
377 library.
378 </para>
379
380 <para>
381 The <filename>buildhistory</filename> class exists to help you maintain
382 the quality of your build output.
383 You can use the class to highlight unexpected and possibly unwanted
384 changes in the build output.
385 When you enable build history it records information about the contents of
386 each package and image and then commits that information to a local Git
387 repository where you can examine the information.
388 </para>
389
390 <para>
391 The remainder of this section describes the following:
392 <itemizedlist>
393 <listitem><para>How you can enable and disable
394 build history</para></listitem>
395 <listitem><para>How to understand what the build history contains
396 </para></listitem>
397 <listitem><para>How to limit the information used for build history
398 </para></listitem>
399 <listitem><para>How to examine the build history from both a
400 command-line and web interface</para></listitem>
401 </itemizedlist>
402 </para>
403
404 <section id='enabling-and-disabling-build-history'>
405 <title>Enabling and Disabling Build History</title>
406
407 <para>
408 Build history is disabled by default.
409 To enable it, add the following statements to the end of your
410 <filename>conf/local.conf</filename> file found in the
411 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
412 <literallayout class='monospaced'>
413 INHERIT += "buildhistory"
414 BUILDHISTORY_COMMIT = "1"
415 </literallayout>
416 Enabling build history as previously described
417 causes the build process to collect build
418 output information and commit it to a local
419 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository.
420 <note>
421 Enabling build history increases your build times slightly,
422 particularly for images, and increases the amount of disk
423 space used during the build.
424 </note>
425 </para>
426
427 <para>
428 You can disable build history by removing the previous statements
429 from your <filename>conf/local.conf</filename> file.
430 However, you should realize that enabling and disabling
431 build history in this manner can change the
432 <filename>do_package</filename> task checksums, which if you
433 are using the OEBasicHash signature generator (the default
434 for many current distro configurations including
435 <filename>DISTRO = "poky"</filename> and
436 <filename>DISTRO = ""</filename>) will result in the packaging
437 tasks being re-run during the subsequent build.
438 </para>
439
440 <para>
441 To disable the build history functionality without causing the
442 packaging tasks to be re-run, add just this statement to your
443 <filename>conf/local.conf</filename> file:
444 <literallayout class='monospaced'>
445 BUILDHISTORY_FEATURES = ""
446 </literallayout>
447 </para>
448 </section>
449
450 <section id='understanding-what-the-build-history-contains'>
451 <title>Understanding What the Build History Contains</title>
452
453 <para>
454 Build history information is kept in
455 <link linkend='var-TMPDIR'><filename>$TMPDIR</filename></link><filename>/buildhistory</filename>
456 in the Build Directory.
457 The following is an example abbreviated listing:
458 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
459 </para>
460
461 <section id='build-history-package-information'>
462 <title>Build History Package Information</title>
463
464 <para>
465 The history for each package contains a text file that has
466 name-value pairs with information about the package.
467 For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename>
468 contains the following:
469 <literallayout class='monospaced'>
470 PV = 1.19.3
471 PR = r3
472 RDEPENDS = update-rc.d eglibc (>= 2.13)
473 RRECOMMENDS = busybox-syslog busybox-udhcpc
474 PKGSIZE = 564701
475 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
476 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
477 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
478 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
479 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
480 </literallayout>
481 Most of these name-value pairs corresponds to variables used
482 to produce the package.
483 The exceptions are <filename>FILELIST</filename>, which is the
484 actual list of files in the package, and
485 <filename>PKGSIZE</filename>, which is the total size of files
486 in the package in bytes.
487 </para>
488
489 <para>
490 There is also a file corresponding to the recipe from which the
491 package came (e.g.
492 <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>):
493 <literallayout class='monospaced'>
494 PV = 1.19.3
495 PR = r3
496 DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \
497 virtual/libc update-rc.d-native
498 PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \
499 busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \
500 busybox-staticdev busybox-locale
501 </literallayout>
502 </para>
503 </section>
504
505 <section id='build-history-image-information'>
506 <title>Build History Image Information</title>
507
508 <para>
509 The files produced for each image are as follows:
510 <itemizedlist>
511 <listitem><para><emphasis>build-id:</emphasis>
512 Human-readable information about the build configuration
513 and metadata source revisions.</para></listitem>
514 <listitem><para><emphasis>*.dot:</emphasis>
515 Dependency graphs for the image that are
516 compatible with <filename>graphviz</filename>.
517 </para></listitem>
518 <listitem><para><emphasis>files-in-image.txt:</emphasis>
519 A list of files in the image with permissions,
520 owner, group, size, and symlink information.
521 </para></listitem>
522 <listitem><para><emphasis>image-info.txt:</emphasis>
523 A text file containing name-value pairs with information
524 about the image.
525 See the following listing example for more information.
526 </para></listitem>
527 <listitem><para><emphasis>installed-package-names.txt:</emphasis>
528 A list of installed packages by name only.</para></listitem>
529 <listitem><para><emphasis>installed-package-sizes.txt:</emphasis>
530 A list of installed packages ordered by size.
531 </para></listitem>
532 <listitem><para><emphasis>installed-packages.txt:</emphasis>
533 A list of installed packages with fuill package
534 filenames.</para></listitem>
535 </itemizedlist>
536 <note>
537 Installed package information is able to be gathered and
538 produced even if package management is disabled for the final
539 image.
540 </note>
541 </para>
542
543 <para>
544 Here is an example of <filename>image-info.txt</filename>:
545 <literallayout class='monospaced'>
546 DISTRO = poky
547 DISTRO_VERSION = 1.1+snapshot-20120207
548 USER_CLASSES = image-mklibs image-prelink
549 IMAGE_CLASSES = image_types
550 IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \
551 package-management ssh-server-dropbear package-management
552 IMAGE_LINGUAS = en-us en-gb
553 IMAGE_INSTALL = task-core-boot task-base-extended
554 BAD_RECOMMENDATIONS =
555 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ;
556 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
557 IMAGESIZE = 171816
558 </literallayout>
559 Other than <filename>IMAGESIZE</filename>, which is the
560 total size of the files in the image in Kbytes, the
561 name-value pairs are variables that may have influenced the
562 content of the image.
563 This information is often useful when you are trying to determine
564 why a change in the package or file listings has occurred.
565 </para>
566 </section>
567
568 <section id='using-build-history-to-gather-image-information-only'>
569 <title>Using Build History to Gather Image Information Only</title>
570
571 <para>
572 As you can see, build history produces image information,
573 including dependency graphs, so you can see why something
574 was pulled into the image.
575 If you are just interested in this information and not
576 interested in collecting history or any package information,
577 you can enable writing only image information without
578 any history by adding the following
579 to your <filename>conf/local.conf</filename> file found in the
580 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
581 <literallayout class='monospaced'>
582 INHERIT += "buildhistory"
583 BUILDHISTORY_COMMIT = "0"
584 BUILDHISTORY_FEATURES = "image"
585 </literallayout>
586 </para>
587 </section>
588
589 <section id='examining-build-history-information'>
590 <title>Examining Build History Information</title>
591
592 <para>
593 You can examine build history output from the command line or
594 from a web interface.
595 </para>
596
597 <para>
598 To see any changes that have occurred (assuming you have
599 <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply
600 use any Git command that allows you to view the history of
601 a repository.
602 Here is one method:
603 <literallayout class='monospaced'>
604 $ git log -p
605 </literallayout>
606 You need to realize, however, that this method does show
607 changes that are not significant (e.g. a package's size
608 changing by a few bytes).
609 </para>
610
611 <para>
612 A command-line tool called <filename>buildhistory-diff</filename>
613 does exist though that queries the Git repository and prints just
614 the differences that might be significant in human-readable form.
615 Here is an example:
616 <literallayout class='monospaced'>
617 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
618 Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt):
619 /etc/anotherpkg.conf was added
620 /sbin/anotherpkg was added
621 * (installed-package-names.txt):
622 * anotherpkg was added
623 Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt):
624 anotherpkg was added
625 packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
626 * PR changed from "r0" to "r1"
627 * PV changed from "0.1.10" to "0.1.12"
628 packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
629 * PR changed from "r0" to "r1"
630 * PV changed from "0.1.10" to "0.1.12"
631 </literallayout>
632 </para>
633
634 <para>
635 To see changes to the build history using a web interface, follow
636 the instruction in the <filename>README</filename> file here.
637 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
638 </para>
639
640 <para>
641 Here is a sample screenshot of the interface:
642 <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
643 </para>
644 </section>
645 </section>
646</section>
647
648</chapter>
649<!--
650vim: expandtab tw=80 ts=4
651-->