poky.conf: Bump version for 3.1.5 release

(From meta-yocto rev: e5c4bf10f870a9f157a94ff940de36b5e18edf00)

Signed-off-by: Steve Sakoman <steve@sakoman.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

bitbake/doc/.gitignore

@@ -0,0 +1 @@
+_build/

bitbake/doc/Makefile

@@ -1,91 +1,35 @@
-# This is a single Makefile to handle all generated BitBake documents.
-# The Makefile needs to live in the documentation directory and all figures used
-# in any manuals must be .PNG files and live in the individual book's figures
-# directory.
-#
-# The Makefile has these targets:
-#
-#    pdf:      generates a PDF version of a manual.
-#    html:     generates an HTML version of a manual.
-#    tarball:  creates a tarball for the doc files.
-#    validate: validates
-#    clean:    removes files
-#
-# The Makefile generates an HTML version of every document.  The
-# variable DOC indicates the folder name for a given manual.
-#
-# To build a manual, you must invoke 'make' with the DOC argument.
-#
-# Examples:
-#
-#     make DOC=bitbake-user-manual
-#     make pdf DOC=bitbake-user-manual
-#
-# The first example generates the HTML version of the User Manual.
-# The second example generates the PDF version of the User Manual.
+# Minimal makefile for Sphinx documentation
 #
 
-ifeq ($(DOC),bitbake-user-manual)
-XSLTOPTS = --stringparam html.stylesheet bitbake-user-manual-style.css \
-           --stringparam  chapter.autolabel 1 \
-           --stringparam  section.autolabel 1 \
-           --stringparam  section.label.includes.component.label 1 \
-           --xinclude
-ALLPREQ = html tarball
-TARFILES = bitbake-user-manual-style.css bitbake-user-manual.html figures/bitbake-title.png
-MANUALS = $(DOC)/$(DOC).html
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+DESTDIR       = final
 
+ifeq ($(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi),0)
+$(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed")
 endif
 
-##
-# These URI should be rewritten by your distribution's xml catalog to
-# match your localy installed XSL stylesheets.
-XSL_BASE_URI  = http://docbook.sourceforge.net/release/xsl/current
-XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-all: $(ALLPREQ)
+.PHONY: help Makefile clean publish
 
-pdf:
-ifeq ($(DOC),bitbake-user-manual)
-	@echo " "
-	@echo "********** Building."$(DOC)
-	@echo " "
-	cd $(DOC); ../tools/docbook-to-pdf $(DOC).xml ../template; cd ..
-endif
-
-html:
-ifeq ($(DOC),bitbake-user-manual)
-#       See http://www.sagehill.net/docbookxsl/HtmlOutput.html
-	@echo " "
-	@echo "******** Building "$(DOC)
-	@echo " "
-	cd $(DOC); xsltproc $(XSLTOPTS) -o $(DOC).html $(DOC)-customization.xsl $(DOC).xml; cd ..
-endif
-
-tarball: html
-	@echo " "
-	@echo "******** Creating Tarball of document files"
-	@echo " "
-	cd $(DOC); tar -cvzf $(DOC).tgz $(TARFILES); cd ..
-
-validate:
-	cd $(DOC); xmllint --postvalid --xinclude --noout $(DOC).xml; cd ..
-
-publish:
-	@if test -f $(DOC)/$(DOC).html; \
-	  then \
-            echo " "; \
-            echo "******** Publishing "$(DOC)".html"; \
-            echo " "; \
-            scp -r $(MANUALS) $(STYLESHEET) docs.yp:/var/www/www.yoctoproject.org-docs/$(VER)/$(DOC); \
-            cd $(DOC); scp -r $(FIGURES) docs.yp:/var/www/www.yoctoproject.org-docs/$(VER)/$(DOC); \
-	else \
-          echo " "; \
-          echo $(DOC)".html missing.  Generate the file first then try again."; \
-          echo " "; \
-	fi
+publish: Makefile html singlehtml
+	rm -rf $(BUILDDIR)/$(DESTDIR)/
+	mkdir -p $(BUILDDIR)/$(DESTDIR)/
+	cp -r $(BUILDDIR)/html/* $(BUILDDIR)/$(DESTDIR)/
+	cp $(BUILDDIR)/singlehtml/index.html $(BUILDDIR)/$(DESTDIR)/singleindex.html
+	sed -i -e 's@index.html#@singleindex.html#@g' $(BUILDDIR)/$(DESTDIR)/singleindex.html
 
 clean:
-	rm -rf $(MANUALS); rm $(DOC)/$(DOC).tgz;
+	@rm -rf $(BUILDDIR)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

bitbake/doc/README

@@ -15,25 +15,41 @@ Each folder is self-contained regarding content and figures.
 If you want to find HTML versions of the BitBake manuals on the web, 
 go to http://www.openembedded.org/wiki/Documentation. 
 
-Makefile
-========
+Sphinx
+======
 
-The Makefile processes manual directories to create HTML, PDF,
-tarballs, etc.  Details on how the Makefile work are documented
-inside the Makefile.  See that file for more information.
+The BitBake documentation was migrated from the original DocBook
+format to Sphinx based documentation for the Yocto Project 3.2
+release.
 
-To build a manual, you run the make command and pass it the name
-of the folder containing the manual's contents. 
-For example, the following command run from the documentation directory 
-creates an HTML and a PDF version of the BitBake User Manual.
-The DOC variable specifies the manual you are making:
+Additional information related to the Sphinx migration, and guidelines
+for developers willing to contribute to the BitBake documentation can
+be found in the Yocto Project Documentation README file:
 
-     $ make DOC=bitbake-user-manual
+https://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/tree/documentation/README
 
-template
-========
-Contains various templates, fonts, and some old PNG files.
+How to build the Yocto Project documentation
+============================================
 
-tools
-=====
-Contains a tool to convert the DocBook files to PDF format.
+Sphinx is written in Python. While it might work with Python2, for
+obvious reasons, we will only support building the BitBake
+documentation with Python3.
+
+Sphinx might be available in your Linux distro packages repositories,
+however it is not recommend using distro packages, as they might be
+old versions, especially if you are using an LTS version of your
+distro. The recommended method to install Sphinx and all required
+dependencies is to use the Python Package Index (pip).
+
+To install all required packages run:
+
+ $ pip3 install sphinx sphinx_rtd_theme pyyaml
+
+To build the documentation locally, run:
+
+ $ cd documentation
+ $ make html
+
+The resulting HTML index page will be _build/html/index.html, and you
+can browse your own copy of the locally generated documentation with
+your browser.

bitbake/doc/_templates/breadcrumbs.html

@@ -0,0 +1,14 @@
+{% extends "!breadcrumbs.html" %}
+
+{% block breadcrumbs %}
+    <li>
+      <span class="doctype_switcher_placeholder">{{ doctype or 'single' }}</span>
+      <span class="version_switcher_placeholder">{{ release }}</span>
+    </li>
+    <li> &raquo;</li>
+    {% for doc in parents %}
+      <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
+    {% endfor %}
+    <li>{{ title }}</li>
+{% endblock %}
+

bitbake/doc/_templates/layout.html

@@ -0,0 +1,7 @@
+{% extends "!layout.html" %}
+
+{% block extrabody %}
+<div id="outdated-warning" style="text-align: center; background-color: #FFBABA; color: #6A0E0E;">
+</div>
+{% endblock %}
+

bitbake/doc/bitbake-user-manual/bitbake-user-manual-customization.xsl

@@ -1,29 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
-
-  <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-<!--
-
-  <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-  <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
-
--->
-
-  <xsl:include href="../template/permalinks.xsl"/>
-  <xsl:include href="../template/section.title.xsl"/>
-  <xsl:include href="../template/component.title.xsl"/>
-  <xsl:include href="../template/division.title.xsl"/>
-  <xsl:include href="../template/formal.object.heading.xsl"/>
-  <xsl:include href="../template/gloss-permalinks.xsl"/>
-
-  <xsl:param name="html.stylesheet" select="'user-manual-style.css'" />
-  <xsl:param name="chapter.autolabel" select="1" />
-  <xsl:param name="section.autolabel" select="1" />
-  <xsl:param name="section.label.includes.component.label" select="1" />
-  <xsl:param name="appendix.autolabel">A</xsl:param>
-
-<!--  <xsl:param name="generate.toc" select="'article nop'"></xsl:param>  -->
-
-</xsl:stylesheet>

bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst

@@ -0,0 +1,733 @@
+.. SPDX-License-Identifier: CC-BY-2.5
+
+=========
+Execution
+=========
+
+|
+
+The primary purpose for running BitBake is to produce some kind of
+output such as a single installable package, a kernel, a software
+development kit, or even a full, board-specific bootable Linux image,
+complete with bootloader, kernel, and root filesystem. Of course, you
+can execute the ``bitbake`` command with options that cause it to
+execute single tasks, compile single recipe files, capture or clear
+data, or simply return information about the execution environment.
+
+This chapter describes BitBake's execution process from start to finish
+when you use it to create an image. The execution process is launched
+using the following command form: ::
+
+  $ bitbake target
+
+For information on
+the BitBake command and its options, see ":ref:`The BitBake Command
+<bitbake-user-manual-command>`" section.
+
+.. note::
+
+   Prior to executing BitBake, you should take advantage of available
+   parallel thread execution on your build host by setting the
+   :term:`BB_NUMBER_THREADS` variable in
+   your project's ``local.conf`` configuration file.
+
+   A common method to determine this value for your build host is to run
+   the following: ::
+
+     $ grep processor /proc/cpuinfo
+
+   This command returns
+   the number of processors, which takes into account hyper-threading.
+   Thus, a quad-core build host with hyper-threading most likely shows
+   eight processors, which is the value you would then assign to
+   ``BB_NUMBER_THREADS``.
+
+   A possibly simpler solution is that some Linux distributions (e.g.
+   Debian and Ubuntu) provide the ``ncpus`` command.
+
+Parsing the Base Configuration Metadata
+=======================================
+
+The first thing BitBake does is parse base configuration metadata. Base
+configuration metadata consists of your project's ``bblayers.conf`` file
+to determine what layers BitBake needs to recognize, all necessary
+``layer.conf`` files (one from each layer), and ``bitbake.conf``. The
+data itself is of various types:
+
+-  **Recipes:** Details about particular pieces of software.
+
+-  **Class Data:** An abstraction of common build information (e.g. how to
+   build a Linux kernel).
+
+-  **Configuration Data:** Machine-specific settings, policy decisions,
+   and so forth. Configuration data acts as the glue to bind everything
+   together.
+
+The ``layer.conf`` files are used to construct key variables such as
+:term:`BBPATH` and :term:`BBFILES`.
+``BBPATH`` is used to search for configuration and class files under the
+``conf`` and ``classes`` directories, respectively. ``BBFILES`` is used
+to locate both recipe and recipe append files (``.bb`` and
+``.bbappend``). If there is no ``bblayers.conf`` file, it is assumed the
+user has set the ``BBPATH`` and ``BBFILES`` directly in the environment.
+
+Next, the ``bitbake.conf`` file is located using the ``BBPATH`` variable
+that was just constructed. The ``bitbake.conf`` file may also include
+other configuration files using the ``include`` or ``require``
+directives.
+
+Prior to parsing configuration files, BitBake looks at certain
+variables, including:
+
+-  :term:`BB_ENV_WHITELIST`
+-  :term:`BB_ENV_EXTRAWHITE`
+-  :term:`BB_PRESERVE_ENV`
+-  :term:`BB_ORIGENV`
+-  :term:`BITBAKE_UI`
+
+The first four variables in this list relate to how BitBake treats shell
+environment variables during task execution. By default, BitBake cleans
+the environment variables and provides tight control over the shell
+execution environment. However, through the use of these first four
+variables, you can apply your control regarding the environment
+variables allowed to be used by BitBake in the shell during execution of
+tasks. See the
+":ref:`bitbake-user-manual/bitbake-user-manual-metadata:Passing Information Into the Build Task Environment`"
+section and the information about these variables in the variable
+glossary for more information on how they work and on how to use them.
+
+The base configuration metadata is global and therefore affects all
+recipes and tasks that are executed.
+
+BitBake first searches the current working directory for an optional
+``conf/bblayers.conf`` configuration file. This file is expected to
+contain a :term:`BBLAYERS` variable that is a
+space-delimited list of 'layer' directories. Recall that if BitBake
+cannot find a ``bblayers.conf`` file, then it is assumed the user has
+set the ``BBPATH`` and ``BBFILES`` variables directly in the
+environment.
+
+For each directory (layer) in this list, a ``conf/layer.conf`` file is
+located and parsed with the :term:`LAYERDIR` variable
+being set to the directory where the layer was found. The idea is these
+files automatically set up :term:`BBPATH` and other
+variables correctly for a given build directory.
+
+BitBake then expects to find the ``conf/bitbake.conf`` file somewhere in
+the user-specified ``BBPATH``. That configuration file generally has
+include directives to pull in any other metadata such as files specific
+to the architecture, the machine, the local environment, and so forth.
+
+Only variable definitions and include directives are allowed in BitBake
+``.conf`` files. Some variables directly influence BitBake's behavior.
+These variables might have been set from the environment depending on
+the environment variables previously mentioned or set in the
+configuration files. The ":ref:`bitbake-user-manual/bitbake-user-manual-ref-variables:Variables Glossary`"
+chapter presents a full list of
+variables.
+
+After parsing configuration files, BitBake uses its rudimentary
+inheritance mechanism, which is through class files, to inherit some
+standard classes. BitBake parses a class when the inherit directive
+responsible for getting that class is encountered.
+
+The ``base.bbclass`` file is always included. Other classes that are
+specified in the configuration using the
+:term:`INHERIT` variable are also included. BitBake
+searches for class files in a ``classes`` subdirectory under the paths
+in ``BBPATH`` in the same way as configuration files.
+
+A good way to get an idea of the configuration files and the class files
+used in your execution environment is to run the following BitBake
+command: ::
+
+  $ bitbake -e > mybb.log
+
+Examining the top of the ``mybb.log``
+shows you the many configuration files and class files used in your
+execution environment.
+
+.. note::
+
+   You need to be aware of how BitBake parses curly braces. If a recipe
+   uses a closing curly brace within the function and the character has
+   no leading spaces, BitBake produces a parsing error. If you use a
+   pair of curly braces in a shell function, the closing curly brace
+   must not be located at the start of the line without leading spaces.
+
+   Here is an example that causes BitBake to produce a parsing error: ::
+
+      fakeroot create_shar() {
+         cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
+      usage()
+      {
+         echo "test"
+         ######  The following "}" at the start of the line causes a parsing error ######
+      }
+      EOF
+      }
+
+      Writing the recipe this way avoids the error:
+      fakeroot create_shar() {
+         cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
+      usage()
+      {
+         echo "test"
+         ###### The following "}" with a leading space at the start of the line avoids the error ######
+       }
+      EOF
+      }
+
+Locating and Parsing Recipes
+============================
+
+During the configuration phase, BitBake will have set
+:term:`BBFILES`. BitBake now uses it to construct a
+list of recipes to parse, along with any append files (``.bbappend``) to
+apply. ``BBFILES`` is a space-separated list of available files and
+supports wildcards. An example would be: ::
+
+  BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend"
+
+BitBake parses each
+recipe and append file located with ``BBFILES`` and stores the values of
+various variables into the datastore.
+
+.. note::
+
+   Append files are applied in the order they are encountered in BBFILES.
+
+For each file, a fresh copy of the base configuration is made, then the
+recipe is parsed line by line. Any inherit statements cause BitBake to
+find and then parse class files (``.bbclass``) using
+:term:`BBPATH` as the search path. Finally, BitBake
+parses in order any append files found in ``BBFILES``.
+
+One common convention is to use the recipe filename to define pieces of
+metadata. For example, in ``bitbake.conf`` the recipe name and version
+are used to set the variables :term:`PN` and
+:term:`PV`: ::
+
+   PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
+   PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
+
+In this example, a recipe called "something_1.2.3.bb" would set
+``PN`` to "something" and ``PV`` to "1.2.3".
+
+By the time parsing is complete for a recipe, BitBake has a list of
+tasks that the recipe defines and a set of data consisting of keys and
+values as well as dependency information about the tasks.
+
+BitBake does not need all of this information. It only needs a small
+subset of the information to make decisions about the recipe.
+Consequently, BitBake caches the values in which it is interested and
+does not store the rest of the information. Experience has shown it is
+faster to re-parse the metadata than to try and write it out to the disk
+and then reload it.
+
+Where possible, subsequent BitBake commands reuse this cache of recipe
+information. The validity of this cache is determined by first computing
+a checksum of the base configuration data (see
+:term:`BB_HASHCONFIG_WHITELIST`) and
+then checking if the checksum matches. If that checksum matches what is
+in the cache and the recipe and class files have not changed, BitBake is
+able to use the cache. BitBake then reloads the cached information about
+the recipe instead of reparsing it from scratch.
+
+Recipe file collections exist to allow the user to have multiple
+repositories of ``.bb`` files that contain the same exact package. For
+example, one could easily use them to make one's own local copy of an
+upstream repository, but with custom modifications that one does not
+want upstream. Here is an example: ::
+
+  BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb"
+  BBFILE_COLLECTIONS = "upstream local"
+  BBFILE_PATTERN_upstream = "^/stuff/openembedded/"
+  BBFILE_PATTERN_local = "^/stuff/openembedded.modified/"
+  BBFILE_PRIORITY_upstream = "5" BBFILE_PRIORITY_local = "10"
+
+.. note::
+
+   The layers mechanism is now the preferred method of collecting code.
+   While the collections code remains, its main use is to set layer
+   priorities and to deal with overlap (conflicts) between layers.
+
+.. _bb-bitbake-providers:
+
+Providers
+=========
+
+Assuming BitBake has been instructed to execute a target and that all
+the recipe files have been parsed, BitBake starts to figure out how to
+build the target. BitBake looks through the ``PROVIDES`` list for each
+of the recipes. A ``PROVIDES`` list is the list of names by which the
+recipe can be known. Each recipe's ``PROVIDES`` list is created
+implicitly through the recipe's :term:`PN` variable and
+explicitly through the recipe's :term:`PROVIDES`
+variable, which is optional.
+
+When a recipe uses ``PROVIDES``, that recipe's functionality can be
+found under an alternative name or names other than the implicit ``PN``
+name. As an example, suppose a recipe named ``keyboard_1.0.bb``
+contained the following: ::
+
+  PROVIDES += "fullkeyboard"
+
+The ``PROVIDES``
+list for this recipe becomes "keyboard", which is implicit, and
+"fullkeyboard", which is explicit. Consequently, the functionality found
+in ``keyboard_1.0.bb`` can be found under two different names.
+
+.. _bb-bitbake-preferences:
+
+Preferences
+===========
+
+The ``PROVIDES`` list is only part of the solution for figuring out a
+target's recipes. Because targets might have multiple providers, BitBake
+needs to prioritize providers by determining provider preferences.
+
+A common example in which a target has multiple providers is
+"virtual/kernel", which is on the ``PROVIDES`` list for each kernel
+recipe. Each machine often selects the best kernel provider by using a
+line similar to the following in the machine configuration file: ::
+
+  PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
+
+The default :term:`PREFERRED_PROVIDER` is the provider
+with the same name as the target. BitBake iterates through each target
+it needs to build and resolves them and their dependencies using this
+process.
+
+Understanding how providers are chosen is made complicated by the fact
+that multiple versions might exist for a given provider. BitBake
+defaults to the highest version of a provider. Version comparisons are
+made using the same method as Debian. You can use the
+:term:`PREFERRED_VERSION` variable to
+specify a particular version. You can influence the order by using the
+:term:`DEFAULT_PREFERENCE` variable.
+
+By default, files have a preference of "0". Setting
+``DEFAULT_PREFERENCE`` to "-1" makes the recipe unlikely to be used
+unless it is explicitly referenced. Setting ``DEFAULT_PREFERENCE`` to
+"1" makes it likely the recipe is used. ``PREFERRED_VERSION`` overrides
+any ``DEFAULT_PREFERENCE`` setting. ``DEFAULT_PREFERENCE`` is often used
+to mark newer and more experimental recipe versions until they have
+undergone sufficient testing to be considered stable.
+
+When there are multiple "versions" of a given recipe, BitBake defaults
+to selecting the most recent version, unless otherwise specified. If the
+recipe in question has a
+:term:`DEFAULT_PREFERENCE` set lower than
+the other recipes (default is 0), then it will not be selected. This
+allows the person or persons maintaining the repository of recipe files
+to specify their preference for the default selected version.
+Additionally, the user can specify their preferred version.
+
+If the first recipe is named ``a_1.1.bb``, then the
+:term:`PN` variable will be set to "a", and the
+:term:`PV` variable will be set to 1.1.
+
+Thus, if a recipe named ``a_1.2.bb`` exists, BitBake will choose 1.2 by
+default. However, if you define the following variable in a ``.conf``
+file that BitBake parses, you can change that preference: ::
+
+  PREFERRED_VERSION_a = "1.1"
+
+.. note::
+
+   It is common for a recipe to provide two versions -- a stable,
+   numbered (and preferred) version, and a version that is automatically
+   checked out from a source code repository that is considered more
+   "bleeding edge" but can be selected only explicitly.
+
+   For example, in the OpenEmbedded codebase, there is a standard,
+   versioned recipe file for BusyBox, ``busybox_1.22.1.bb``, but there
+   is also a Git-based version, ``busybox_git.bb``, which explicitly
+   contains the line ::
+
+     DEFAULT_PREFERENCE = "-1"
+
+   to ensure that the
+   numbered, stable version is always preferred unless the developer
+   selects otherwise.
+
+.. _bb-bitbake-dependencies:
+
+Dependencies
+============
+
+Each target BitBake builds consists of multiple tasks such as ``fetch``,
+``unpack``, ``patch``, ``configure``, and ``compile``. For best
+performance on multi-core systems, BitBake considers each task as an
+independent entity with its own set of dependencies.
+
+Dependencies are defined through several variables. You can find
+information about variables BitBake uses in the
+:doc:`bitbake-user-manual-ref-variables` near the end of this manual. At a
+basic level, it is sufficient to know that BitBake uses the
+:term:`DEPENDS` and
+:term:`RDEPENDS` variables when calculating
+dependencies.
+
+For more information on how BitBake handles dependencies, see the
+:ref:`bitbake-user-manual/bitbake-user-manual-metadata:Dependencies`
+section.
+
+.. _ref-bitbake-tasklist:
+
+The Task List
+=============
+
+Based on the generated list of providers and the dependency information,
+BitBake can now calculate exactly what tasks it needs to run and in what
+order it needs to run them. The
+:ref:`bitbake-user-manual/bitbake-user-manual-execution:executing tasks`
+section has more information on how BitBake chooses which task to
+execute next.
+
+The build now starts with BitBake forking off threads up to the limit
+set in the :term:`BB_NUMBER_THREADS`
+variable. BitBake continues to fork threads as long as there are tasks
+ready to run, those tasks have all their dependencies met, and the
+thread threshold has not been exceeded.
+
+It is worth noting that you can greatly speed up the build time by
+properly setting the ``BB_NUMBER_THREADS`` variable.
+
+As each task completes, a timestamp is written to the directory
+specified by the :term:`STAMP` variable. On subsequent
+runs, BitBake looks in the build directory within ``tmp/stamps`` and
+does not rerun tasks that are already completed unless a timestamp is
+found to be invalid. Currently, invalid timestamps are only considered
+on a per recipe file basis. So, for example, if the configure stamp has
+a timestamp greater than the compile timestamp for a given target, then
+the compile task would rerun. Running the compile task again, however,
+has no effect on other providers that depend on that target.
+
+The exact format of the stamps is partly configurable. In modern
+versions of BitBake, a hash is appended to the stamp so that if the
+configuration changes, the stamp becomes invalid and the task is
+automatically rerun. This hash, or signature used, is governed by the
+signature policy that is configured (see the
+:ref:`bitbake-user-manual/bitbake-user-manual-execution:checksums (signatures)`
+section for information). It is also
+possible to append extra metadata to the stamp using the
+``[stamp-extra-info]`` task flag. For example, OpenEmbedded uses this
+flag to make some tasks machine-specific.
+
+.. note::
+
+   Some tasks are marked as "nostamp" tasks. No timestamp file is
+   created when these tasks are run. Consequently, "nostamp" tasks are
+   always rerun.
+
+For more information on tasks, see the
+:ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks` section.
+
+Executing Tasks
+===============
+
+Tasks can be either a shell task or a Python task. For shell tasks,
+BitBake writes a shell script to
+``${``\ :term:`T`\ ``}/run.do_taskname.pid`` and then
+executes the script. The generated shell script contains all the
+exported variables, and the shell functions with all variables expanded.
+Output from the shell script goes to the file
+``${T}/log.do_taskname.pid``. Looking at the expanded shell functions in
+the run file and the output in the log files is a useful debugging
+technique.
+
+For Python tasks, BitBake executes the task internally and logs
+information to the controlling terminal. Future versions of BitBake will
+write the functions to files similar to the way shell tasks are handled.
+Logging will be handled in a way similar to shell tasks as well.
+
+The order in which BitBake runs the tasks is controlled by its task
+scheduler. It is possible to configure the scheduler and define custom
+implementations for specific use cases. For more information, see these
+variables that control the behavior:
+
+-  :term:`BB_SCHEDULER`
+
+-  :term:`BB_SCHEDULERS`
+
+It is possible to have functions run before and after a task's main
+function. This is done using the ``[prefuncs]`` and ``[postfuncs]``
+flags of the task that lists the functions to run.
+
+.. _checksums:
+
+Checksums (Signatures)
+======================
+
+A checksum is a unique signature of a task's inputs. The signature of a
+task can be used to determine if a task needs to be run. Because it is a
+change in a task's inputs that triggers running the task, BitBake needs
+to detect all the inputs to a given task. For shell tasks, this turns
+out to be fairly easy because BitBake generates a "run" shell script for
+each task and it is possible to create a checksum that gives you a good
+idea of when the task's data changes.
+
+To complicate the problem, some things should not be included in the
+checksum. First, there is the actual specific build path of a given task
+- the working directory. It does not matter if the working directory
+changes because it should not affect the output for target packages. The
+simplistic approach for excluding the working directory is to set it to
+some fixed value and create the checksum for the "run" script. BitBake
+goes one step better and uses the
+:term:`BB_HASHBASE_WHITELIST` variable
+to define a list of variables that should never be included when
+generating the signatures.
+
+Another problem results from the "run" scripts containing functions that
+might or might not get called. The incremental build solution contains
+code that figures out dependencies between shell functions. This code is
+used to prune the "run" scripts down to the minimum set, thereby
+alleviating this problem and making the "run" scripts much more readable
+as a bonus.
+
+So far we have solutions for shell scripts. What about Python tasks? The
+same approach applies even though these tasks are more difficult. The
+process needs to figure out what variables a Python function accesses
+and what functions it calls. Again, the incremental build solution
+contains code that first figures out the variable and function
+dependencies, and then creates a checksum for the data used as the input
+to the task.
+
+Like the working directory case, situations exist where dependencies
+should be ignored. For these cases, you can instruct the build process
+to ignore a dependency by using a line like the following: ::
+
+  PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
+
+This example ensures that the
+``PACKAGE_ARCHS`` variable does not depend on the value of ``MACHINE``,
+even if it does reference it.
+
+Equally, there are cases where we need to add dependencies BitBake is
+not able to find. You can accomplish this by using a line like the
+following: ::
+
+  PACKAGE_ARCHS[vardeps] = "MACHINE"
+
+This example explicitly
+adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``.
+
+Consider a case with in-line Python, for example, where BitBake is not
+able to figure out dependencies. When running in debug mode (i.e. using
+``-DDD``), BitBake produces output when it discovers something for which
+it cannot figure out dependencies.
+
+Thus far, this section has limited discussion to the direct inputs into
+a task. Information based on direct inputs is referred to as the
+"basehash" in the code. However, there is still the question of a task's
+indirect inputs - the things that were already built and present in the
+build directory. The checksum (or signature) for a particular task needs
+to add the hashes of all the tasks on which the particular task depends.
+Choosing which dependencies to add is a policy decision. However, the
+effect is to generate a master checksum that combines the basehash and
+the hashes of the task's dependencies.
+
+At the code level, there are a variety of ways both the basehash and the
+dependent task hashes can be influenced. Within the BitBake
+configuration file, we can give BitBake some extra information to help
+it construct the basehash. The following statement effectively results
+in a list of global variable dependency excludes - variables never
+included in any checksum. This example uses variables from OpenEmbedded
+to help illustrate the concept: ::
+
+   BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
+       SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
+       USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
+       PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
+       CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
+
+The previous example excludes the work directory, which is part of
+``TMPDIR``.
+
+The rules for deciding which hashes of dependent tasks to include
+through dependency chains are more complex and are generally
+accomplished with a Python function. The code in
+``meta/lib/oe/sstatesig.py`` shows two examples of this and also
+illustrates how you can insert your own policy into the system if so
+desired. This file defines the two basic signature generators
+OpenEmbedded-Core uses: "OEBasic" and "OEBasicHash". By default, there
+is a dummy "noop" signature handler enabled in BitBake. This means that
+behavior is unchanged from previous versions. ``OE-Core`` uses the
+"OEBasicHash" signature handler by default through this setting in the
+``bitbake.conf`` file: ::
+
+  BB_SIGNATURE_HANDLER ?= "OEBasicHash"
+
+The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same as the "OEBasic"
+version but adds the task hash to the stamp files. This results in any
+metadata change that changes the task hash, automatically causing the
+task to be run again. This removes the need to bump
+:term:`PR` values, and changes to metadata automatically
+ripple across the build.
+
+It is also worth noting that the end result of these signature
+generators is to make some dependency and hash information available to
+the build. This information includes:
+
+-  ``BB_BASEHASH_task-``\ *taskname*: The base hashes for each task in the
+   recipe.
+
+-  ``BB_BASEHASH_``\ *filename:taskname*: The base hashes for each
+   dependent task.
+
+-  ``BBHASHDEPS_``\ *filename:taskname*: The task dependencies for
+   each task.
+
+-  ``BB_TASKHASH``: The hash of the currently running task.
+
+It is worth noting that BitBake's "-S" option lets you debug BitBake's
+processing of signatures. The options passed to -S allow different
+debugging modes to be used, either using BitBake's own debug functions
+or possibly those defined in the metadata/signature handler itself. The
+simplest parameter to pass is "none", which causes a set of signature
+information to be written out into ``STAMPS_DIR`` corresponding to the
+targets specified. The other currently available parameter is
+"printdiff", which causes BitBake to try to establish the closest
+signature match it can (e.g. in the sstate cache) and then run
+``bitbake-diffsigs`` over the matches to determine the stamps and delta
+where these two stamp trees diverge.
+
+.. note::
+
+   It is likely that future versions of BitBake will provide other
+   signature handlers triggered through additional "-S" parameters.
+
+You can find more information on checksum metadata in the
+:ref:`bitbake-user-manual/bitbake-user-manual-metadata:task checksums and setscene`
+section.
+
+Setscene
+========
+
+The setscene process enables BitBake to handle "pre-built" artifacts.
+The ability to handle and reuse these artifacts allows BitBake the
+luxury of not having to build something from scratch every time.
+Instead, BitBake can use, when possible, existing build artifacts.
+
+BitBake needs to have reliable data indicating whether or not an
+artifact is compatible. Signatures, described in the previous section,
+provide an ideal way of representing whether an artifact is compatible.
+If a signature is the same, an object can be reused.
+
+If an object can be reused, the problem then becomes how to replace a
+given task or set of tasks with the pre-built artifact. BitBake solves
+the problem with the "setscene" process.
+
+When BitBake is asked to build a given target, before building anything,
+it first asks whether cached information is available for any of the
+targets it's building, or any of the intermediate targets. If cached
+information is available, BitBake uses this information instead of
+running the main tasks.
+
+BitBake first calls the function defined by the
+:term:`BB_HASHCHECK_FUNCTION` variable
+with a list of tasks and corresponding hashes it wants to build. This
+function is designed to be fast and returns a list of the tasks for
+which it believes in can obtain artifacts.
+
+Next, for each of the tasks that were returned as possibilities, BitBake
+executes a setscene version of the task that the possible artifact
+covers. Setscene versions of a task have the string "_setscene" appended
+to the task name. So, for example, the task with the name ``xxx`` has a
+setscene task named ``xxx_setscene``. The setscene version of the task
+executes and provides the necessary artifacts returning either success
+or failure.
+
+As previously mentioned, an artifact can cover more than one task. For
+example, it is pointless to obtain a compiler if you already have the
+compiled binary. To handle this, BitBake calls the
+:term:`BB_SETSCENE_DEPVALID` function for
+each successful setscene task to know whether or not it needs to obtain
+the dependencies of that task.
+
+Finally, after all the setscene tasks have executed, BitBake calls the
+function listed in
+:term:`BB_SETSCENE_VERIFY_FUNCTION2`
+with the list of tasks BitBake thinks has been "covered". The metadata
+can then ensure that this list is correct and can inform BitBake that it
+wants specific tasks to be run regardless of the setscene result.
+
+You can find more information on setscene metadata in the
+:ref:`bitbake-user-manual/bitbake-user-manual-metadata:task checksums and setscene`
+section.
+
+Logging
+=======
+
+In addition to the standard command line option to control how verbose
+builds are when execute, bitbake also supports user defined
+configuration of the `Python
+logging <https://docs.python.org/3/library/logging.html>`__ facilities
+through the :term:`BB_LOGCONFIG` variable. This
+variable defines a json or yaml `logging
+configuration <https://docs.python.org/3/library/logging.config.html>`__
+that will be intelligently merged into the default configuration. The
+logging configuration is merged using the following rules:
+
+-  The user defined configuration will completely replace the default
+   configuration if top level key ``bitbake_merge`` is set to the value
+   ``False``. In this case, all other rules are ignored.
+
+-  The user configuration must have a top level ``version`` which must
+   match the value of the default configuration.
+
+-  Any keys defined in the ``handlers``, ``formatters``, or ``filters``,
+   will be merged into the same section in the default configuration,
+   with the user specified keys taking replacing a default one if there
+   is a conflict. In practice, this means that if both the default
+   configuration and user configuration specify a handler named
+   ``myhandler``, the user defined one will replace the default. To
+   prevent the user from inadvertently replacing a default handler,
+   formatter, or filter, all of the default ones are named with a prefix
+   of "``BitBake.``"
+
+-  If a logger is defined by the user with the key ``bitbake_merge`` set
+   to ``False``, that logger will be completely replaced by user
+   configuration. In this case, no other rules will apply to that
+   logger.
+
+-  All user defined ``filter`` and ``handlers`` properties for a given
+   logger will be merged with corresponding properties from the default
+   logger. For example, if the user configuration adds a filter called
+   ``myFilter`` to the ``BitBake.SigGen``, and the default configuration
+   adds a filter called ``BitBake.defaultFilter``, both filters will be
+   applied to the logger
+
+As an example, consider the following user logging configuration file
+which logs all Hash Equivalence related messages of VERBOSE or higher to
+a file called ``hashequiv.log`` ::
+
+   {
+       "version": 1,
+       "handlers": {
+           "autobuilderlog": {
+               "class": "logging.FileHandler",
+               "formatter": "logfileFormatter",
+               "level": "DEBUG",
+               "filename": "hashequiv.log",
+               "mode": "w"
+           }
+       },
+       "formatters": {
+               "logfileFormatter": {
+                   "format": "%(name)s: %(levelname)s: %(message)s"
+               }
+       },
+       "loggers": {
+           "BitBake.SigGen.HashEquiv": {
+               "level": "VERBOSE",
+               "handlers": ["autobuilderlog"]
+           },
+           "BitBake.RunQueue.HashEquiv": {
+               "level": "VERBOSE",
+               "handlers": ["autobuilderlog"]
+           }
+       }
+   }

bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst

@@ -0,0 +1,621 @@
+.. SPDX-License-Identifier: CC-BY-2.5
+
+=====================
+File Download Support
+=====================
+
+|
+
+BitBake's fetch module is a standalone piece of library code that deals
+with the intricacies of downloading source code and files from remote
+systems. Fetching source code is one of the cornerstones of building
+software. As such, this module forms an important part of BitBake.
+
+The current fetch module is called "fetch2" and refers to the fact that
+it is the second major version of the API. The original version is
+obsolete and has been removed from the codebase. Thus, in all cases,
+"fetch" refers to "fetch2" in this manual.
+
+The Download (Fetch)
+====================
+
+BitBake takes several steps when fetching source code or files. The
+fetcher codebase deals with two distinct processes in order: obtaining
+the files from somewhere (cached or otherwise) and then unpacking those
+files into a specific location and perhaps in a specific way. Getting
+and unpacking the files is often optionally followed by patching.
+Patching, however, is not covered by this module.
+
+The code to execute the first part of this process, a fetch, looks
+something like the following: ::
+
+   src_uri = (d.getVar('SRC_URI') or "").split()
+   fetcher = bb.fetch2.Fetch(src_uri, d)
+   fetcher.download()
+
+This code sets up an instance of the fetch class. The instance uses a
+space-separated list of URLs from the :term:`SRC_URI`
+variable and then calls the ``download`` method to download the files.
+
+The instantiation of the fetch class is usually followed by: ::
+
+   rootdir = l.getVar('WORKDIR')
+   fetcher.unpack(rootdir)
+
+This code unpacks the downloaded files to the specified by ``WORKDIR``.
+
+.. note::
+
+   For convenience, the naming in these examples matches the variables
+   used by OpenEmbedded. If you want to see the above code in action,
+   examine the OpenEmbedded class file ``base.bbclass``
+   .
+
+The ``SRC_URI`` and ``WORKDIR`` variables are not hardcoded into the
+fetcher, since those fetcher methods can be (and are) called with
+different variable names. In OpenEmbedded for example, the shared state
+(sstate) code uses the fetch module to fetch the sstate files.
+
+When the ``download()`` method is called, BitBake tries to resolve the
+URLs by looking for source files in a specific search order:
+
+-  *Pre-mirror Sites:* BitBake first uses pre-mirrors to try and find
+   source files. These locations are defined using the
+   :term:`PREMIRRORS` variable.
+
+-  *Source URI:* If pre-mirrors fail, BitBake uses the original URL (e.g
+   from ``SRC_URI``).
+
+-  *Mirror Sites:* If fetch failures occur, BitBake next uses mirror
+   locations as defined by the :term:`MIRRORS` variable.
+
+For each URL passed to the fetcher, the fetcher calls the submodule that
+handles that particular URL type. This behavior can be the source of
+some confusion when you are providing URLs for the ``SRC_URI`` variable.
+Consider the following two URLs: ::
+
+   http://git.yoctoproject.org/git/poky;protocol=git
+   git://git.yoctoproject.org/git/poky;protocol=http
+
+In the former case, the URL is passed to the ``wget`` fetcher, which does not
+understand "git". Therefore, the latter case is the correct form since the Git
+fetcher does know how to use HTTP as a transport.
+
+Here are some examples that show commonly used mirror definitions: ::
+
+   PREMIRRORS ?= "\
+      bzr://.*/.\*  http://somemirror.org/sources/ \\n \
+      cvs://.*/.\*  http://somemirror.org/sources/ \\n \
+      git://.*/.\*  http://somemirror.org/sources/ \\n \
+      hg://.*/.\*   http://somemirror.org/sources/ \\n \
+      osc://.*/.\*  http://somemirror.org/sources/ \\n \
+      p4://.*/.\*   http://somemirror.org/sources/ \\n \
+     svn://.*/.\*   http://somemirror.org/sources/ \\n"
+
+   MIRRORS =+ "\
+      ftp://.*/.\*   http://somemirror.org/sources/ \\n \
+      http://.*/.\*  http://somemirror.org/sources/ \\n \
+      https://.*/.\* http://somemirror.org/sources/ \\n"
+
+It is useful to note that BitBake
+supports cross-URLs. It is possible to mirror a Git repository on an
+HTTP server as a tarball. This is what the ``git://`` mapping in the
+previous example does.
+
+Since network accesses are slow, BitBake maintains a cache of files
+downloaded from the network. Any source files that are not local (i.e.
+downloaded from the Internet) are placed into the download directory,
+which is specified by the :term:`DL_DIR` variable.
+
+File integrity is of key importance for reproducing builds. For
+non-local archive downloads, the fetcher code can verify SHA-256 and MD5
+checksums to ensure the archives have been downloaded correctly. You can
+specify these checksums by using the ``SRC_URI`` variable with the
+appropriate varflags as follows: ::
+
+   SRC_URI[md5sum] = "value"
+   SRC_URI[sha256sum] = "value"
+
+You can also specify the checksums as
+parameters on the ``SRC_URI`` as shown below: ::
+
+  SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
+
+If multiple URIs exist, you can specify the checksums either directly as
+in the previous example, or you can name the URLs. The following syntax
+shows how you name the URIs: ::
+
+   SRC_URI = "http://example.com/foobar.tar.bz2;name=foo"
+   SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d
+
+After a file has been downloaded and
+has had its checksum checked, a ".done" stamp is placed in ``DL_DIR``.
+BitBake uses this stamp during subsequent builds to avoid downloading or
+comparing a checksum for the file again.
+
+.. note::
+
+   It is assumed that local storage is safe from data corruption. If
+   this were not the case, there would be bigger issues to worry about.
+
+If :term:`BB_STRICT_CHECKSUM` is set, any
+download without a checksum triggers an error message. The
+:term:`BB_NO_NETWORK` variable can be used to
+make any attempted network access a fatal error, which is useful for
+checking that mirrors are complete as well as other things.
+
+.. _bb-the-unpack:
+
+The Unpack
+==========
+
+The unpack process usually immediately follows the download. For all
+URLs except Git URLs, BitBake uses the common ``unpack`` method.
+
+A number of parameters exist that you can specify within the URL to
+govern the behavior of the unpack stage:
+
+-  *unpack:* Controls whether the URL components are unpacked. If set to
+   "1", which is the default, the components are unpacked. If set to
+   "0", the unpack stage leaves the file alone. This parameter is useful
+   when you want an archive to be copied in and not be unpacked.
+
+-  *dos:* Applies to ``.zip`` and ``.jar`` files and specifies whether
+   to use DOS line ending conversion on text files.
+
+-  *basepath:* Instructs the unpack stage to strip the specified
+   directories from the source path when unpacking.
+
+-  *subdir:* Unpacks the specific URL to the specified subdirectory
+   within the root directory.
+
+The unpack call automatically decompresses and extracts files with ".Z",
+".z", ".gz", ".xz", ".zip", ".jar", ".ipk", ".rpm". ".srpm", ".deb" and
+".bz2" extensions as well as various combinations of tarball extensions.
+
+As mentioned, the Git fetcher has its own unpack method that is
+optimized to work with Git trees. Basically, this method works by
+cloning the tree into the final directory. The process is completed
+using references so that there is only one central copy of the Git
+metadata needed.
+
+.. _bb-fetchers:
+
+Fetchers
+========
+
+As mentioned earlier, the URL prefix determines which fetcher submodule
+BitBake uses. Each submodule can support different URL parameters, which
+are described in the following sections.
+
+.. _local-file-fetcher:
+
+Local file fetcher (``file://``)
+--------------------------------
+
+This submodule handles URLs that begin with ``file://``. The filename
+you specify within the URL can be either an absolute or relative path to
+a file. If the filename is relative, the contents of the
+:term:`FILESPATH` variable is used in the same way
+``PATH`` is used to find executables. If the file cannot be found, it is
+assumed that it is available in :term:`DL_DIR` by the
+time the ``download()`` method is called.
+
+If you specify a directory, the entire directory is unpacked.
+
+Here are a couple of example URLs, the first relative and the second
+absolute: ::
+
+   SRC_URI = "file://relativefile.patch"
+   SRC_URI = "file:///Users/ich/very_important_software"
+
+.. _http-ftp-fetcher:
+
+HTTP/FTP wget fetcher (``http://``, ``ftp://``, ``https://``)
+-------------------------------------------------------------
+
+This fetcher obtains files from web and FTP servers. Internally, the
+fetcher uses the wget utility.
+
+The executable and parameters used are specified by the
+``FETCHCMD_wget`` variable, which defaults to sensible values. The
+fetcher supports a parameter "downloadfilename" that allows the name of
+the downloaded file to be specified. Specifying the name of the
+downloaded file is useful for avoiding collisions in
+:term:`DL_DIR` when dealing with multiple files that
+have the same name.
+
+Some example URLs are as follows: ::
+
+   SRC_URI = "http://oe.handhelds.org/not_there.aac"
+   SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac"
+   SRC_URI = "ftp://you@oe.handhelds.org/home/you/secret.plan"
+
+.. note::
+
+   Because URL parameters are delimited by semi-colons, this can
+   introduce ambiguity when parsing URLs that also contain semi-colons,
+   for example:
+   ::
+
+           SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47"
+
+
+   Such URLs should should be modified by replacing semi-colons with '&'
+   characters:
+   ::
+
+           SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47"
+
+
+   In most cases this should work. Treating semi-colons and '&' in
+   queries identically is recommended by the World Wide Web Consortium
+   (W3C). Note that due to the nature of the URL, you may have to
+   specify the name of the downloaded file as well:
+   ::
+
+           SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2"
+
+
+.. _cvs-fetcher:
+
+CVS fetcher (``(cvs://``)
+-------------------------
+
+This submodule handles checking out files from the CVS version control
+system. You can configure it using a number of different variables:
+
+-  :term:`FETCHCMD_cvs <FETCHCMD>`: The name of the executable to use when running
+   the ``cvs`` command. This name is usually "cvs".
+
+-  :term:`SRCDATE`: The date to use when fetching the CVS source code. A
+   special value of "now" causes the checkout to be updated on every
+   build.
+
+-  :term:`CVSDIR`: Specifies where a temporary
+   checkout is saved. The location is often ``DL_DIR/cvs``.
+
+-  CVS_PROXY_HOST: The name to use as a "proxy=" parameter to the
+   ``cvs`` command.
+
+-  CVS_PROXY_PORT: The port number to use as a "proxyport="
+   parameter to the ``cvs`` command.
+
+As well as the standard username and password URL syntax, you can also
+configure the fetcher with various URL parameters:
+
+The supported parameters are as follows:
+
+-  *"method":* The protocol over which to communicate with the CVS
+   server. By default, this protocol is "pserver". If "method" is set to
+   "ext", BitBake examines the "rsh" parameter and sets ``CVS_RSH``. You
+   can use "dir" for local directories.
+
+-  *"module":* Specifies the module to check out. You must supply this
+   parameter.
+
+-  *"tag":* Describes which CVS TAG should be used for the checkout. By
+   default, the TAG is empty.
+
+-  *"date":* Specifies a date. If no "date" is specified, the
+   :term:`SRCDATE` of the configuration is used to
+   checkout a specific date. The special value of "now" causes the
+   checkout to be updated on every build.
+
+-  *"localdir":* Used to rename the module. Effectively, you are
+   renaming the output directory to which the module is unpacked. You
+   are forcing the module into a special directory relative to
+   :term:`CVSDIR`.
+
+-  *"rsh":* Used in conjunction with the "method" parameter.
+
+-  *"scmdata":* Causes the CVS metadata to be maintained in the tarball
+   the fetcher creates when set to "keep". The tarball is expanded into
+   the work directory. By default, the CVS metadata is removed.
+
+-  *"fullpath":* Controls whether the resulting checkout is at the
+   module level, which is the default, or is at deeper paths.
+
+-  *"norecurse":* Causes the fetcher to only checkout the specified
+   directory with no recurse into any subdirectories.
+
+-  *"port":* The port to which the CVS server connects.
+
+Some example URLs are as follows: ::
+
+   SRC_URI = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
+   SRC_URI = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
+
+.. _svn-fetcher:
+
+Subversion (SVN) Fetcher (``svn://``)
+-------------------------------------
+
+This fetcher submodule fetches code from the Subversion source control
+system. The executable used is specified by ``FETCHCMD_svn``, which
+defaults to "svn". The fetcher's temporary working directory is set by
+:term:`SVNDIR`, which is usually ``DL_DIR/svn``.
+
+The supported parameters are as follows:
+
+-  *"module":* The name of the svn module to checkout. You must provide
+   this parameter. You can think of this parameter as the top-level
+   directory of the repository data you want.
+
+-  *"path_spec":* A specific directory in which to checkout the
+   specified svn module.
+
+-  *"protocol":* The protocol to use, which defaults to "svn". If
+   "protocol" is set to "svn+ssh", the "ssh" parameter is also used.
+
+-  *"rev":* The revision of the source code to checkout.
+
+-  *"scmdata":* Causes the ".svn" directories to be available during
+   compile-time when set to "keep". By default, these directories are
+   removed.
+
+-  *"ssh":* An optional parameter used when "protocol" is set to
+   "svn+ssh". You can use this parameter to specify the ssh program used
+   by svn.
+
+-  *"transportuser":* When required, sets the username for the
+   transport. By default, this parameter is empty. The transport
+   username is different than the username used in the main URL, which
+   is passed to the subversion command.
+
+Following are three examples using svn: ::
+
+   SRC_URI = "svn://myrepos/proj1;module=vip;protocol=http;rev=667"
+   SRC_URI = "svn://myrepos/proj1;module=opie;protocol=svn+ssh"
+   SRC_URI = "svn://myrepos/proj1;module=trunk;protocol=http;path_spec=${MY_DIR}/proj1"
+
+.. _git-fetcher:
+
+Git Fetcher (``git://``)
+------------------------
+
+This fetcher submodule fetches code from the Git source control system.
+The fetcher works by creating a bare clone of the remote into
+:term:`GITDIR`, which is usually ``DL_DIR/git2``. This
+bare clone is then cloned into the work directory during the unpack
+stage when a specific tree is checked out. This is done using alternates
+and by reference to minimize the amount of duplicate data on the disk
+and make the unpack process fast. The executable used can be set with
+``FETCHCMD_git``.
+
+This fetcher supports the following parameters:
+
+-  *"protocol":* The protocol used to fetch the files. The default is
+   "git" when a hostname is set. If a hostname is not set, the Git
+   protocol is "file". You can also use "http", "https", "ssh" and
+   "rsync".
+
+-  *"nocheckout":* Tells the fetcher to not checkout source code when
+   unpacking when set to "1". Set this option for the URL where there is
+   a custom routine to checkout code. The default is "0".
+
+-  *"rebaseable":* Indicates that the upstream Git repository can be
+   rebased. You should set this parameter to "1" if revisions can become
+   detached from branches. In this case, the source mirror tarball is
+   done per revision, which has a loss of efficiency. Rebasing the
+   upstream Git repository could cause the current revision to disappear
+   from the upstream repository. This option reminds the fetcher to
+   preserve the local cache carefully for future use. The default value
+   for this parameter is "0".
+
+-  *"nobranch":* Tells the fetcher to not check the SHA validation for
+   the branch when set to "1". The default is "0". Set this option for
+   the recipe that refers to the commit that is valid for a tag instead
+   of the branch.
+
+-  *"bareclone":* Tells the fetcher to clone a bare clone into the
+   destination directory without checking out a working tree. Only the
+   raw Git metadata is provided. This parameter implies the "nocheckout"
+   parameter as well.
+
+-  *"branch":* The branch(es) of the Git tree to clone. If unset, this
+   is assumed to be "master". The number of branch parameters much match
+   the number of name parameters.
+
+-  *"rev":* The revision to use for the checkout. The default is
+   "master".
+
+-  *"tag":* Specifies a tag to use for the checkout. To correctly
+   resolve tags, BitBake must access the network. For that reason, tags
+   are often not used. As far as Git is concerned, the "tag" parameter
+   behaves effectively the same as the "rev" parameter.
+
+-  *"subpath":* Limits the checkout to a specific subpath of the tree.
+   By default, the whole tree is checked out.
+
+-  *"destsuffix":* The name of the path in which to place the checkout.
+   By default, the path is ``git/``.
+
+-  *"usehead":* Enables local ``git://`` URLs to use the current branch
+   HEAD as the revision for use with ``AUTOREV``. The "usehead"
+   parameter implies no branch and only works when the transfer protocol
+   is ``file://``.
+
+Here are some example URLs: ::
+
+   SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
+   SRC_URI = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
+
+.. _gitsm-fetcher:
+
+Git Submodule Fetcher (``gitsm://``)
+------------------------------------
+
+This fetcher submodule inherits from the :ref:`Git
+fetcher<bitbake-user-manual/bitbake-user-manual-fetching:git fetcher
+(\`\`git://\`\`)>` and extends that fetcher's behavior by fetching a
+repository's submodules. :term:`SRC_URI` is passed to the Git fetcher as
+described in the :ref:`bitbake-user-manual/bitbake-user-manual-fetching:git
+fetcher (\`\`git://\`\`)` section.
+
+.. note::
+
+   You must clean a recipe when switching between '``git://``' and
+   '``gitsm://``' URLs.
+
+   The Git Submodules fetcher is not a complete fetcher implementation.
+   The fetcher has known issues where it does not use the normal source
+   mirroring infrastructure properly. Further, the submodule sources it
+   fetches are not visible to the licensing and source archiving
+   infrastructures.
+
+.. _clearcase-fetcher:
+
+ClearCase Fetcher (``ccrc://``)
+-------------------------------
+
+This fetcher submodule fetches code from a
+`ClearCase <http://en.wikipedia.org/wiki/Rational_ClearCase>`__
+repository.
+
+To use this fetcher, make sure your recipe has proper
+:term:`SRC_URI`, :term:`SRCREV`, and
+:term:`PV` settings. Here is an example: ::
+
+   SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module"
+   SRCREV = "EXAMPLE_CLEARCASE_TAG"
+   PV = "${@d.getVar("SRCREV", False).replace("/", "+")}"
+
+The fetcher uses the ``rcleartool`` or
+``cleartool`` remote client, depending on which one is available.
+
+Following are options for the ``SRC_URI`` statement:
+
+-  *vob*: The name, which must include the prepending "/" character,
+   of the ClearCase VOB. This option is required.
+
+-  *module*: The module, which must include the prepending "/"
+   character, in the selected VOB.
+
+   .. note::
+
+      The module and vob options are combined to create the load rule in the
+      view config spec. As an example, consider the vob and module values from
+      the SRC_URI statement at the start of this section. Combining those values
+      results in the following: ::
+
+         load /example_vob/example_module
+
+-  *proto*: The protocol, which can be either ``http`` or ``https``.
+
+By default, the fetcher creates a configuration specification. If you
+want this specification written to an area other than the default, use
+the ``CCASE_CUSTOM_CONFIG_SPEC`` variable in your recipe to define where
+the specification is written.
+
+.. note::
+
+   the SRCREV loses its functionality if you specify this variable. However,
+   SRCREV is still used to label the archive after a fetch even though it does
+   not define what is fetched.
+
+Here are a couple of other behaviors worth mentioning:
+
+-  When using ``cleartool``, the login of ``cleartool`` is handled by
+   the system. The login require no special steps.
+
+-  In order to use ``rcleartool`` with authenticated users, an
+   "rcleartool login" is necessary before using the fetcher.
+
+.. _perforce-fetcher:
+
+Perforce Fetcher (``p4://``)
+----------------------------
+
+This fetcher submodule fetches code from the
+`Perforce <https://www.perforce.com/>`__ source control system. The
+executable used is specified by ``FETCHCMD_p4``, which defaults to "p4".
+The fetcher's temporary working directory is set by
+:term:`P4DIR`, which defaults to "DL_DIR/p4".
+The fetcher does not make use of a perforce client, instead it
+relies on ``p4 files`` to retrieve a list of
+files and ``p4 print`` to transfer the content
+of those files locally.
+
+To use this fetcher, make sure your recipe has proper
+:term:`SRC_URI`, :term:`SRCREV`, and
+:term:`PV` values. The p4 executable is able to use the
+config file defined by your system's ``P4CONFIG`` environment variable
+in order to define the Perforce server URL and port, username, and
+password if you do not wish to keep those values in a recipe itself. If
+you choose not to use ``P4CONFIG``, or to explicitly set variables that
+``P4CONFIG`` can contain, you can specify the ``P4PORT`` value, which is
+the server's URL and port number, and you can specify a username and
+password directly in your recipe within ``SRC_URI``.
+
+Here is an example that relies on ``P4CONFIG`` to specify the server URL
+and port, username, and password, and fetches the Head Revision: ::
+
+   SRC_URI = "p4://example-depot/main/source/..."
+   SRCREV = "${AUTOREV}"
+   PV = "p4-${SRCPV}"
+   S = "${WORKDIR}/p4"
+
+Here is an example that specifies the server URL and port, username, and
+password, and fetches a Revision based on a Label: ::
+
+   P4PORT = "tcp:p4server.example.net:1666"
+   SRC_URI = "p4://user:passwd@example-depot/main/source/..."
+   SRCREV = "release-1.0"
+   PV = "p4-${SRCPV}"
+   S = "${WORKDIR}/p4"
+
+.. note::
+
+   You should always set S to "${WORKDIR}/p4" in your recipe.
+
+.. _repo-fetcher:
+
+Repo Fetcher (``repo://``)
+--------------------------
+
+This fetcher submodule fetches code from ``google-repo`` source control
+system. The fetcher works by initiating and syncing sources of the
+repository into :term:`REPODIR`, which is usually
+``${DL_DIR}/repo``.
+
+This fetcher supports the following parameters:
+
+-  *"protocol":* Protocol to fetch the repository manifest (default:
+   git).
+
+-  *"branch":* Branch or tag of repository to get (default: master).
+
+-  *"manifest":* Name of the manifest file (default: ``default.xml``).
+
+Here are some example URLs: ::
+
+   SRC_URI = "repo://REPOROOT;protocol=git;branch=some_branch;manifest=my_manifest.xml"
+   SRC_URI = "repo://REPOROOT;protocol=file;branch=some_branch;manifest=my_manifest.xml"
+
+Other Fetchers
+--------------
+
+Fetch submodules also exist for the following:
+
+-  Bazaar (``bzr://``)
+
+-  Mercurial (``hg://``)
+
+-  npm (``npm://``)
+
+-  OSC (``osc://``)
+
+-  Secure FTP (``sftp://``)
+
+-  Secure Shell (``ssh://``)
+
+-  Trees using Git Annex (``gitannex://``)
+
+No documentation currently exists for these lesser used fetcher
+submodules. However, you might find the code helpful and readable.
+
+Auto Revisions
+==============
+
+We need to document ``AUTOREV`` and ``SRCREV_FORMAT`` here.

bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml

@@ -1,868 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<chapter>
-<title>File Download Support</title>
-
-    <para>
-        BitBake's fetch module is a standalone piece of library code
-        that deals with the intricacies of downloading source code
-        and files from remote systems.
-        Fetching source code is one of the cornerstones of building software.
-        As such, this module forms an important part of BitBake.
-    </para>
-
-    <para>
-        The current fetch module is called "fetch2" and refers to the
-        fact that it is the second major version of the API.
-        The original version is obsolete and has been removed from the codebase.
-        Thus, in all cases, "fetch" refers to "fetch2" in this
-        manual.
-    </para>
-
-    <section id='the-download-fetch'>
-        <title>The Download (Fetch)</title>
-
-        <para>
-            BitBake takes several steps when fetching source code or files.
-            The fetcher codebase deals with two distinct processes in order:
-            obtaining the files from somewhere (cached or otherwise)
-            and then unpacking those files into a specific location and
-            perhaps in a specific way.
-            Getting and unpacking the files is often optionally followed
-            by patching.
-            Patching, however, is not covered by this module.
-        </para>
-
-        <para>
-            The code to execute the first part of this process, a fetch,
-            looks something like the following:
-            <literallayout class='monospaced'>
-     src_uri = (d.getVar('SRC_URI') or "").split()
-     fetcher = bb.fetch2.Fetch(src_uri, d)
-     fetcher.download()
-            </literallayout>
-            This code sets up an instance of the fetch class.
-            The instance uses a space-separated list of URLs from the
-            <link linkend='var-bb-SRC_URI'><filename>SRC_URI</filename></link>
-            variable and then calls the <filename>download</filename>
-            method to download the files.
-        </para>
-
-        <para>
-            The instantiation of the fetch class is usually followed by:
-            <literallayout class='monospaced'>
-     rootdir = l.getVar('WORKDIR')
-     fetcher.unpack(rootdir)
-            </literallayout>
-            This code unpacks the downloaded files to the
-            specified by <filename>WORKDIR</filename>.
-            <note>
-                For convenience, the naming in these examples matches
-                the variables used by OpenEmbedded.
-                If you want to see the above code in action, examine
-                the OpenEmbedded class file <filename>base.bbclass</filename>.
-            </note>
-            The <filename>SRC_URI</filename> and <filename>WORKDIR</filename>
-            variables are not hardcoded into the fetcher, since those fetcher
-            methods can be (and are) called with different variable names.
-            In OpenEmbedded for example, the shared state (sstate) code uses
-            the fetch module to fetch the sstate files.
-        </para>
-
-        <para>
-            When the <filename>download()</filename> method is called,
-            BitBake tries to resolve the URLs by looking for source files
-            in a specific search order:
-            <itemizedlist>
-                <listitem><para><emphasis>Pre-mirror Sites:</emphasis>
-                    BitBake first uses pre-mirrors to try and find source files.
-                    These locations are defined using the
-                    <link linkend='var-bb-PREMIRRORS'><filename>PREMIRRORS</filename></link>
-                    variable.
-                    </para></listitem>
-                <listitem><para><emphasis>Source URI:</emphasis>
-                    If pre-mirrors fail, BitBake uses the original URL (e.g from
-                    <filename>SRC_URI</filename>).
-                    </para></listitem>
-                <listitem><para><emphasis>Mirror Sites:</emphasis>
-                    If fetch failures occur, BitBake next uses mirror locations as
-                    defined by the
-                    <link linkend='var-bb-MIRRORS'><filename>MIRRORS</filename></link>
-                    variable.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-
-        <para>
-            For each URL passed to the fetcher, the fetcher
-            calls the submodule that handles that particular URL type.
-            This behavior can be the source of some confusion when you
-            are providing URLs for the <filename>SRC_URI</filename>
-            variable.
-            Consider the following two URLs:
-            <literallayout class='monospaced'>
-     http://git.yoctoproject.org/git/poky;protocol=git
-     git://git.yoctoproject.org/git/poky;protocol=http
-            </literallayout>
-            In the former case, the URL is passed to the
-            <filename>wget</filename> fetcher, which does not
-            understand "git".
-            Therefore, the latter case is the correct form since the
-            Git fetcher does know how to use HTTP as a transport.
-        </para>
-
-        <para>
-            Here are some examples that show commonly used mirror
-            definitions:
-            <literallayout class='monospaced'>
-     PREMIRRORS ?= "\
-         bzr://.*/.*   http://somemirror.org/sources/ \n \
-         cvs://.*/.*   http://somemirror.org/sources/ \n \
-         git://.*/.*   http://somemirror.org/sources/ \n \
-         hg://.*/.*    http://somemirror.org/sources/ \n \
-         osc://.*/.*   http://somemirror.org/sources/ \n \
-         p4://.*/.*    http://somemirror.org/sources/ \n \
-         svn://.*/.*   http://somemirror.org/sources/ \n"
-
-     MIRRORS =+ "\
-         ftp://.*/.*      http://somemirror.org/sources/ \n \
-         http://.*/.*     http://somemirror.org/sources/ \n \
-         https://.*/.*    http://somemirror.org/sources/ \n"
-            </literallayout>
-            It is useful to note that BitBake supports
-            cross-URLs.
-            It is possible to mirror a Git repository on an HTTP
-            server as a tarball.
-            This is what the <filename>git://</filename> mapping in
-            the previous example does.
-        </para>
-
-        <para>
-            Since network accesses are slow, BitBake maintains a
-            cache of files downloaded from the network.
-            Any source files that are not local (i.e.
-            downloaded from the Internet) are placed into the download
-            directory, which is specified by the
-            <link linkend='var-bb-DL_DIR'><filename>DL_DIR</filename></link>
-            variable.
-        </para>
-
-        <para>
-            File integrity is of key importance for reproducing builds.
-            For non-local archive downloads, the fetcher code can verify
-            SHA-256 and MD5 checksums to ensure the archives have been
-            downloaded correctly.
-            You can specify these checksums by using the
-            <filename>SRC_URI</filename> variable with the appropriate
-            varflags as follows:
-            <literallayout class='monospaced'>
-     SRC_URI[md5sum] = "<replaceable>value</replaceable>"
-     SRC_URI[sha256sum] = "<replaceable>value</replaceable>"
-            </literallayout>
-            You can also specify the checksums as parameters on the
-            <filename>SRC_URI</filename> as shown below:
-            <literallayout class='monospaced'>
-     SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
-            </literallayout>
-            If multiple URIs exist, you can specify the checksums either
-            directly as in the previous example, or you can name the URLs.
-            The following syntax shows how you name the URIs:
-            <literallayout class='monospaced'>
-     SRC_URI = "http://example.com/foobar.tar.bz2;name=foo"
-     SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d
-            </literallayout>
-            After a file has been downloaded and has had its checksum checked,
-            a ".done" stamp is placed in <filename>DL_DIR</filename>.
-            BitBake uses this stamp during subsequent builds to avoid
-            downloading or comparing a checksum for the file again.
-            <note>
-                It is assumed that local storage is safe from data corruption.
-                If this were not the case, there would be bigger issues to worry about.
-            </note>
-        </para>
-
-        <para>
-            If
-            <link linkend='var-bb-BB_STRICT_CHECKSUM'><filename>BB_STRICT_CHECKSUM</filename></link>
-            is set, any download without a checksum triggers an
-            error message.
-            The
-            <link linkend='var-bb-BB_NO_NETWORK'><filename>BB_NO_NETWORK</filename></link>
-            variable can be used to make any attempted network access a fatal
-            error, which is useful for checking that mirrors are complete
-            as well as other things.
-        </para>
-    </section>
-
-    <section id='bb-the-unpack'>
-        <title>The Unpack</title>
-
-        <para>
-            The unpack process usually immediately follows the download.
-            For all URLs except Git URLs, BitBake uses the common
-            <filename>unpack</filename> method.
-        </para>
-
-        <para>
-            A number of parameters exist that you can specify within the
-            URL to govern the behavior of the unpack stage:
-            <itemizedlist>
-                <listitem><para><emphasis>unpack:</emphasis>
-                    Controls whether the URL components are unpacked.
-                    If set to "1", which is the default, the components
-                    are unpacked.
-                    If set to "0", the unpack stage leaves the file alone.
-                    This parameter is useful when you want an archive to be
-                    copied in and not be unpacked.
-                    </para></listitem>
-                <listitem><para><emphasis>dos:</emphasis>
-                    Applies to <filename>.zip</filename> and
-                    <filename>.jar</filename> files and specifies whether to
-                    use DOS line ending conversion on text files.
-                    </para></listitem>
-                <listitem><para><emphasis>basepath:</emphasis>
-                    Instructs the unpack stage to strip the specified
-                    directories from the source path when unpacking.
-                    </para></listitem>
-                <listitem><para><emphasis>subdir:</emphasis>
-                    Unpacks the specific URL to the specified subdirectory
-                    within the root directory.
-                    </para></listitem>
-            </itemizedlist>
-            The unpack call automatically decompresses and extracts files
-            with ".Z", ".z", ".gz", ".xz", ".zip", ".jar", ".ipk", ".rpm".
-            ".srpm", ".deb" and ".bz2" extensions as well as various combinations
-            of tarball extensions.
-        </para>
-
-        <para>
-            As mentioned, the Git fetcher has its own unpack method that
-            is optimized to work with Git trees.
-            Basically, this method works by cloning the tree into the final
-            directory.
-            The process is completed using references so that there is
-            only one central copy of the Git metadata needed.
-        </para>
-    </section>
-
-    <section id='bb-fetchers'>
-        <title>Fetchers</title>
-
-        <para>
-            As mentioned earlier, the URL prefix determines which
-            fetcher submodule BitBake uses.
-            Each submodule can support different URL parameters,
-            which are described in the following sections.
-        </para>
-
-        <section id='local-file-fetcher'>
-            <title>Local file fetcher (<filename>file://</filename>)</title>
-
-            <para>
-                This submodule handles URLs that begin with
-                <filename>file://</filename>.
-                The filename you specify within the URL can be
-                either an absolute or relative path to a file.
-                If the filename is relative, the contents of the
-                <link linkend='var-bb-FILESPATH'><filename>FILESPATH</filename></link>
-                variable is used in the same way
-                <filename>PATH</filename> is used to find executables.
-                If the file cannot be found, it is assumed that it is available in
-                <link linkend='var-bb-DL_DIR'><filename>DL_DIR</filename></link>
-                by the time the <filename>download()</filename> method is called.
-            </para>
-
-            <para>
-                If you specify a directory, the entire directory is
-                unpacked.
-            </para>
-
-            <para>
-                Here are a couple of example URLs, the first relative and
-                the second absolute:
-                <literallayout class='monospaced'>
-     SRC_URI = "file://relativefile.patch"
-     SRC_URI = "file:///Users/ich/very_important_software"
-                </literallayout>
-            </para>
-        </section>
-
-        <section id='http-ftp-fetcher'>
-            <title>HTTP/FTP wget fetcher (<filename>http://</filename>, <filename>ftp://</filename>, <filename>https://</filename>)</title>
-
-            <para>
-                This fetcher obtains files from web and FTP servers.
-                Internally, the fetcher uses the wget utility.
-            </para>
-
-            <para>
-                The executable and parameters used are specified by the
-                <filename>FETCHCMD_wget</filename> variable, which defaults
-                to sensible values.
-                The fetcher supports a parameter "downloadfilename" that
-                allows the name of the downloaded file to be specified.
-                Specifying the name of the downloaded file is useful
-                for avoiding collisions in
-                <link linkend='var-bb-DL_DIR'><filename>DL_DIR</filename></link>
-                when dealing with multiple files that have the same name.
-            </para>
-
-            <para>
-                Some example URLs are as follows:
-                <literallayout class='monospaced'>
-     SRC_URI = "http://oe.handhelds.org/not_there.aac"
-     SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac"
-     SRC_URI = "ftp://you@oe.handhelds.org/home/you/secret.plan"
-                </literallayout>
-            </para>
-            <note>
-               Because URL parameters are delimited by semi-colons, this can
-               introduce ambiguity when parsing URLs that also contain semi-colons,
-               for example:
-                <literallayout class='monospaced'>
-     SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47"
-                </literallayout>
-               Such URLs should should be modified by replacing semi-colons with '&amp;' characters:
-               <literallayout class='monospaced'>
-     SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&amp;a=snapshot&amp;h=a5dd47"
-                </literallayout>
-                In most cases this should work. Treating semi-colons and '&amp;' in queries
-                identically is recommended by the World Wide Web Consortium (W3C).
-                Note that due to the nature of the URL, you may have to specify the name
-                of the downloaded file as well:
-              <literallayout class='monospaced'>
-     SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&amp;a=snapshot&amp;h=a5dd47;downloadfilename=myfile.bz2"
-                </literallayout>
-            </note>
-        </section>
-
-        <section id='cvs-fetcher'>
-            <title>CVS fetcher (<filename>(cvs://</filename>)</title>
-
-            <para>
-                This submodule handles checking out files from the
-                CVS version control system.
-                You can configure it using a number of different variables:
-                <itemizedlist>
-                    <listitem><para><emphasis><filename>FETCHCMD_cvs</filename>:</emphasis>
-                        The name of the executable to use when running
-                        the <filename>cvs</filename> command.
-                        This name is usually "cvs".
-                        </para></listitem>
-                    <listitem><para><emphasis><filename>SRCDATE</filename>:</emphasis>
-                        The date to use when fetching the CVS source code.
-                        A special value of "now" causes the checkout to
-                        be updated on every build.
-                        </para></listitem>
-                    <listitem><para><emphasis><link linkend='var-bb-CVSDIR'><filename>CVSDIR</filename></link>:</emphasis>
-                        Specifies where a temporary checkout is saved.
-                        The location is often <filename>DL_DIR/cvs</filename>.
-                        </para></listitem>
-                    <listitem><para><emphasis><filename>CVS_PROXY_HOST</filename>:</emphasis>
-                        The name to use as a "proxy=" parameter to the
-                        <filename>cvs</filename> command.
-                        </para></listitem>
-                    <listitem><para><emphasis><filename>CVS_PROXY_PORT</filename>:</emphasis>
-                        The port number to use as a "proxyport=" parameter to
-                        the <filename>cvs</filename> command.
-                        </para></listitem>
-                </itemizedlist>
-                As well as the standard username and password URL syntax,
-                you can also configure the fetcher with various URL parameters:
-            </para>
-
-            <para>
-                The supported parameters are as follows:
-                <itemizedlist>
-                    <listitem><para><emphasis>"method":</emphasis>
-                        The protocol over which to communicate with the CVS
-                        server.
-                        By default, this protocol is "pserver".
-                        If "method" is set to "ext", BitBake examines the
-                        "rsh" parameter and sets <filename>CVS_RSH</filename>.
-                        You can use "dir" for local directories.
-                        </para></listitem>
-                    <listitem><para><emphasis>"module":</emphasis>
-                        Specifies the module to check out.
-                        You must supply this parameter.
-                        </para></listitem>
-                    <listitem><para><emphasis>"tag":</emphasis>
-                        Describes which CVS TAG should be used for
-                        the checkout.
-                        By default, the TAG is empty.
-                        </para></listitem>
-                    <listitem><para><emphasis>"date":</emphasis>
-                        Specifies a date.
-                        If no "date" is specified, the
-                        <link linkend='var-bb-SRCDATE'><filename>SRCDATE</filename></link>
-                        of the configuration is used to checkout a specific date.
-                        The special value of "now" causes the checkout to be
-                        updated on every build.
-                        </para></listitem>
-                    <listitem><para><emphasis>"localdir":</emphasis>
-                        Used to rename the module.
-                        Effectively, you are renaming the output directory
-                        to which the module is unpacked.
-                        You are forcing the module into a special
-                        directory relative to
-                        <link linkend='var-bb-CVSDIR'><filename>CVSDIR</filename></link>.
-                        </para></listitem>
-                    <listitem><para><emphasis>"rsh"</emphasis>
-                        Used in conjunction with the "method" parameter.
-                        </para></listitem>
-                    <listitem><para><emphasis>"scmdata":</emphasis>
-                        Causes the CVS metadata to be maintained in the tarball
-                        the fetcher creates when set to "keep".
-                        The tarball is expanded into the work directory.
-                        By default, the CVS metadata is removed.
-                        </para></listitem>
-                    <listitem><para><emphasis>"fullpath":</emphasis>
-                        Controls whether the resulting checkout is at the
-                        module level, which is the default, or is at deeper
-                        paths.
-                        </para></listitem>
-                    <listitem><para><emphasis>"norecurse":</emphasis>
-                        Causes the fetcher to only checkout the specified
-                        directory with no recurse into any subdirectories.
-                        </para></listitem>
-                    <listitem><para><emphasis>"port":</emphasis>
-                        The port to which the CVS server connects.
-                        </para></listitem>
-                </itemizedlist>
-                Some example URLs are as follows:
-                <literallayout class='monospaced'>
-     SRC_URI = "cvs://CVSROOT;module=mymodule;tag=some-version;method=ext"
-     SRC_URI = "cvs://CVSROOT;module=mymodule;date=20060126;localdir=usethat"
-                </literallayout>
-            </para>
-        </section>
-
-        <section id='svn-fetcher'>
-            <title>Subversion (SVN) Fetcher (<filename>svn://</filename>)</title>
-
-            <para>
-                This fetcher submodule fetches code from the
-                Subversion source control system.
-                The executable used is specified by
-                <filename>FETCHCMD_svn</filename>, which defaults
-                to "svn".
-                The fetcher's temporary working directory is set by
-                <link linkend='var-bb-SVNDIR'><filename>SVNDIR</filename></link>,
-                which is usually <filename>DL_DIR/svn</filename>.
-            </para>
-
-            <para>
-                The supported parameters are as follows:
-                <itemizedlist>
-                    <listitem><para><emphasis>"module":</emphasis>
-                        The name of the svn module to checkout.
-                        You must provide this parameter.
-                        You can think of this parameter as the top-level
-                        directory of the repository data you want.
-                        </para></listitem>
-                    <listitem><para><emphasis>"path_spec":</emphasis>
-                        A specific directory in which to checkout the
-                        specified svn module.
-                        </para></listitem>
-                    <listitem><para><emphasis>"protocol":</emphasis>
-                        The protocol to use, which defaults to "svn".
-                        If "protocol" is set to "svn+ssh", the "ssh"
-                        parameter is also used.
-                        </para></listitem>
-                    <listitem><para><emphasis>"rev":</emphasis>
-                        The revision of the source code to checkout.
-                        </para></listitem>
-                    <listitem><para><emphasis>"scmdata":</emphasis>
-                        Causes the “.svn” directories to be available during
-                        compile-time when set to "keep".
-                        By default, these directories are removed.
-                        </para></listitem>
-                    <listitem><para><emphasis>"ssh":</emphasis>
-                        An optional parameter used when "protocol" is set
-                        to "svn+ssh".
-                        You can use this parameter to specify the ssh
-                        program used by svn.
-                        </para></listitem>
-                    <listitem><para><emphasis>"transportuser":</emphasis>
-                        When required, sets the username for the transport.
-                        By default, this parameter is empty.
-                        The transport username is different than the username
-                        used in the main URL, which is passed to the subversion
-                        command.
-                        </para></listitem>
-                </itemizedlist>
-                Following are three examples using svn:
-                <literallayout class='monospaced'>
-     SRC_URI = "svn://myrepos/proj1;module=vip;protocol=http;rev=667"
-     SRC_URI = "svn://myrepos/proj1;module=opie;protocol=svn+ssh"
-     SRC_URI = "svn://myrepos/proj1;module=trunk;protocol=http;path_spec=${MY_DIR}/proj1"
-                </literallayout>
-            </para>
-        </section>
-
-        <section id='git-fetcher'>
-            <title>Git Fetcher (<filename>git://</filename>)</title>
-
-            <para>
-                This fetcher submodule fetches code from the Git
-                source control system.
-                The fetcher works by creating a bare clone of the
-                remote into
-                <link linkend='var-bb-GITDIR'><filename>GITDIR</filename></link>,
-                which is usually <filename>DL_DIR/git2</filename>.
-                This bare clone is then cloned into the work directory during the
-                unpack stage when a specific tree is checked out.
-                This is done using alternates and by reference to
-                minimize the amount of duplicate data on the disk and
-                make the unpack process fast.
-                The executable used can be set with
-                <filename>FETCHCMD_git</filename>.
-            </para>
-
-            <para>
-                This fetcher supports the following parameters:
-                <itemizedlist>
-                    <listitem><para><emphasis>"protocol":</emphasis>
-                        The protocol used to fetch the files.
-                        The default is "git" when a hostname is set.
-                        If a hostname is not set, the Git protocol is "file".
-                        You can also use "http", "https", "ssh" and "rsync".
-                        </para></listitem>
-                    <listitem><para><emphasis>"nocheckout":</emphasis>
-                        Tells the fetcher to not checkout source code when
-                        unpacking when set to "1".
-                        Set this option for the URL where there is a custom
-                        routine to checkout code.
-                        The default is "0".
-                        </para></listitem>
-                    <listitem><para><emphasis>"rebaseable":</emphasis>
-                        Indicates that the upstream Git repository can be rebased.
-                        You should set this parameter to "1" if
-                        revisions can become detached from branches.
-                        In this case, the source mirror tarball is done per
-                        revision, which has a loss of efficiency.
-                        Rebasing the upstream Git repository could cause the
-                        current revision to disappear from the upstream repository.
-                        This option reminds the fetcher to preserve the local cache
-                        carefully for future use.
-                        The default value for this parameter is "0".
-                        </para></listitem>
-                    <listitem><para><emphasis>"nobranch":</emphasis>
-                        Tells the fetcher to not check the SHA validation
-                        for the branch when set to "1".
-                        The default is "0".
-                        Set this option for the recipe that refers to
-                        the commit that is valid for a tag instead of
-                        the branch.
-                        </para></listitem>
-                    <listitem><para><emphasis>"bareclone":</emphasis>
-                        Tells the fetcher to clone a bare clone into the
-                        destination directory without checking out a working tree.
-                        Only the raw Git metadata is provided.
-                        This parameter implies the "nocheckout" parameter as well.
-                        </para></listitem>
-                    <listitem><para><emphasis>"branch":</emphasis>
-                        The branch(es) of the Git tree to clone.
-                        If unset, this is assumed to be "master".
-                        The number of branch parameters much match the number of
-                        name parameters.
-                        </para></listitem>
-                    <listitem><para><emphasis>"rev":</emphasis>
-                        The revision to use for the checkout.
-                        The default is "master".
-                        </para></listitem>
-                    <listitem><para><emphasis>"tag":</emphasis>
-                        Specifies a tag to use for the checkout.
-                        To correctly resolve tags, BitBake must access the
-                        network.
-                        For that reason, tags are often not used.
-                        As far as Git is concerned, the "tag" parameter behaves
-                        effectively the same as the "rev" parameter.
-                        </para></listitem>
-                    <listitem><para><emphasis>"subpath":</emphasis>
-                        Limits the checkout to a specific subpath of the tree.
-                        By default, the whole tree is checked out.
-                        </para></listitem>
-                    <listitem><para><emphasis>"destsuffix":</emphasis>
-                        The name of the path in which to place the checkout.
-                        By default, the path is <filename>git/</filename>.
-                        </para></listitem>
-                    <listitem><para><emphasis>"usehead":</emphasis>
-                        Enables local <filename>git://</filename> URLs to use the
-                        current branch HEAD as the revision for use with
-                        <filename>AUTOREV</filename>.
-                        The "usehead" parameter implies no branch and only works
-                        when the transfer protocol is
-                        <filename>file://</filename>.
-                        </para></listitem>
-                </itemizedlist>
-                Here are some example URLs:
-                <literallayout class='monospaced'>
-     SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1"
-     SRC_URI = "git://git.oe.handhelds.org/git/vip.git;protocol=http"
-                </literallayout>
-            </para>
-        </section>
-
-        <section id='gitsm-fetcher'>
-            <title>Git Submodule Fetcher (<filename>gitsm://</filename>)</title>
-
-            <para>
-                This fetcher submodule inherits from the
-                <link linkend='git-fetcher'>Git fetcher</link> and extends
-                that fetcher's behavior by fetching a repository's submodules.
-                <link linkend='var-bb-SRC_URI'><filename>SRC_URI</filename></link>
-                is passed to the Git fetcher as described in the
-                "<link linkend='git-fetcher'>Git Fetcher (<filename>git://</filename>)</link>"
-                section.
-                <note>
-                    <title>Notes and Warnings</title>
-                    <para>
-                        You must clean a recipe when switching between
-                        '<filename>git://</filename>' and
-                        '<filename>gitsm://</filename>' URLs.
-                    </para>
-
-                    <para>
-                        The Git Submodules fetcher is not a complete fetcher
-                        implementation.
-                        The fetcher has known issues where it does not use the
-                        normal source mirroring infrastructure properly. Further,
-                        the submodule sources it fetches are not visible to the
-                        licensing and source archiving infrastructures.
-                    </para>
-                </note>
-            </para>
-        </section>
-
-        <section id='clearcase-fetcher'>
-            <title>ClearCase Fetcher (<filename>ccrc://</filename>)</title>
-
-            <para>
-                This fetcher submodule fetches code from a
-                <ulink url='http://en.wikipedia.org/wiki/Rational_ClearCase'>ClearCase</ulink>
-                repository.
-            </para>
-
-            <para>
-                To use this fetcher, make sure your recipe has proper
-                <link linkend='var-bb-SRC_URI'><filename>SRC_URI</filename></link>,
-                <link linkend='var-bb-SRCREV'><filename>SRCREV</filename></link>, and
-                <link linkend='var-bb-PV'><filename>PV</filename></link> settings.
-                Here is an example:
-                <literallayout class='monospaced'>
-     SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module"
-     SRCREV = "EXAMPLE_CLEARCASE_TAG"
-     PV = "${@d.getVar("SRCREV", False).replace("/", "+")}"
-                </literallayout>
-                The fetcher uses the <filename>rcleartool</filename> or
-                <filename>cleartool</filename> remote client, depending on
-                which one is available.
-            </para>
-
-            <para>
-                Following are options for the <filename>SRC_URI</filename>
-                statement:
-                <itemizedlist>
-                    <listitem><para><emphasis><filename>vob</filename></emphasis>:
-                        The name, which must include the
-                        prepending "/" character, of the ClearCase VOB.
-                        This option is required.
-                        </para></listitem>
-                    <listitem><para><emphasis><filename>module</filename></emphasis>:
-                        The module, which must include the
-                        prepending "/" character, in the selected VOB.
-                        <note>
-                            The <filename>module</filename> and <filename>vob</filename>
-                            options are combined to create the <filename>load</filename> rule in
-                            the view config spec.
-                            As an example, consider the <filename>vob</filename> and
-                            <filename>module</filename> values from the
-                            <filename>SRC_URI</filename> statement at the start of this section.
-                            Combining those values results in the following:
-                            <literallayout class='monospaced'>
-     load /example_vob/example_module
-                            </literallayout>
-                        </note>
-                        </para></listitem>
-                    <listitem><para><emphasis><filename>proto</filename></emphasis>:
-                        The protocol, which can be either <filename>http</filename> or
-                        <filename>https</filename>.
-                        </para></listitem>
-                </itemizedlist>
-            </para>
-
-            <para>
-                By default, the fetcher creates a configuration specification.
-                If you want this specification written to an area other than the default,
-                use the <filename>CCASE_CUSTOM_CONFIG_SPEC</filename> variable
-                in your recipe to define where the specification is written.
-                <note>
-                    the <filename>SRCREV</filename> loses its functionality if you
-                    specify this variable.
-                    However, <filename>SRCREV</filename> is still used to label the
-                    archive after a fetch even though it does not define what is
-                    fetched.
-                </note>
-            </para>
-
-            <para>
-                Here are a couple of other behaviors worth mentioning:
-                <itemizedlist>
-                    <listitem><para>
-                        When using <filename>cleartool</filename>, the login of
-                        <filename>cleartool</filename> is handled by the system.
-                        The login require no special steps.
-                        </para></listitem>
-                    <listitem><para>
-                        In order to use <filename>rcleartool</filename> with authenticated
-                        users, an "rcleartool login" is necessary before using the fetcher.
-                        </para></listitem>
-                </itemizedlist>
-            </para>
-        </section>
-
-        <section id='perforce-fetcher'>
-            <title>Perforce Fetcher (<filename>p4://</filename>)</title>
-
-            <para>
-                This fetcher submodule fetches code from the
-                <ulink url='https://www.perforce.com/'>Perforce</ulink>
-                source control system.
-                The executable used is specified by
-                <filename>FETCHCMD_p4</filename>, which defaults
-                to "p4".
-                The fetcher's temporary working directory is set by
-                <link linkend='var-bb-P4DIR'><filename>P4DIR</filename></link>,
-                which defaults to "DL_DIR/p4".
-            </para>
-
-            <para>
-                To use this fetcher, make sure your recipe has proper
-                <link linkend='var-bb-SRC_URI'><filename>SRC_URI</filename></link>,
-                <link linkend='var-bb-SRCREV'><filename>SRCREV</filename></link>, and
-                <link linkend='var-bb-PV'><filename>PV</filename></link> values.
-                The p4 executable is able to use the config file defined by your
-                system's <filename>P4CONFIG</filename> environment variable in
-                order to define the Perforce server URL and port, username, and
-                password if you do not wish to keep those values in a recipe
-                itself.
-                If you choose not to use <filename>P4CONFIG</filename>,
-                or to explicitly set variables that <filename>P4CONFIG</filename>
-                can contain, you can specify the <filename>P4PORT</filename> value,
-                which is the server's URL and port number, and you can
-                specify a username and password directly in your recipe within
-                <filename>SRC_URI</filename>.
-            </para>
-
-            <para>
-                Here is an example that relies on <filename>P4CONFIG</filename>
-                to specify the server URL and port, username, and password, and
-                fetches the Head Revision:
-                <literallayout class='monospaced'>
-    SRC_URI = "p4://example-depot/main/source/..."
-    SRCREV = "${AUTOREV}"
-    PV = "p4-${SRCPV}"
-    S = "${WORKDIR}/p4"
-                </literallayout>
-            </para>
-
-            <para>
-                Here is an example that specifies the server URL and port,
-                username, and password, and fetches a Revision based on a Label:
-                <literallayout class='monospaced'>
-    P4PORT = "tcp:p4server.example.net:1666"
-    SRC_URI = "p4://user:passwd@example-depot/main/source/..."
-    SRCREV = "release-1.0"
-    PV = "p4-${SRCPV}"
-    S = "${WORKDIR}/p4"
-                </literallayout>
-                <note>
-                    You should always set <filename>S</filename>
-                    to <filename>"${WORKDIR}/p4"</filename> in your recipe.
-                </note>
-            </para>
-        </section>
-
-        <section id='repo-fetcher'>
-            <title>Repo Fetcher (<filename>repo://</filename>)</title>
-
-            <para>
-                This fetcher submodule fetches code from
-                <filename>google-repo</filename> source control system.
-                The fetcher works by initiating and syncing sources of the
-                repository into
-                <link linkend='var-bb-REPODIR'><filename>REPODIR</filename></link>,
-                which is usually
-                <link linkend='var-bb-DL_DIR'><filename>DL_DIR</filename></link><filename>/repo</filename>.
-            </para>
-
-            <para>
-                This fetcher supports the following parameters:
-                <itemizedlist>
-                    <listitem><para>
-                        <emphasis>"protocol":</emphasis>
-                        Protocol to fetch the repository manifest (default: git).
-                        </para></listitem>
-                    <listitem><para>
-                        <emphasis>"branch":</emphasis>
-                        Branch or tag of repository to get (default: master).
-                        </para></listitem>
-                    <listitem><para>
-                        <emphasis>"manifest":</emphasis>
-                        Name of the manifest file (default: <filename>default.xml</filename>).
-                        </para></listitem>
-                </itemizedlist>
-                Here are some example URLs:
-                <literallayout class='monospaced'>
-    SRC_URI = "repo://REPOROOT;protocol=git;branch=some_branch;manifest=my_manifest.xml"
-    SRC_URI = "repo://REPOROOT;protocol=file;branch=some_branch;manifest=my_manifest.xml"
-                </literallayout>
-            </para>
-        </section>
-
-        <section id='other-fetchers'>
-            <title>Other Fetchers</title>
-
-            <para>
-                Fetch submodules also exist for the following:
-                <itemizedlist>
-                    <listitem><para>
-                        Bazaar (<filename>bzr://</filename>)
-                        </para></listitem>
-                    <listitem><para>
-                        Mercurial (<filename>hg://</filename>)
-                        </para></listitem>
-                    <listitem><para>
-                        npm (<filename>npm://</filename>)
-                        </para></listitem>
-                    <listitem><para>
-                        OSC (<filename>osc://</filename>)
-                        </para></listitem>
-                    <listitem><para>
-                        Secure FTP (<filename>sftp://</filename>)
-                        </para></listitem>
-                    <listitem><para>
-                        Secure Shell (<filename>ssh://</filename>)
-                        </para></listitem>
-                    <listitem><para>
-                        Trees using Git Annex (<filename>gitannex://</filename>)
-                        </para></listitem>
-                </itemizedlist>
-                No documentation currently exists for these lesser used
-                fetcher submodules.
-                However, you might find the code helpful and readable.
-            </para>
-        </section>
-    </section>
-
-    <section id='auto-revisions'>
-        <title>Auto Revisions</title>
-
-        <para>
-            We need to document <filename>AUTOREV</filename> and
-            <filename>SRCREV_FORMAT</filename> here.
-        </para>
-    </section>
-</chapter>

bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.rst

@@ -0,0 +1,415 @@
+.. SPDX-License-Identifier: CC-BY-2.5
+
+===================
+Hello World Example
+===================
+
+BitBake Hello World
+===================
+
+The simplest example commonly used to demonstrate any new programming
+language or tool is the "`Hello
+World <http://en.wikipedia.org/wiki/Hello_world_program>`__" example.
+This appendix demonstrates, in tutorial form, Hello World within the
+context of BitBake. The tutorial describes how to create a new project
+and the applicable metadata files necessary to allow BitBake to build
+it.
+
+Obtaining BitBake
+=================
+
+See the :ref:`bitbake-user-manual/bitbake-user-manual-hello:obtaining bitbake` section for
+information on how to obtain BitBake. Once you have the source code on
+your machine, the BitBake directory appears as follows: ::
+
+   $ ls -al
+   total 100
+   drwxrwxr-x. 9 wmat wmat  4096 Jan 31 13:44 .
+   drwxrwxr-x. 3 wmat wmat  4096 Feb  4 10:45 ..
+   -rw-rw-r--. 1 wmat wmat   365 Nov 26 04:55 AUTHORS
+   drwxrwxr-x. 2 wmat wmat  4096 Nov 26 04:55 bin
+   drwxrwxr-x. 4 wmat wmat  4096 Jan 31 13:44 build
+   -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog
+   drwxrwxr-x. 2 wmat wmat  4096 Nov 26 04:55 classes
+   drwxrwxr-x. 2 wmat wmat  4096 Nov 26 04:55 conf
+   drwxrwxr-x. 3 wmat wmat  4096 Nov 26 04:55 contrib
+   -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING
+   drwxrwxr-x. 3 wmat wmat  4096 Nov 26 04:55 doc
+   -rw-rw-r--. 1 wmat wmat    69 Nov 26 04:55 .gitignore
+   -rw-rw-r--. 1 wmat wmat   849 Nov 26 04:55 HEADER
+   drwxrwxr-x. 5 wmat wmat  4096 Jan 31 13:44 lib
+   -rw-rw-r--. 1 wmat wmat   195 Nov 26 04:55 MANIFEST.in
+   -rw-rw-r--. 1 wmat wmat  2887 Nov 26 04:55 TODO
+
+At this point, you should have BitBake cloned to a directory that
+matches the previous listing except for dates and user names.
+
+Setting Up the BitBake Environment
+==================================
+
+First, you need to be sure that you can run BitBake. Set your working
+directory to where your local BitBake files are and run the following
+command: ::
+
+  $ ./bin/bitbake --version
+  BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0
+
+The console output tells you what version
+you are running.
+
+The recommended method to run BitBake is from a directory of your
+choice. To be able to run BitBake from any directory, you need to add
+the executable binary to your binary to your shell's environment
+``PATH`` variable. First, look at your current ``PATH`` variable by
+entering the following: ::
+
+  $ echo $PATH
+
+Next, add the directory location
+for the BitBake binary to the ``PATH``. Here is an example that adds the
+``/home/scott-lenovo/bitbake/bin`` directory to the front of the
+``PATH`` variable: ::
+
+  $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH
+
+You should now be able to enter the ``bitbake`` command from the command
+line while working from any directory.
+
+The Hello World Example
+=======================
+
+The overall goal of this exercise is to build a complete "Hello World"
+example utilizing task and layer concepts. Because this is how modern
+projects such as OpenEmbedded and the Yocto Project utilize BitBake, the
+example provides an excellent starting point for understanding BitBake.
+
+To help you understand how to use BitBake to build targets, the example
+starts with nothing but the ``bitbake`` command, which causes BitBake to
+fail and report problems. The example progresses by adding pieces to the
+build to eventually conclude with a working, minimal "Hello World"
+example.
+
+While every attempt is made to explain what is happening during the
+example, the descriptions cannot cover everything. You can find further
+information throughout this manual. Also, you can actively participate
+in the :oe_lists:`/g/bitbake-devel`
+discussion mailing list about the BitBake build tool.
+
+.. note::
+
+   This example was inspired by and drew heavily from
+   `Mailing List post - The BitBake equivalent of "Hello, World!"
+   <http://www.mail-archive.com/yocto@yoctoproject.org/msg09379.html>`_.
+
+As stated earlier, the goal of this example is to eventually compile
+"Hello World". However, it is unknown what BitBake needs and what you
+have to provide in order to achieve that goal. Recall that BitBake
+utilizes three types of metadata files:
+:ref:`bitbake-user-manual/bitbake-user-manual-intro:configuration files`,
+:ref:`bitbake-user-manual/bitbake-user-manual-intro:classes`, and
+:ref:`bitbake-user-manual/bitbake-user-manual-intro:recipes`.
+But where do they go? How does BitBake find
+them? BitBake's error messaging helps you answer these types of
+questions and helps you better understand exactly what is going on.
+
+Following is the complete "Hello World" example.
+
+#.  **Create a Project Directory:** First, set up a directory for the
+    "Hello World" project. Here is how you can do so in your home
+    directory: ::
+
+      $ mkdir ~/hello
+      $ cd ~/hello
+
+    This is the directory that
+    BitBake will use to do all of its work. You can use this directory
+    to keep all the metafiles needed by BitBake. Having a project
+    directory is a good way to isolate your project.
+
+#.  **Run BitBake:** At this point, you have nothing but a project
+    directory. Run the ``bitbake`` command and see what it does: ::
+
+       $ bitbake
+       The BBPATH variable is not set and bitbake did not
+       find a conf/bblayers.conf file in the expected location.
+       Maybe you accidentally invoked bitbake from the wrong directory?
+       DEBUG: Removed the following variables from the environment:
+       GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,
+       GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,
+       XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,
+       MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,
+       GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,
+       XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,
+       _, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,
+       UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS
+
+    The majority of this output is specific to environment variables that
+    are not directly relevant to BitBake. However, the very first
+    message regarding the ``BBPATH`` variable and the
+    ``conf/bblayers.conf`` file is relevant.
+
+    When you run BitBake, it begins looking for metadata files. The
+    :term:`BBPATH` variable is what tells BitBake where
+    to look for those files. ``BBPATH`` is not set and you need to set
+    it. Without ``BBPATH``, BitBake cannot find any configuration files
+    (``.conf``) or recipe files (``.bb``) at all. BitBake also cannot
+    find the ``bitbake.conf`` file.
+
+#.  **Setting BBPATH:** For this example, you can set ``BBPATH`` in
+    the same manner that you set ``PATH`` earlier in the appendix. You
+    should realize, though, that it is much more flexible to set the
+    ``BBPATH`` variable up in a configuration file for each project.
+
+    From your shell, enter the following commands to set and export the
+    ``BBPATH`` variable: ::
+
+      $ BBPATH="projectdirectory"
+      $ export BBPATH
+
+    Use your actual project directory in the command. BitBake uses that
+    directory to find the metadata it needs for your project.
+
+    .. note::
+
+       When specifying your project directory, do not use the tilde
+       ("~") character as BitBake does not expand that character as the
+       shell would.
+
+#.  **Run BitBake:** Now that you have ``BBPATH`` defined, run the
+    ``bitbake`` command again: ::
+
+       $ bitbake
+       ERROR: Traceback (most recent call last):
+         File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
+           return func(fn, *args)
+         File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file
+           return bb.parse.handle(fn, data, include)
+         File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle
+           return h['handle'](fn, data, include)
+         File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle
+           abs_fn = resolve_file(fn, data)
+         File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file
+           raise IOError("file %s not found in %s" % (fn, bbpath))
+       IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello
+
+       ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello
+
+    This sample output shows that BitBake could not find the
+    ``conf/bitbake.conf`` file in the project directory. This file is
+    the first thing BitBake must find in order to build a target. And,
+    since the project directory for this example is empty, you need to
+    provide a ``conf/bitbake.conf`` file.
+
+#.  **Creating conf/bitbake.conf:** The ``conf/bitbake.conf`` includes
+    a number of configuration variables BitBake uses for metadata and
+    recipe files. For this example, you need to create the file in your
+    project directory and define some key BitBake variables. For more
+    information on the ``bitbake.conf`` file, see
+    http://git.openembedded.org/bitbake/tree/conf/bitbake.conf.
+
+    Use the following commands to create the ``conf`` directory in the
+    project directory: ::
+
+      $ mkdir conf
+
+    From within the ``conf`` directory,
+    use some editor to create the ``bitbake.conf`` so that it contains
+    the following: ::
+
+       PN  = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
+
+       TMPDIR  = "${TOPDIR}/tmp"
+       CACHE   = "${TMPDIR}/cache"
+       STAMP   = "${TMPDIR}/${PN}/stamps"
+       T       = "${TMPDIR}/${PN}/work"
+       B       = "${TMPDIR}/${PN}"
+
+    .. note::
+
+       Without a value for PN , the variables STAMP , T , and B , prevent more
+       than one recipe from working. You can fix this by either setting PN to
+       have a value similar to what OpenEmbedded and BitBake use in the default
+       bitbake.conf file (see previous example). Or, by manually updating each
+       recipe to set PN . You will also need to include PN as part of the STAMP
+       , T , and B variable definitions in the local.conf file.
+
+    The ``TMPDIR`` variable establishes a directory that BitBake uses
+    for build output and intermediate files other than the cached
+    information used by the
+    :ref:`bitbake-user-manual/bitbake-user-manual-execution:setscene`
+    process. Here, the ``TMPDIR`` directory is set to ``hello/tmp``.
+
+    .. tip::
+
+       You can always safely delete the tmp directory in order to rebuild a
+       BitBake target. The build process creates the directory for you when you
+       run BitBake.
+
+    For information about each of the other variables defined in this
+    example, check :term:`PN`, :term:`TOPDIR`, :term:`CACHE`, :term:`STAMP`,
+    :term:`T` or :term:`B` to take you to the definitions in the
+    glossary.
+
+#.  **Run BitBake:** After making sure that the ``conf/bitbake.conf`` file
+    exists, you can run the ``bitbake`` command again: ::
+
+       $ bitbake
+       ERROR: Traceback (most recent call last):
+         File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
+           return func(fn, *args)
+         File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
+           bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
+         File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
+           include(fn, file, lineno, d, "inherit")
+         File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
+           raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
+       ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
+
+       ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
+
+    In the sample output,
+    BitBake could not find the ``classes/base.bbclass`` file. You need
+    to create that file next.
+
+#.  **Creating classes/base.bbclass:** BitBake uses class files to
+    provide common code and functionality. The minimally required class
+    for BitBake is the ``classes/base.bbclass`` file. The ``base`` class
+    is implicitly inherited by every recipe. BitBake looks for the class
+    in the ``classes`` directory of the project (i.e ``hello/classes``
+    in this example).
+
+    Create the ``classes`` directory as follows: ::
+
+      $ cd $HOME/hello
+      $ mkdir classes
+
+    Move to the ``classes`` directory and then create the
+    ``base.bbclass`` file by inserting this single line: addtask build
+    The minimal task that BitBake runs is the ``do_build`` task. This is
+    all the example needs in order to build the project. Of course, the
+    ``base.bbclass`` can have much more depending on which build
+    environments BitBake is supporting.
+
+#.  **Run BitBake:** After making sure that the ``classes/base.bbclass``
+    file exists, you can run the ``bitbake`` command again: ::
+
+       $ bitbake
+       Nothing to do. Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
+
+    BitBake is finally reporting
+    no errors. However, you can see that it really does not have
+    anything to do. You need to create a recipe that gives BitBake
+    something to do.
+
+#.  **Creating a Layer:** While it is not really necessary for such a
+    small example, it is good practice to create a layer in which to
+    keep your code separate from the general metadata used by BitBake.
+    Thus, this example creates and uses a layer called "mylayer".
+
+    .. note::
+
+       You can find additional information on layers in the
+       ":ref:`bitbake-user-manual/bitbake-user-manual-intro:Layers`" section.
+
+    Minimally, you need a recipe file and a layer configuration file in
+    your layer. The configuration file needs to be in the ``conf``
+    directory inside the layer. Use these commands to set up the layer
+    and the ``conf`` directory: ::
+
+       $ cd $HOME
+       $ mkdir mylayer
+       $ cd mylayer
+       $ mkdir conf
+
+    Move to the ``conf`` directory and create a ``layer.conf`` file that has the
+    following: ::
+
+      BBPATH .= ":${LAYERDIR}"
+      BBFILES += "${LAYERDIR}/\*.bb"
+      BBFILE_COLLECTIONS += "mylayer"
+     `BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/"
+
+    For information on these variables, click on :term:`BBFILES`,
+    :term:`LAYERDIR`, :term:`BBFILE_COLLECTIONS` or :term:`BBFILE_PATTERN_mylayer <BBFILE_PATTERN>`
+    to go to the definitions in the glossary.
+
+    You need to create the recipe file next. Inside your layer at the
+    top-level, use an editor and create a recipe file named
+    ``printhello.bb`` that has the following: ::
+
+       DESCRIPTION = "Prints Hello World"
+       PN = 'printhello'
+       PV = '1'
+
+       python do_build() {
+          bb.plain("********************");
+          bb.plain("*                  *");
+          bb.plain("*  Hello, World!   *");
+          bb.plain("*                  *");
+          bb.plain("********************");
+       }
+
+    The recipe file simply provides
+    a description of the recipe, the name, version, and the ``do_build``
+    task, which prints out "Hello World" to the console. For more
+    information on :term:`DESCRIPTION`, :term:`PN` or :term:`PV`
+    follow the links to the glossary.
+
+#. **Run BitBake With a Target:** Now that a BitBake target exists, run
+    the command and provide that target: ::
+
+      $ cd $HOME/hello
+      $ bitbake printhello
+      ERROR: no recipe files to build, check your BBPATH and BBFILES?
+
+      Summary: There was 1 ERROR message shown, returning a non-zero exit code.
+
+    We have created the layer with the recipe and
+    the layer configuration file but it still seems that BitBake cannot
+    find the recipe. BitBake needs a ``conf/bblayers.conf`` that lists
+    the layers for the project. Without this file, BitBake cannot find
+    the recipe.
+
+#. **Creating conf/bblayers.conf:** BitBake uses the
+    ``conf/bblayers.conf`` file to locate layers needed for the project.
+    This file must reside in the ``conf`` directory of the project (i.e.
+    ``hello/conf`` for this example).
+
+    Set your working directory to the ``hello/conf`` directory and then
+    create the ``bblayers.conf`` file so that it contains the following: ::
+
+       BBLAYERS ?= " \
+           /home/<you>/mylayer \
+       "
+
+    You need to provide your own information for ``you`` in the file.
+
+#. **Run BitBake With a Target:** Now that you have supplied the
+    ``bblayers.conf`` file, run the ``bitbake`` command and provide the
+    target: ::
+
+       $ bitbake printhello
+       Parsing recipes: 100% |##################################################################################|
+       Time: 00:00:00
+       Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.
+       NOTE: Resolving any missing task queue dependencies
+       NOTE: Preparing RunQueue
+       NOTE: Executing RunQueue Tasks
+       ********************
+       *                  *
+       *  Hello, World!   *
+       *                  *
+       ********************
+       NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and all succeeded.
+
+    .. note::
+
+       After the first execution, re-running bitbake printhello again will not
+       result in a BitBake run that prints the same console output. The reason
+       for this is that the first time the printhello.bb recipe's do_build task
+       executes successfully, BitBake writes a stamp file for the task. Thus,
+       the next time you attempt to run the task using that same bitbake
+       command, BitBake notices the stamp and therefore determines that the task
+       does not need to be re-run. If you delete the tmp directory or run
+       bitbake -c clean printhello and then re-run the build, the "Hello,
+       World!" message will be printed again.

bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml

@@ -1,513 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<appendix id='hello-world-example'>
-    <title>Hello World Example</title>
-
-    <section id='bitbake-hello-world'>
-        <title>BitBake Hello World</title>
-
-        <para>
-            The simplest example commonly used to demonstrate any new
-            programming language or tool is the
-            "<ulink url="http://en.wikipedia.org/wiki/Hello_world_program">Hello World</ulink>"
-            example.
-            This appendix demonstrates, in tutorial form, Hello
-            World within the context of BitBake.
-            The tutorial describes how to create a new project
-            and the applicable metadata files necessary to allow
-            BitBake to build it.
-        </para>
-    </section>
-
-    <section id='example-obtaining-bitbake'>
-        <title>Obtaining BitBake</title>
-
-        <para>
-            See the
-            "<link linkend='obtaining-bitbake'>Obtaining BitBake</link>"
-            section for information on how to obtain BitBake.
-            Once you have the source code on your machine, the BitBake directory
-            appears as follows:
-            <literallayout class='monospaced'>
-     $ ls -al
-     total 100
-     drwxrwxr-x. 9 wmat wmat  4096 Jan 31 13:44 .
-     drwxrwxr-x. 3 wmat wmat  4096 Feb  4 10:45 ..
-     -rw-rw-r--. 1 wmat wmat   365 Nov 26 04:55 AUTHORS
-     drwxrwxr-x. 2 wmat wmat  4096 Nov 26 04:55 bin
-     drwxrwxr-x. 4 wmat wmat  4096 Jan 31 13:44 build
-     -rw-rw-r--. 1 wmat wmat 16501 Nov 26 04:55 ChangeLog
-     drwxrwxr-x. 2 wmat wmat  4096 Nov 26 04:55 classes
-     drwxrwxr-x. 2 wmat wmat  4096 Nov 26 04:55 conf
-     drwxrwxr-x. 3 wmat wmat  4096 Nov 26 04:55 contrib
-     -rw-rw-r--. 1 wmat wmat 17987 Nov 26 04:55 COPYING
-     drwxrwxr-x. 3 wmat wmat  4096 Nov 26 04:55 doc
-     -rw-rw-r--. 1 wmat wmat    69 Nov 26 04:55 .gitignore
-     -rw-rw-r--. 1 wmat wmat   849 Nov 26 04:55 HEADER
-     drwxrwxr-x. 5 wmat wmat  4096 Jan 31 13:44 lib
-     -rw-rw-r--. 1 wmat wmat   195 Nov 26 04:55 MANIFEST.in
-     -rw-rw-r--. 1 wmat wmat  2887 Nov 26 04:55 TODO
-            </literallayout>
-        </para>
-
-        <para>
-            At this point, you should have BitBake cloned to
-            a directory that matches the previous listing except for
-            dates and user names.
-        </para>
-    </section>
-
-    <section id='setting-up-the-bitbake-environment'>
-        <title>Setting Up the BitBake Environment</title>
-
-        <para>
-            First, you need to be sure that you can run BitBake.
-            Set your working directory to where your local BitBake
-            files are and run the following command:
-            <literallayout class='monospaced'>
-     $ ./bin/bitbake --version
-     BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0
-            </literallayout>
-            The console output tells you what version you are running.
-        </para>
-
-        <para>
-            The recommended method to run BitBake is from a directory of your
-            choice.
-            To be able to run BitBake from any directory, you need to add the
-            executable binary to your binary to your shell's environment
-            <filename>PATH</filename> variable.
-            First, look at your current <filename>PATH</filename> variable
-            by entering the following:
-            <literallayout class='monospaced'>
-     $ echo $PATH
-            </literallayout>
-            Next, add the directory location for the BitBake binary to the
-            <filename>PATH</filename>.
-            Here is an example that adds the
-            <filename>/home/scott-lenovo/bitbake/bin</filename> directory
-            to the front of the <filename>PATH</filename> variable:
-            <literallayout class='monospaced'>
-     $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH
-            </literallayout>
-            You should now be able to enter the <filename>bitbake</filename>
-            command from the command line while working from any directory.
-        </para>
-    </section>
-
-    <section id='the-hello-world-example'>
-        <title>The Hello World Example</title>
-
-        <para>
-            The overall goal of this exercise is to build a
-            complete "Hello World" example utilizing task and layer
-            concepts.
-            Because this is how modern projects such as OpenEmbedded and
-            the Yocto Project utilize BitBake, the example
-            provides an excellent starting point for understanding
-            BitBake.
-        </para>
-
-        <para>
-            To help you understand how to use BitBake to build targets,
-            the example starts with nothing but the <filename>bitbake</filename>
-            command, which causes BitBake to fail and report problems.
-            The example progresses by adding pieces to the build to
-            eventually conclude with a working, minimal "Hello World"
-            example.
-        </para>
-
-        <para>
-            While every attempt is made to explain what is happening during
-            the example, the descriptions cannot cover everything.
-            You can find further information throughout this manual.
-            Also, you can actively participate in the
-            <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'></ulink>
-            discussion mailing list about the BitBake build tool.
-        </para>
-
-        <note>
-            This example was inspired by and drew heavily from
-            <ulink url="http://www.mail-archive.com/yocto@yoctoproject.org/msg09379.html">Mailing List post - The BitBake equivalent of "Hello, World!"</ulink>.
-        </note>
-
-        <para>
-            As stated earlier, the goal of this example
-            is to eventually compile "Hello World".
-            However, it is unknown what BitBake needs and what you have
-            to provide in order to achieve that goal.
-            Recall that BitBake utilizes three types of metadata files:
-            <link linkend='configuration-files'>Configuration Files</link>,
-            <link linkend='classes'>Classes</link>, and
-            <link linkend='recipes'>Recipes</link>.
-            But where do they go?
-            How does BitBake find them?
-            BitBake's error messaging helps you answer these types of questions
-            and helps you better understand exactly what is going on.
-        </para>
-
-        <para>
-            Following is the complete "Hello World" example.
-        </para>
-
-        <orderedlist>
-            <listitem><para><emphasis>Create a Project Directory:</emphasis>
-                First, set up a directory for the "Hello World" project.
-                Here is how you can do so in your home directory:
-                <literallayout class='monospaced'>
-     $ mkdir ~/hello
-     $ cd ~/hello
-                </literallayout>
-                This is the directory that BitBake will use to do all of
-                its work.
-                You can use this directory to keep all the metafiles needed
-                by BitBake.
-                Having a project directory is a good way to isolate your
-                project.
-                </para></listitem>
-            <listitem><para><emphasis>Run BitBake:</emphasis>
-                At this point, you have nothing but a project directory.
-                Run the <filename>bitbake</filename> command and see what
-                it does:
-                <literallayout class='monospaced'>
-     $ bitbake
-     The BBPATH variable is not set and bitbake did not
-     find a conf/bblayers.conf file in the expected location.
-     Maybe you accidentally invoked bitbake from the wrong directory?
-     DEBUG: Removed the following variables from the environment:
-     GNOME_DESKTOP_SESSION_ID, XDG_CURRENT_DESKTOP,
-     GNOME_KEYRING_CONTROL, DISPLAY, SSH_AGENT_PID, LANG, no_proxy,
-     XDG_SESSION_PATH, XAUTHORITY, SESSION_MANAGER, SHLVL,
-     MANDATORY_PATH, COMPIZ_CONFIG_PROFILE, WINDOWID, EDITOR,
-     GPG_AGENT_INFO, SSH_AUTH_SOCK, GDMSESSION, GNOME_KEYRING_PID,
-     XDG_SEAT_PATH, XDG_CONFIG_DIRS, LESSOPEN, DBUS_SESSION_BUS_ADDRESS,
-     _, XDG_SESSION_COOKIE, DESKTOP_SESSION, LESSCLOSE, DEFAULTS_PATH,
-     UBUNTU_MENUPROXY, OLDPWD, XDG_DATA_DIRS, COLORTERM, LS_COLORS
-                </literallayout>
-                The majority of this output is specific to environment variables
-                that are not directly relevant to BitBake.
-                However, the very first message regarding the
-                <filename>BBPATH</filename> variable and the
-                <filename>conf/bblayers.conf</filename> file
-                is relevant.</para>
-                <para>
-                When you run BitBake, it begins looking for metadata files.
-                The
-                <link linkend='var-bb-BBPATH'><filename>BBPATH</filename></link>
-                variable is what tells BitBake where to look for those files.
-                <filename>BBPATH</filename> is not set and you need to set it.
-                Without <filename>BBPATH</filename>, BitBake cannot
-                find any configuration files (<filename>.conf</filename>)
-                or recipe files (<filename>.bb</filename>) at all.
-                BitBake also cannot find the <filename>bitbake.conf</filename>
-                file.
-                </para></listitem>
-            <listitem><para><emphasis>Setting <filename>BBPATH</filename>:</emphasis>
-                For this example, you can set <filename>BBPATH</filename>
-                in the same manner that you set <filename>PATH</filename>
-                earlier in the appendix.
-                You should realize, though, that it is much more flexible to set the
-                <filename>BBPATH</filename> variable up in a configuration
-                file for each project.</para>
-                <para>From your shell, enter the following commands to set and
-                export the <filename>BBPATH</filename> variable:
-                <literallayout class='monospaced'>
-     $ BBPATH="<replaceable>projectdirectory</replaceable>"
-     $ export BBPATH
-                </literallayout>
-                Use your actual project directory in the command.
-                BitBake uses that directory to find the metadata it needs for
-                your project.
-                <note>
-                    When specifying your project directory, do not use the
-                    tilde ("~") character as BitBake does not expand that character
-                    as the shell would.
-                </note>
-                </para></listitem>
-            <listitem><para><emphasis>Run BitBake:</emphasis>
-                Now that you have <filename>BBPATH</filename> defined, run
-                the <filename>bitbake</filename> command again:
-                <literallayout class='monospaced'>
-     $ bitbake
-     ERROR: Traceback (most recent call last):
-       File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
-         return func(fn, *args)
-       File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 173, in parse_config_file
-         return bb.parse.handle(fn, data, include)
-       File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 99, in handle
-         return h['handle'](fn, data, include)
-       File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 120, in handle
-         abs_fn = resolve_file(fn, data)
-       File "/home/scott-lenovo/bitbake/lib/bb/parse/__init__.py", line 117, in resolve_file
-         raise IOError("file %s not found in %s" % (fn, bbpath))
-     IOError: file conf/bitbake.conf not found in /home/scott-lenovo/hello
-
-     ERROR: Unable to parse conf/bitbake.conf: file conf/bitbake.conf not found in /home/scott-lenovo/hello
-                </literallayout>
-                This sample output shows that BitBake could not find the
-                <filename>conf/bitbake.conf</filename> file in the project
-                directory.
-                This file is the first thing BitBake must find in order
-                to build a target.
-                And, since the project directory for this example is
-                empty, you need to provide a <filename>conf/bitbake.conf</filename>
-                file.
-                </para></listitem>
-            <listitem><para><emphasis>Creating <filename>conf/bitbake.conf</filename>:</emphasis>
-                The <filename>conf/bitbake.conf</filename> includes a number of
-                configuration variables BitBake uses for metadata and recipe
-                files.
-                For this example, you need to create the file in your project directory
-                and define some key BitBake variables.
-                For more information on the <filename>bitbake.conf</filename> file,
-                see
-                <ulink url='http://git.openembedded.org/bitbake/tree/conf/bitbake.conf'></ulink>.
-                </para>
-                <para>Use the following commands to create the <filename>conf</filename>
-                directory in the project directory:
-                <literallayout class='monospaced'>
-     $ mkdir conf
-                </literallayout>
-                From within the <filename>conf</filename> directory, use
-                some editor to create the <filename>bitbake.conf</filename>
-                so that it contains the following:
-                <literallayout class='monospaced'>
-     <link linkend='var-bb-PN'>PN</link>  = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
-                </literallayout>
-                <literallayout class='monospaced'>
-     TMPDIR  = "${<link linkend='var-bb-TOPDIR'>TOPDIR</link>}/tmp"
-     <link linkend='var-bb-CACHE'>CACHE</link>   = "${TMPDIR}/cache"
-     <link linkend='var-bb-STAMP'>STAMP</link>   = "${TMPDIR}/${PN}/stamps"
-     <link linkend='var-bb-T'>T</link>       = "${TMPDIR}/${PN}/work"
-     <link linkend='var-bb-B'>B</link>       = "${TMPDIR}/${PN}"
-                </literallayout>
-                <note>
-                    Without a value for <filename>PN</filename>, the
-                    variables <filename>STAMP</filename>,
-                    <filename>T</filename>, and <filename>B</filename>,
-                    prevent more than one recipe from working. You can fix
-                    this by either setting <filename>PN</filename> to have
-                    a value similar to what OpenEmbedded and BitBake use
-                    in the default <filename>bitbake.conf</filename> file
-                    (see previous example). Or, by manually updating each
-                    recipe to set <filename>PN</filename>. You will also
-                    need to include <filename>PN</filename> as part of the
-                    <filename>STAMP</filename>, <filename>T</filename>, and
-                    <filename>B</filename> variable definitions in the
-                    <filename>local.conf</filename> file.
-                </note>
-                The <filename>TMPDIR</filename> variable establishes a directory
-                that BitBake uses for build output and intermediate files other
-                than the cached information used by the
-                <link linkend='setscene'>Setscene</link> process.
-                Here, the <filename>TMPDIR</filename> directory is set to
-                <filename>hello/tmp</filename>.
-                <note><title>Tip</title>
-                    You can always safely delete the <filename>tmp</filename>
-                    directory in order to rebuild a BitBake target.
-                    The build process creates the directory for you
-                    when you run BitBake.
-                </note></para>
-                <para>For information about each of the other variables defined in this
-                example, click on the links to take you to the definitions in
-                the glossary.
-                </para></listitem>
-            <listitem><para><emphasis>Run BitBake:</emphasis>
-                After making sure that the <filename>conf/bitbake.conf</filename>
-                file exists, you can run the <filename>bitbake</filename>
-                command again:
-                <literallayout class='monospaced'>
-     $ bitbake
-     ERROR: Traceback (most recent call last):
-       File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 163, in wrapped
-         return func(fn, *args)
-       File "/home/scott-lenovo/bitbake/lib/bb/cookerdata.py", line 177, in _inherit
-         bb.parse.BBHandler.inherit(bbclass, "configuration INHERITs", 0, data)
-       File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/BBHandler.py", line 92, in inherit
-         include(fn, file, lineno, d, "inherit")
-       File "/home/scott-lenovo/bitbake/lib/bb/parse/parse_py/ConfHandler.py", line 100, in include
-         raise ParseError("Could not %(error_out)s file %(fn)s" % vars(), oldfn, lineno)
-     ParseError: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
-
-     ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inherit file classes/base.bbclass
-                </literallayout>
-                In the sample output, BitBake could not find the
-                <filename>classes/base.bbclass</filename> file.
-                You need to create that file next.
-                </para></listitem>
-            <listitem><para><emphasis>Creating <filename>classes/base.bbclass</filename>:</emphasis>
-                BitBake uses class files to provide common code and functionality.
-                The minimally required class for BitBake is the
-                <filename>classes/base.bbclass</filename> file.
-                The <filename>base</filename> class is implicitly inherited by
-                every recipe.
-                BitBake looks for the class in the <filename>classes</filename>
-                directory of the project (i.e <filename>hello/classes</filename>
-                in this example).
-                </para>
-                <para>Create the <filename>classes</filename> directory as follows:
-                <literallayout class='monospaced'>
-     $ cd $HOME/hello
-     $ mkdir classes
-                </literallayout>
-                Move to the <filename>classes</filename> directory and then
-                create the <filename>base.bbclass</filename> file by inserting
-                this single line:
-                <literallayout class='monospaced'>
-     addtask build
-                </literallayout>
-                The minimal task that BitBake runs is the
-                <filename>do_build</filename> task.
-                This is all the example needs in order to build the project.
-                Of course, the <filename>base.bbclass</filename> can have much
-                more depending on which build environments BitBake is
-                supporting.
-                </para></listitem>
-            <listitem><para><emphasis>Run BitBake:</emphasis>
-                After making sure that the <filename>classes/base.bbclass</filename>
-                file exists, you can run the <filename>bitbake</filename>
-                command again:
-                <literallayout class='monospaced'>
-     $ bitbake
-     Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.
-                </literallayout>
-                BitBake is finally reporting no errors.
-                However, you can see that it really does not have anything
-                to do.
-                You need to create a recipe that gives BitBake something to do.
-                </para></listitem>
-            <listitem><para><emphasis>Creating a Layer:</emphasis>
-                While it is not really necessary for such a small example,
-                it is good practice to create a layer in which to keep your
-                code separate from the general metadata used by BitBake.
-                Thus, this example creates and uses a layer called "mylayer".
-                <note>
-                    You can find additional information on layers in the
-                    "<link linkend='layers'>Layers</link>" section.
-                </note></para>
-
-                <para>Minimally, you need a recipe file and a layer configuration
-                file in your layer.
-                The configuration file needs to be in the <filename>conf</filename>
-                directory inside the layer.
-                Use these commands to set up the layer and the <filename>conf</filename>
-                directory:
-                <literallayout class='monospaced'>
-     $ cd $HOME
-     $ mkdir mylayer
-     $ cd mylayer
-     $ mkdir conf
-                </literallayout>
-                Move to the <filename>conf</filename> directory and create a
-                <filename>layer.conf</filename> file that has the following:
-                <literallayout class='monospaced'>
-     BBPATH .= ":${<link linkend='var-bb-LAYERDIR'>LAYERDIR</link>}"
-
-     <link linkend='var-bb-BBFILES'>BBFILES</link> += "${LAYERDIR}/*.bb"
-
-     <link linkend='var-bb-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link> += "mylayer"
-     <link linkend='var-bb-BBFILE_PATTERN'>BBFILE_PATTERN_mylayer</link> := "^${LAYERDIR_RE}/"
-                </literallayout>
-                For information on these variables, click the links
-                to go to the definitions in the glossary.</para>
-                <para>You need to create the recipe file next.
-                Inside your layer at the top-level, use an editor and create
-                a recipe file named <filename>printhello.bb</filename> that
-                has the following:
-                <literallayout class='monospaced'>
-     <link linkend='var-bb-DESCRIPTION'>DESCRIPTION</link> = "Prints Hello World"
-     <link linkend='var-bb-PN'>PN</link> = 'printhello'
-     <link linkend='var-bb-PV'>PV</link> = '1'
-
-     python do_build() {
-        bb.plain("********************");
-        bb.plain("*                  *");
-        bb.plain("*  Hello, World!   *");
-        bb.plain("*                  *");
-        bb.plain("********************");
-     }
-                </literallayout>
-                The recipe file simply provides a description of the
-                recipe, the name, version, and the <filename>do_build</filename>
-                task, which prints out "Hello World" to the console.
-                For more information on these variables, follow the links
-                to the glossary.
-                </para></listitem>
-            <listitem><para><emphasis>Run BitBake With a Target:</emphasis>
-                Now that a BitBake target exists, run the command and provide
-                that target:
-                <literallayout class='monospaced'>
-     $ cd $HOME/hello
-     $ bitbake printhello
-     ERROR: no recipe files to build, check your BBPATH and BBFILES?
-
-     Summary: There was 1 ERROR message shown, returning a non-zero exit code.
-                </literallayout>
-                We have created the layer with the recipe and the layer
-                configuration file but it still seems that BitBake cannot
-                find the recipe.
-                BitBake needs a <filename>conf/bblayers.conf</filename> that
-                lists the layers for the project.
-                Without this file, BitBake cannot find the recipe.
-                </para></listitem>
-            <listitem><para><emphasis>Creating <filename>conf/bblayers.conf</filename>:</emphasis>
-                BitBake uses the <filename>conf/bblayers.conf</filename> file
-                to locate layers needed for the project.
-                This file must reside in the <filename>conf</filename> directory
-                of the project (i.e. <filename>hello/conf</filename> for this
-                example).</para>
-                <para>Set your working directory to the <filename>hello/conf</filename>
-                directory and then create the <filename>bblayers.conf</filename>
-                file so that it contains the following:
-                <literallayout class='monospaced'>
-     BBLAYERS ?= " \
-       /home/&lt;you&gt;/mylayer \
-       "
-                </literallayout>
-                You need to provide your own information for
-                <filename>you</filename> in the file.
-                </para></listitem>
-            <listitem><para><emphasis>Run BitBake With a Target:</emphasis>
-                Now that you have supplied the <filename>bblayers.conf</filename>
-                file, run the <filename>bitbake</filename> command and provide
-                the target:
-                <literallayout class='monospaced'>
-     $ bitbake printhello
-     Parsing recipes: 100% |##################################################################################|
-     Time: 00:00:00
-     Parsing of 1 .bb files complete (0 cached, 1 parsed). 1 targets, 0 skipped, 0 masked, 0 errors.
-     NOTE: Resolving any missing task queue dependencies
-     NOTE: Preparing RunQueue
-     NOTE: Executing RunQueue Tasks
-     ********************
-     *                  *
-     *  Hello, World!   *
-     *                  *
-     ********************
-     NOTE: Tasks Summary: Attempted 1 tasks of which 0 didn't need to be rerun and all succeeded.
-                </literallayout>
-                BitBake finds the <filename>printhello</filename> recipe and
-                successfully runs the task.
-                <note>
-                    After the first execution, re-running
-                    <filename>bitbake printhello</filename> again will not
-                    result in a BitBake run that prints the same console
-                    output.
-                    The reason for this is that the first time the
-                    <filename>printhello.bb</filename> recipe's
-                    <filename>do_build</filename> task executes
-                    successfully, BitBake writes a stamp file for the task.
-                    Thus, the next time you attempt to run the task
-                    using that same <filename>bitbake</filename> command,
-                    BitBake notices the stamp and therefore determines
-                    that the task does not need to be re-run.
-                    If you delete the <filename>tmp</filename> directory
-                    or run <filename>bitbake -c clean printhello</filename>
-                    and then re-run the build, the "Hello, World!" message will
-                    be printed again.
-                </note>
-                </para></listitem>
-        </orderedlist>
-    </section>
-</appendix>

bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst

@@ -0,0 +1,651 @@
+.. SPDX-License-Identifier: CC-BY-2.5
+
+========
+Overview
+========
+
+|
+
+Welcome to the BitBake User Manual. This manual provides information on
+the BitBake tool. The information attempts to be as independent as
+possible regarding systems that use BitBake, such as OpenEmbedded and
+the Yocto Project. In some cases, scenarios or examples within the
+context of a build system are used in the manual to help with
+understanding. For these cases, the manual clearly states the context.
+
+.. _intro:
+
+Introduction
+============
+
+Fundamentally, BitBake is a generic task execution engine that allows
+shell and Python tasks to be run efficiently and in parallel while
+working within complex inter-task dependency constraints. One of
+BitBake's main users, OpenEmbedded, takes this core and builds embedded
+Linux software stacks using a task-oriented approach.
+
+Conceptually, BitBake is similar to GNU Make in some regards but has
+significant differences:
+
+-  BitBake executes tasks according to provided metadata that builds up
+   the tasks. Metadata is stored in recipe (``.bb``) and related recipe
+   "append" (``.bbappend``) files, configuration (``.conf``) and
+   underlying include (``.inc``) files, and in class (``.bbclass``)
+   files. The metadata provides BitBake with instructions on what tasks
+   to run and the dependencies between those tasks.
+
+-  BitBake includes a fetcher library for obtaining source code from
+   various places such as local files, source control systems, or
+   websites.
+
+-  The instructions for each unit to be built (e.g. a piece of software)
+   are known as "recipe" files and contain all the information about the
+   unit (dependencies, source file locations, checksums, description and
+   so on).
+
+-  BitBake includes a client/server abstraction and can be used from a
+   command line or used as a service over XML-RPC and has several
+   different user interfaces.
+
+History and Goals
+=================
+
+BitBake was originally a part of the OpenEmbedded project. It was
+inspired by the Portage package management system used by the Gentoo
+Linux distribution. On December 7, 2004, OpenEmbedded project team
+member Chris Larson split the project into two distinct pieces:
+
+-  BitBake, a generic task executor
+
+-  OpenEmbedded, a metadata set utilized by BitBake
+
+Today, BitBake is the primary basis of the
+`OpenEmbedded <http://www.openembedded.org/>`__ project, which is being
+used to build and maintain Linux distributions such as the `Angstrom
+Distribution <http://www.angstrom-distribution.org/>`__, and which is
+also being used as the build tool for Linux projects such as the `Yocto
+Project <http://www.yoctoproject.org>`__.
+
+Prior to BitBake, no other build tool adequately met the needs of an
+aspiring embedded Linux distribution. All of the build systems used by
+traditional desktop Linux distributions lacked important functionality,
+and none of the ad hoc Buildroot-based systems, prevalent in the
+embedded space, were scalable or maintainable.
+
+Some important original goals for BitBake were:
+
+-  Handle cross-compilation.
+
+-  Handle inter-package dependencies (build time on target architecture,
+   build time on native architecture, and runtime).
+
+-  Support running any number of tasks within a given package,
+   including, but not limited to, fetching upstream sources, unpacking
+   them, patching them, configuring them, and so forth.
+
+-  Be Linux distribution agnostic for both build and target systems.
+
+-  Be architecture agnostic.
+
+-  Support multiple build and target operating systems (e.g. Cygwin, the
+   BSDs, and so forth).
+
+-  Be self-contained, rather than tightly integrated into the build
+   machine's root filesystem.
+
+-  Handle conditional metadata on the target architecture, operating
+   system, distribution, and machine.
+
+-  Be easy to use the tools to supply local metadata and packages
+   against which to operate.
+
+-  Be easy to use BitBake to collaborate between multiple projects for
+   their builds.
+
+-  Provide an inheritance mechanism to share common metadata between
+   many packages.
+
+Over time it became apparent that some further requirements were
+necessary:
+
+-  Handle variants of a base recipe (e.g. native, sdk, and multilib).
+
+-  Split metadata into layers and allow layers to enhance or override
+   other layers.
+
+-  Allow representation of a given set of input variables to a task as a
+   checksum. Based on that checksum, allow acceleration of builds with
+   prebuilt components.
+
+BitBake satisfies all the original requirements and many more with
+extensions being made to the basic functionality to reflect the
+additional requirements. Flexibility and power have always been the
+priorities. BitBake is highly extensible and supports embedded Python
+code and execution of any arbitrary tasks.
+
+.. _Concepts:
+
+Concepts
+========
+
+BitBake is a program written in the Python language. At the highest
+level, BitBake interprets metadata, decides what tasks are required to
+run, and executes those tasks. Similar to GNU Make, BitBake controls how
+software is built. GNU Make achieves its control through "makefiles",
+while BitBake uses "recipes".
+
+BitBake extends the capabilities of a simple tool like GNU Make by
+allowing for the definition of much more complex tasks, such as
+assembling entire embedded Linux distributions.
+
+The remainder of this section introduces several concepts that should be
+understood in order to better leverage the power of BitBake.
+
+Recipes
+-------
+
+BitBake Recipes, which are denoted by the file extension ``.bb``, are
+the most basic metadata files. These recipe files provide BitBake with
+the following:
+
+-  Descriptive information about the package (author, homepage, license,
+   and so on)
+
+-  The version of the recipe
+
+-  Existing dependencies (both build and runtime dependencies)
+
+-  Where the source code resides and how to fetch it
+
+-  Whether the source code requires any patches, where to find them, and
+   how to apply them
+
+-  How to configure and compile the source code
+
+-  How to assemble the generated artifacts into one or more installable
+   packages
+
+-  Where on the target machine to install the package or packages
+   created
+
+Within the context of BitBake, or any project utilizing BitBake as its
+build system, files with the ``.bb`` extension are referred to as
+recipes.
+
+.. note::
+
+   The term "package" is also commonly used to describe recipes.
+   However, since the same word is used to describe packaged output from
+   a project, it is best to maintain a single descriptive term -
+   "recipes". Put another way, a single "recipe" file is quite capable
+   of generating a number of related but separately installable
+   "packages". In fact, that ability is fairly common.
+
+Configuration Files
+-------------------
+
+Configuration files, which are denoted by the ``.conf`` extension,
+define various configuration variables that govern the project's build
+process. These files fall into several areas that define machine
+configuration, distribution configuration, possible compiler tuning,
+general common configuration, and user configuration. The main
+configuration file is the sample ``bitbake.conf`` file, which is located
+within the BitBake source tree ``conf`` directory.
+
+Classes
+-------
+
+Class files, which are denoted by the ``.bbclass`` extension, contain
+information that is useful to share between metadata files. The BitBake
+source tree currently comes with one class metadata file called
+``base.bbclass``. You can find this file in the ``classes`` directory.
+The ``base.bbclass`` class files is special since it is always included
+automatically for all recipes and classes. This class contains
+definitions for standard basic tasks such as fetching, unpacking,
+configuring (empty by default), compiling (runs any Makefile present),
+installing (empty by default) and packaging (empty by default). These
+tasks are often overridden or extended by other classes added during the
+project development process.
+
+Layers
+------
+
+Layers allow you to isolate different types of customizations from each
+other. While you might find it tempting to keep everything in one layer
+when working on a single project, the more modular your metadata, the
+easier it is to cope with future changes.
+
+To illustrate how you can use layers to keep things modular, consider
+customizations you might make to support a specific target machine.
+These types of customizations typically reside in a special layer,
+rather than a general layer, called a Board Support Package (BSP) layer.
+Furthermore, the machine customizations should be isolated from recipes
+and metadata that support a new GUI environment, for example. This
+situation gives you a couple of layers: one for the machine
+configurations and one for the GUI environment. It is important to
+understand, however, that the BSP layer can still make machine-specific
+additions to recipes within the GUI environment layer without polluting
+the GUI layer itself with those machine-specific changes. You can
+accomplish this through a recipe that is a BitBake append
+(``.bbappend``) file.
+
+.. _append-bbappend-files:
+
+Append Files
+------------
+
+Append files, which are files that have the ``.bbappend`` file
+extension, extend or override information in an existing recipe file.
+
+BitBake expects every append file to have a corresponding recipe file.
+Furthermore, the append file and corresponding recipe file must use the
+same root filename. The filenames can differ only in the file type
+suffix used (e.g. ``formfactor_0.0.bb`` and
+``formfactor_0.0.bbappend``).
+
+Information in append files extends or overrides the information in the
+underlying, similarly-named recipe files.
+
+When you name an append file, you can use the "``%``" wildcard character
+to allow for matching recipe names. For example, suppose you have an
+append file named as follows: ::
+
+  busybox_1.21.%.bbappend
+
+That append file
+would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So,
+the append file would match the following recipe names: ::
+
+  busybox_1.21.1.bb
+  busybox_1.21.2.bb
+  busybox_1.21.3.bb
+
+.. note::
+
+   The use of the " % " character is limited in that it only works directly in
+   front of the .bbappend portion of the append file's name. You cannot use the
+   wildcard character in any other location of the name.
+
+If the ``busybox`` recipe was updated to ``busybox_1.3.0.bb``, the
+append name would not match. However, if you named the append file
+``busybox_1.%.bbappend``, then you would have a match.
+
+In the most general case, you could name the append file something as
+simple as ``busybox_%.bbappend`` to be entirely version independent.
+
+Obtaining BitBake
+=================
+
+You can obtain BitBake several different ways:
+
+-  **Cloning BitBake:** Using Git to clone the BitBake source code
+   repository is the recommended method for obtaining BitBake. Cloning
+   the repository makes it easy to get bug fixes and have access to
+   stable branches and the master branch. Once you have cloned BitBake,
+   you should use the latest stable branch for development since the
+   master branch is for BitBake development and might contain less
+   stable changes.
+
+   You usually need a version of BitBake that matches the metadata you
+   are using. The metadata is generally backwards compatible but not
+   forward compatible.
+
+   Here is an example that clones the BitBake repository: ::
+
+     $ git clone git://git.openembedded.org/bitbake
+
+   This command clones the BitBake
+   Git repository into a directory called ``bitbake``. Alternatively,
+   you can designate a directory after the ``git clone`` command if you
+   want to call the new directory something other than ``bitbake``. Here
+   is an example that names the directory ``bbdev``: ::
+
+     $ git clone git://git.openembedded.org/bitbake bbdev
+
+-  **Installation using your Distribution Package Management System:**
+   This method is not recommended because the BitBake version that is
+   provided by your distribution, in most cases, is several releases
+   behind a snapshot of the BitBake repository.
+
+-  **Taking a snapshot of BitBake:** Downloading a snapshot of BitBake
+   from the source code repository gives you access to a known branch or
+   release of BitBake.
+
+      .. note::
+
+         Cloning the Git repository, as described earlier, is the preferred
+         method for getting BitBake. Cloning the repository makes it easier
+         to update as patches are added to the stable branches.
+
+   The following example downloads a snapshot of BitBake version 1.17.0: ::
+
+     $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
+     $ tar zxpvf bitbake-1.17.0.tar.gz
+
+   After extraction of the tarball using
+   the tar utility, you have a directory entitled ``bitbake-1.17.0``.
+
+-  **Using the BitBake that Comes With Your Build Checkout:** A final
+   possibility for getting a copy of BitBake is that it already comes
+   with your checkout of a larger BitBake-based build system, such as
+   Poky. Rather than manually checking out individual layers and gluing
+   them together yourself, you can check out an entire build system. The
+   checkout will already include a version of BitBake that has been
+   thoroughly tested for compatibility with the other components. For
+   information on how to check out a particular BitBake-based build
+   system, consult that build system's supporting documentation.
+
+.. _bitbake-user-manual-command:
+
+The BitBake Command
+===================
+
+The ``bitbake`` command is the primary interface to the BitBake tool.
+This section presents the BitBake command syntax and provides several
+execution examples.
+
+Usage and syntax
+----------------
+
+Following is the usage and syntax for BitBake: ::
+
+   $ bitbake -h
+   Usage: bitbake [options] [recipename/target recipe:do_task ...]
+
+       Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
+       It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
+       will provide the layer, BBFILES and other configuration information.
+
+   Options:
+     --version             show program's version number and exit
+     -h, --help            show this help message and exit
+     -b BUILDFILE, --buildfile=BUILDFILE
+                           Execute tasks from a specific .bb recipe directly.
+                           WARNING: Does not handle any dependencies from other
+                           recipes.
+     -k, --continue        Continue as much as possible after an error. While the
+                           target that failed and anything depending on it cannot
+                           be built, as much as possible will be built before
+                           stopping.
+     -f, --force           Force the specified targets/task to run (invalidating
+                           any existing stamp file).
+     -c CMD, --cmd=CMD     Specify the task to execute. The exact options
+                           available depend on the metadata. Some examples might
+                           be 'compile' or 'populate_sysroot' or 'listtasks' may
+                           give a list of the tasks available.
+     -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
+                           Invalidate the stamp for the specified task such as
+                           'compile' and then run the default task for the
+                           specified target(s).
+     -r PREFILE, --read=PREFILE
+                           Read the specified file before bitbake.conf.
+     -R POSTFILE, --postread=POSTFILE
+                           Read the specified file after bitbake.conf.
+     -v, --verbose         Enable tracing of shell tasks (with 'set -x'). Also
+                           print bb.note(...) messages to stdout (in addition to
+                           writing them to ${T}/log.do_&lt;task&gt;).
+     -D, --debug           Increase the debug level. You can specify this more
+                           than once. -D sets the debug level to 1, where only
+                           bb.debug(1, ...) messages are printed to stdout; -DD
+                           sets the debug level to 2, where both bb.debug(1, ...)
+                           and bb.debug(2, ...) messages are printed; etc.
+                           Without -D, no debug messages are printed. Note that
+                           -D only affects output to stdout. All debug messages
+                           are written to ${T}/log.do_taskname, regardless of the
+                           debug level.
+     -q, --quiet           Output less log message data to the terminal. You can
+                           specify this more than once.
+     -n, --dry-run         Don't execute, just go through the motions.
+     -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
+                           Dump out the signature construction information, with
+                           no task execution. The SIGNATURE_HANDLER parameter is
+                           passed to the handler. Two common values are none and
+                           printdiff but the handler may define more/less. none
+                           means only dump the signature, printdiff means compare
+                           the dumped signature with the cached one.
+     -p, --parse-only      Quit after parsing the BB recipes.
+     -s, --show-versions   Show current and preferred versions of all recipes.
+     -e, --environment     Show the global or per-recipe environment complete
+                           with information about where variables were
+                           set/changed.
+     -g, --graphviz        Save dependency tree information for the specified
+                           targets in the dot syntax.
+     -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
+                           Assume these dependencies don't exist and are already
+                           provided (equivalent to ASSUME_PROVIDED). Useful to
+                           make dependency graphs more appealing
+     -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
+                           Show debug logging for the specified logging domains
+     -P, --profile         Profile the command and save reports.
+     -u UI, --ui=UI        The user interface to use (knotty, ncurses or taskexp
+                           - default knotty).
+     --token=XMLRPCTOKEN   Specify the connection token to be used when
+                           connecting to a remote server.
+     --revisions-changed   Set the exit code depending on whether upstream
+                           floating revisions have changed or not.
+     --server-only         Run bitbake without a UI, only starting a server
+                           (cooker) process.
+     -B BIND, --bind=BIND  The name/address for the bitbake xmlrpc server to bind
+                           to.
+     -T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT
+                           Set timeout to unload bitbake server due to
+                           inactivity, set to -1 means no unload, default:
+                           Environment variable BB_SERVER_TIMEOUT.
+     --no-setscene         Do not run any setscene tasks. sstate will be ignored
+                           and everything needed, built.
+     --setscene-only       Only run setscene tasks, don't run any real tasks.
+     --remote-server=REMOTE_SERVER
+                           Connect to the specified server.
+     -m, --kill-server     Terminate any running bitbake server.
+     --observe-only        Connect to a server as an observing-only client.
+     --status-only         Check the status of the remote bitbake server.
+     -w WRITEEVENTLOG, --write-log=WRITEEVENTLOG
+                           Writes the event log of the build to a bitbake event
+                           json file. Use '' (empty string) to assign the name
+                           automatically.
+     --runall=RUNALL       Run the specified task for any recipe in the taskgraph
+                           of the specified target (even if it wouldn't otherwise
+                           have run).
+     --runonly=RUNONLY     Run only the specified task within the taskgraph of
+                           the specified targets (and any task dependencies those
+                           tasks may have).
+
+.. _bitbake-examples:
+
+Examples
+--------
+
+This section presents some examples showing how to use BitBake.
+
+.. _example-executing-a-task-against-a-single-recipe:
+
+Executing a Task Against a Single Recipe
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Executing tasks for a single recipe file is relatively simple. You
+specify the file in question, and BitBake parses it and executes the
+specified task. If you do not specify a task, BitBake executes the
+default task, which is "build". BitBake obeys inter-task dependencies
+when doing so.
+
+The following command runs the build task, which is the default task, on
+the ``foo_1.0.bb`` recipe file: ::
+
+  $ bitbake -b foo_1.0.bb
+
+The following command runs the clean task on the ``foo.bb`` recipe file: ::
+
+  $ bitbake -b foo.bb -c clean
+
+.. note::
+
+   The "-b" option explicitly does not handle recipe dependencies. Other
+   than for debugging purposes, it is instead recommended that you use
+   the syntax presented in the next section.
+
+Executing Tasks Against a Set of Recipe Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are a number of additional complexities introduced when one wants
+to manage multiple ``.bb`` files. Clearly there needs to be a way to
+tell BitBake what files are available and, of those, which you want to
+execute. There also needs to be a way for each recipe to express its
+dependencies, both for build-time and runtime. There must be a way for
+you to express recipe preferences when multiple recipes provide the same
+functionality, or when there are multiple versions of a recipe.
+
+The ``bitbake`` command, when not using "--buildfile" or "-b" only
+accepts a "PROVIDES". You cannot provide anything else. By default, a
+recipe file generally "PROVIDES" its "packagename" as shown in the
+following example: ::
+
+  $ bitbake foo
+
+This next example "PROVIDES" the
+package name and also uses the "-c" option to tell BitBake to just
+execute the ``do_clean`` task: ::
+
+  $ bitbake -c clean foo
+
+Executing a List of Task and Recipe Combinations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The BitBake command line supports specifying different tasks for
+individual targets when you specify multiple targets. For example,
+suppose you had two targets (or recipes) ``myfirstrecipe`` and
+``mysecondrecipe`` and you needed BitBake to run ``taskA`` for the first
+recipe and ``taskB`` for the second recipe: ::
+
+  $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB
+
+Generating Dependency Graphs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+BitBake is able to generate dependency graphs using the ``dot`` syntax.
+You can convert these graphs into images using the ``dot`` tool from
+`Graphviz <http://www.graphviz.org>`__.
+
+When you generate a dependency graph, BitBake writes two files to the
+current working directory:
+
+-  ``task-depends.dot``: Shows dependencies between tasks. These
+   dependencies match BitBake's internal task execution list.
+
+-  ``pn-buildlist``: Shows a simple list of targets that are to be
+   built.
+
+To stop depending on common depends, use the "-I" depend option and
+BitBake omits them from the graph. Leaving this information out can
+produce more readable graphs. This way, you can remove from the graph
+``DEPENDS`` from inherited classes such as ``base.bbclass``.
+
+Here are two examples that create dependency graphs. The second example
+omits depends common in OpenEmbedded from the graph: ::
+
+  $ bitbake -g foo
+
+  $ bitbake -g -I virtual/kernel -I eglibc foo
+
+Executing a Multiple Configuration Build
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+BitBake is able to build multiple images or packages using a single
+command where the different targets require different configurations
+(multiple configuration builds). Each target, in this scenario, is
+referred to as a "multiconfig".
+
+To accomplish a multiple configuration build, you must define each
+target's configuration separately using a parallel configuration file in
+the build directory. The location for these multiconfig configuration
+files is specific. They must reside in the current build directory in a
+sub-directory of ``conf`` named ``multiconfig``. Following is an example
+for two separate targets:
+
+.. image:: figures/bb_multiconfig_files.png
+   :align: center
+
+The reason for this required file hierarchy is because the ``BBPATH``
+variable is not constructed until the layers are parsed. Consequently,
+using the configuration file as a pre-configuration file is not possible
+unless it is located in the current working directory.
+
+Minimally, each configuration file must define the machine and the
+temporary directory BitBake uses for the build. Suggested practice
+dictates that you do not overlap the temporary directories used during
+the builds.
+
+Aside from separate configuration files for each target, you must also
+enable BitBake to perform multiple configuration builds. Enabling is
+accomplished by setting the
+:term:`BBMULTICONFIG` variable in the
+``local.conf`` configuration file. As an example, suppose you had
+configuration files for ``target1`` and ``target2`` defined in the build
+directory. The following statement in the ``local.conf`` file both
+enables BitBake to perform multiple configuration builds and specifies
+the two extra multiconfigs: ::
+
+  BBMULTICONFIG = "target1 target2"
+
+Once the target configuration files are in place and BitBake has been
+enabled to perform multiple configuration builds, use the following
+command form to start the builds: ::
+
+  $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ]
+
+Here is an example for two extra multiconfigs: ``target1`` and ``target2``: ::
+
+  $ bitbake mc::target mc:target1:target mc:target2:target
+
+.. _bb-enabling-multiple-configuration-build-dependencies:
+
+Enabling Multiple Configuration Build Dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes dependencies can exist between targets (multiconfigs) in a
+multiple configuration build. For example, suppose that in order to
+build an image for a particular architecture, the root filesystem of
+another build for a different architecture needs to exist. In other
+words, the image for the first multiconfig depends on the root
+filesystem of the second multiconfig. This dependency is essentially
+that the task in the recipe that builds one multiconfig is dependent on
+the completion of the task in the recipe that builds another
+multiconfig.
+
+To enable dependencies in a multiple configuration build, you must
+declare the dependencies in the recipe using the following statement
+form: ::
+
+  task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend"
+
+To better show how to use this statement, consider an example with two
+multiconfigs: ``target1`` and ``target2``: ::
+
+  image_task[mcdepends] = "mc:target1:target2:image2:rootfs_task"
+
+In this example, the
+``from_multiconfig`` is "target1" and the ``to_multiconfig`` is "target2". The
+task on which the image whose recipe contains image_task depends on the
+completion of the rootfs_task used to build out image2, which is
+associated with the "target2" multiconfig.
+
+Once you set up this dependency, you can build the "target1" multiconfig
+using a BitBake command as follows: ::
+
+  $ bitbake mc:target1:image1
+
+This command executes all the tasks needed to create ``image1`` for the "target1"
+multiconfig. Because of the dependency, BitBake also executes through
+the ``rootfs_task`` for the "target2" multiconfig build.
+
+Having a recipe depend on the root filesystem of another build might not
+seem that useful. Consider this change to the statement in the image1
+recipe: ::
+
+  image_task[mcdepends] = "mc:target1:target2:image2:image_task"
+
+In this case, BitBake must create ``image2`` for the "target2" build since
+the "target1" build depends on it.
+
+Because "target1" and "target2" are enabled for multiple configuration
+builds and have separate configuration files, BitBake places the
+artifacts for each build in the respective temporary build directories.

bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml

@@ -1,891 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<chapter id="bitbake-user-manual-intro">
-    <title>Overview</title>
-
-    <para>
-        Welcome to the BitBake User Manual.
-        This manual provides information on the BitBake tool.
-        The information attempts to be as independent as possible regarding
-        systems that use BitBake, such as OpenEmbedded and the
-        Yocto Project.
-        In some cases, scenarios or examples within the context of
-        a build system are used in the manual to help with understanding.
-        For these cases, the manual clearly states the context.
-    </para>
-
-    <section id="intro">
-        <title>Introduction</title>
-
-        <para>
-            Fundamentally, BitBake is a generic task execution
-            engine that allows shell and Python tasks to be run
-            efficiently and in parallel while working within
-            complex inter-task dependency constraints.
-            One of BitBake's main users, OpenEmbedded, takes this core
-            and builds embedded Linux software stacks using
-            a task-oriented approach.
-        </para>
-
-        <para>
-            Conceptually, BitBake is similar to GNU Make in
-            some regards but has significant differences:
-            <itemizedlist>
-                <listitem><para>
-                    BitBake executes tasks according to provided
-                    metadata that builds up the tasks.
-                    Metadata is stored in recipe (<filename>.bb</filename>)
-                    and related recipe "append" (<filename>.bbappend</filename>)
-                    files, configuration (<filename>.conf</filename>) and
-                    underlying include (<filename>.inc</filename>) files, and
-                    in class (<filename>.bbclass</filename>) files.
-                    The metadata provides
-                    BitBake with instructions on what tasks to run and
-                    the dependencies between those tasks.
-                    </para></listitem>
-                <listitem><para>
-                    BitBake includes a fetcher library for obtaining source
-                    code from various places such as local files, source control
-                    systems, or websites.
-                    </para></listitem>
-                <listitem><para>
-                    The instructions for each unit to be built (e.g. a piece
-                    of software) are known as "recipe" files and
-                    contain all the information about the unit
-                    (dependencies, source file locations, checksums, description
-                    and so on).
-                    </para></listitem>
-                <listitem><para>
-                    BitBake includes a client/server abstraction and can
-                    be used from a command line or used as a service over
-                    XML-RPC and has several different user interfaces.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-
-    <section id="history-and-goals">
-        <title>History and Goals</title>
-
-        <para>
-            BitBake was originally a part of the OpenEmbedded project.
-            It was inspired by the Portage package management system
-            used by the Gentoo Linux distribution.
-            On December 7, 2004, OpenEmbedded project team member
-            Chris Larson split the project into two distinct pieces:
-            <itemizedlist>
-                <listitem><para>BitBake, a generic task executor</para></listitem>
-                <listitem><para>OpenEmbedded, a metadata set utilized by
-                    BitBake</para></listitem>
-            </itemizedlist>
-            Today, BitBake is the primary basis of the
-            <ulink url="http://www.openembedded.org/">OpenEmbedded</ulink>
-            project, which is being used to build and maintain Linux
-            distributions such as the
-            <ulink url='http://www.angstrom-distribution.org/'>Angstrom Distribution</ulink>,
-            and which is also being used as the build tool for Linux projects
-            such as the
-            <ulink url='http://www.yoctoproject.org'>Yocto Project</ulink>.
-        </para>
-
-        <para>
-            Prior to BitBake, no other build tool adequately met the needs of
-            an aspiring embedded Linux distribution.
-            All of the build systems used by traditional desktop Linux
-            distributions lacked important functionality, and none of the
-            ad hoc Buildroot-based systems, prevalent in the
-            embedded space, were scalable or maintainable.
-        </para>
-
-        <para>
-            Some important original goals for BitBake were:
-            <itemizedlist>
-                <listitem><para>
-                    Handle cross-compilation.
-                    </para></listitem>
-                <listitem><para>
-                    Handle inter-package dependencies (build time on
-                    target architecture, build time on native
-                    architecture, and runtime).
-                    </para></listitem>
-                <listitem><para>
-                    Support running any number of tasks within a given
-                    package, including, but not limited to, fetching
-                    upstream sources, unpacking them, patching them,
-                    configuring them, and so forth.
-                    </para></listitem>
-                <listitem><para>
-                    Be Linux distribution agnostic for both build and
-                    target systems.
-                    </para></listitem>
-                <listitem><para>
-                    Be architecture agnostic.
-                    </para></listitem>
-                <listitem><para>
-                    Support multiple build and target operating systems
-                    (e.g. Cygwin, the BSDs, and so forth).
-                    </para></listitem>
-                <listitem><para>
-                    Be self-contained, rather than tightly
-                    integrated into the build machine's root
-                    filesystem.
-                    </para></listitem>
-                <listitem><para>
-                    Handle conditional metadata on the target architecture,
-                    operating system, distribution, and machine.
-                    </para></listitem>
-                <listitem><para>
-                    Be easy to use the tools to supply local metadata and packages
-                    against which to operate.
-                    </para></listitem>
-                <listitem><para>
-                    Be easy to use BitBake to collaborate between multiple
-                    projects for their builds.
-                    </para></listitem>
-                <listitem><para>
-                    Provide an inheritance mechanism to share
-                    common metadata between many packages.
-                    </para></listitem>
-            </itemizedlist>
-            Over time it became apparent that some further requirements
-            were necessary:
-            <itemizedlist>
-                <listitem><para>
-                    Handle variants of a base recipe (e.g. native, sdk,
-                    and multilib).
-                    </para></listitem>
-                <listitem><para>
-                    Split metadata into layers and allow layers
-                    to enhance or override other layers.
-                    </para></listitem>
-                <listitem><para>
-                    Allow representation of a given set of input variables
-                    to a task as a checksum.
-                    Based on that checksum, allow acceleration of builds
-                    with prebuilt components.
-                    </para></listitem>
-            </itemizedlist>
-            BitBake satisfies all the original requirements and many more
-            with extensions being made to the basic functionality to
-            reflect the additional requirements.
-            Flexibility and power have always been the priorities.
-            BitBake is highly extensible and supports embedded Python code and
-            execution of any arbitrary tasks.
-        </para>
-    </section>
-
-    <section id="Concepts">
-        <title>Concepts</title>
-
-        <para>
-            BitBake is a program written in the Python language.
-            At the highest level, BitBake interprets metadata, decides
-            what tasks are required to run, and executes those tasks.
-            Similar to GNU Make, BitBake controls how software is
-            built.
-            GNU Make achieves its control through "makefiles", while
-            BitBake uses "recipes".
-        </para>
-
-        <para>
-            BitBake extends the capabilities of a simple
-            tool like GNU Make by allowing for the definition of much more
-            complex tasks, such as assembling entire embedded Linux
-            distributions.
-        </para>
-
-        <para>
-            The remainder of this section introduces several concepts
-            that should be understood in order to better leverage
-            the power of BitBake.
-        </para>
-
-        <section id='recipes'>
-            <title>Recipes</title>
-
-            <para>
-                BitBake Recipes, which are denoted by the file extension
-                <filename>.bb</filename>, are the most basic metadata files.
-                These recipe files provide BitBake with the following:
-                <itemizedlist>
-                    <listitem><para>Descriptive information about the
-                        package (author, homepage, license, and so on)</para></listitem>
-                    <listitem><para>The version of the recipe</para></listitem>
-                    <listitem><para>Existing dependencies (both build
-                        and runtime dependencies)</para></listitem>
-                    <listitem><para>Where the source code resides and
-                        how to fetch it</para></listitem>
-                    <listitem><para>Whether the source code requires
-                        any patches, where to find them, and how to apply
-                        them</para></listitem>
-                    <listitem><para>How to configure and compile the
-                        source code</para></listitem>
-                    <listitem><para>How to assemble the generated artifacts into
-                        one or more installable packages</para></listitem>
-                    <listitem><para>Where on the target machine to install the
-                        package or packages created</para></listitem>
-                </itemizedlist>
-            </para>
-
-            <para>
-                Within the context of BitBake, or any project utilizing BitBake
-                as its build system, files with the <filename>.bb</filename>
-                extension are referred to as <firstterm>recipes</firstterm>.
-                <note>
-                    The term "package" is also commonly used to describe recipes.
-                    However, since the same word is used to describe packaged
-                    output from a project, it is best to maintain a single
-                    descriptive term - "recipes".
-                    Put another way, a single "recipe" file is quite capable
-                    of generating a number of related but separately installable
-                    "packages".
-                    In fact, that ability is fairly common.
-                </note>
-            </para>
-        </section>
-
-        <section id='configuration-files'>
-            <title>Configuration Files</title>
-
-            <para>
-                Configuration files, which are denoted by the
-                <filename>.conf</filename> extension, define
-                various configuration variables that govern the project's build
-                process.
-                These files fall into several areas that define
-                machine configuration, distribution configuration,
-                possible compiler tuning, general common
-                configuration, and user configuration.
-                The main configuration file is the sample
-                <filename>bitbake.conf</filename> file, which is
-                located within the BitBake source tree
-                <filename>conf</filename> directory.
-            </para>
-        </section>
-
-        <section id='classes'>
-            <title>Classes</title>
-
-            <para>
-                Class files, which are denoted by the
-                <filename>.bbclass</filename> extension, contain
-                information that is useful to share between metadata files.
-                The BitBake source tree currently comes with one class metadata file
-                called <filename>base.bbclass</filename>.
-                You can find this file in the
-                <filename>classes</filename> directory.
-                The <filename>base.bbclass</filename> class files is special since it
-                is always included automatically for all recipes
-                and classes.
-                This class contains definitions for standard basic tasks such
-                as fetching, unpacking, configuring (empty by default),
-                compiling (runs any Makefile present), installing (empty by
-                default) and packaging (empty by default).
-                These tasks are often overridden or extended by other classes
-                added during the project development process.
-            </para>
-        </section>
-
-        <section id='layers'>
-            <title>Layers</title>
-
-            <para>
-                Layers allow you to isolate different types of
-                customizations from each other.
-                While you might find it tempting to keep everything in one layer
-                when working on a single project, the more modular
-                your metadata, the easier it is to cope with future changes.
-            </para>
-
-            <para>
-                To illustrate how you can use layers to keep things modular,
-                consider customizations you might make to support a specific target machine.
-                These types of customizations typically reside in a special layer,
-                rather than a general layer, called a <firstterm>Board Support Package</firstterm> (BSP)
-                layer.
-                Furthermore, the machine customizations should be isolated from
-                recipes and metadata that support a new GUI environment, for
-                example.
-                This situation gives you a couple of layers: one for the machine
-                configurations and one for the GUI environment.
-                It is important to understand, however, that the BSP layer can still
-                make machine-specific additions to recipes within
-                the GUI environment layer without polluting the GUI layer itself
-                with those machine-specific changes.
-                You can accomplish this through a recipe that is a BitBake append
-                (<filename>.bbappend</filename>) file.
-            </para>
-        </section>
-
-        <section id='append-bbappend-files'>
-            <title>Append Files</title>
-
-            <para>
-                Append files, which are files that have the
-                <filename>.bbappend</filename> file extension, extend or
-                override information in an existing recipe file.
-            </para>
-
-            <para>
-                BitBake expects every append file to have a corresponding recipe file.
-                Furthermore, the append file and corresponding recipe file
-                must use the same root filename.
-                The filenames can differ only in the file type suffix used
-                (e.g. <filename>formfactor_0.0.bb</filename> and
-                <filename>formfactor_0.0.bbappend</filename>).
-            </para>
-
-            <para>
-                Information in append files extends or
-                overrides the information in the underlying,
-                similarly-named recipe files.
-            </para>
-
-            <para>
-                When you name an append file, you can use the
-                "<filename>%</filename>" wildcard character to allow for matching
-                recipe names.
-                For example, suppose you have an append file named
-                as follows:
-                <literallayout class='monospaced'>
-     busybox_1.21.%.bbappend
-                </literallayout>
-                That append file would match any <filename>busybox_1.21.</filename><replaceable>x</replaceable><filename>.bb</filename>
-                version of the recipe.
-                So, the append file would match the following recipe names:
-                <literallayout class='monospaced'>
-     busybox_1.21.1.bb
-     busybox_1.21.2.bb
-     busybox_1.21.3.bb
-                </literallayout>
-                <note><title>Important</title>
-                    The use of the "<filename>%</filename>" character
-                    is limited in that it only works directly in front of the
-                    <filename>.bbappend</filename> portion of the append file's
-                    name.
-                    You cannot use the wildcard character in any other
-                    location of the name.
-                </note>
-                If the <filename>busybox</filename> recipe was updated to
-                <filename>busybox_1.3.0.bb</filename>, the append name would not
-                match.
-                However, if you named the append file
-                <filename>busybox_1.%.bbappend</filename>, then you would have a match.
-            </para>
-
-            <para>
-                In the most general case, you could name the append file something as
-                simple as <filename>busybox_%.bbappend</filename> to be entirely
-                version independent.
-            </para>
-        </section>
-    </section>
-
-    <section id='obtaining-bitbake'>
-        <title>Obtaining BitBake</title>
-
-        <para>
-            You can obtain BitBake several different ways:
-            <itemizedlist>
-                <listitem><para><emphasis>Cloning BitBake:</emphasis>
-                    Using Git to clone the BitBake source code repository
-                    is the recommended method for obtaining BitBake.
-                    Cloning the repository makes it easy to get bug fixes
-                    and have access to stable branches and the master
-                    branch.
-                    Once you have cloned BitBake, you should use
-                    the latest stable
-                    branch for development since the master branch is for
-                    BitBake development and might contain less stable changes.
-                    </para>
-                    <para>You usually need a version of BitBake
-                    that matches the metadata you are using.
-                    The metadata is generally backwards compatible but
-                    not forward compatible.</para>
-                    <para>Here is an example that clones the BitBake repository:
-                    <literallayout class='monospaced'>
-     $ git clone git://git.openembedded.org/bitbake
-                    </literallayout>
-                    This command clones the BitBake Git repository into a
-                    directory called <filename>bitbake</filename>.
-                    Alternatively, you can
-                    designate a directory after the
-                    <filename>git clone</filename> command
-                    if you want to call the new directory something
-                    other than <filename>bitbake</filename>.
-                    Here is an example that names the directory
-                    <filename>bbdev</filename>:
-                    <literallayout class='monospaced'>
-     $ git clone git://git.openembedded.org/bitbake bbdev
-                    </literallayout></para></listitem>
-                <listitem><para><emphasis>Installation using your Distribution
-                    Package Management System:</emphasis>
-                    This method is not
-                    recommended because the BitBake version that is
-                    provided by your distribution, in most cases,
-                    is several
-                    releases behind a snapshot of the BitBake repository.
-                    </para></listitem>
-                <listitem><para><emphasis>Taking a snapshot of BitBake:</emphasis>
-                    Downloading a snapshot of BitBake from the
-                    source code repository gives you access to a known
-                    branch or release of BitBake.
-                    <note>
-                         Cloning the Git repository, as described earlier,
-                         is the preferred method for getting BitBake.
-                         Cloning the repository makes it easier to update as
-                         patches are added to the stable branches.
-                    </note></para>
-                    <para>The following example downloads a snapshot of
-                    BitBake version 1.17.0:
-                    <literallayout class='monospaced'>
-     $ wget http://git.openembedded.org/bitbake/snapshot/bitbake-1.17.0.tar.gz
-     $ tar zxpvf bitbake-1.17.0.tar.gz
-                    </literallayout>
-                    After extraction of the tarball using the tar utility,
-                    you have a directory entitled
-                    <filename>bitbake-1.17.0</filename>.
-                    </para></listitem>
-                <listitem><para><emphasis>Using the BitBake that Comes With Your
-                    Build Checkout:</emphasis>
-                    A final possibility for getting a copy of BitBake is that it
-                    already comes with your checkout of a larger BitBake-based build
-                    system, such as Poky.
-                    Rather than manually checking out individual layers and
-                    gluing them together yourself, you can check
-                    out an entire build system.
-                    The checkout will already include a version of BitBake that
-                    has been thoroughly tested for compatibility with the other
-                    components.
-                    For information on how to check out a particular BitBake-based
-                    build system, consult that build system's supporting documentation.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-
-    <section id="bitbake-user-manual-command">
-        <title>The BitBake Command</title>
-
-        <para>
-            The <filename>bitbake</filename> command is the primary interface
-            to the BitBake tool.
-            This section presents the BitBake command syntax and provides
-            several execution examples.
-        </para>
-
-        <section id='usage-and-syntax'>
-            <title>Usage and syntax</title>
-
-            <para>
-                Following is the usage and syntax for BitBake:
-                <literallayout class='monospaced'>
-     $ bitbake -h
-     Usage: bitbake [options] [recipename/target recipe:do_task ...]
-
-         Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
-         It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
-         will provide the layer, BBFILES and other configuration information.
-
-     Options:
-       --version             show program's version number and exit
-       -h, --help            show this help message and exit
-       -b BUILDFILE, --buildfile=BUILDFILE
-                             Execute tasks from a specific .bb recipe directly.
-                             WARNING: Does not handle any dependencies from other
-                             recipes.
-       -k, --continue        Continue as much as possible after an error. While the
-                             target that failed and anything depending on it cannot
-                             be built, as much as possible will be built before
-                             stopping.
-       -f, --force           Force the specified targets/task to run (invalidating
-                             any existing stamp file).
-       -c CMD, --cmd=CMD     Specify the task to execute. The exact options
-                             available depend on the metadata. Some examples might
-                             be 'compile' or 'populate_sysroot' or 'listtasks' may
-                             give a list of the tasks available.
-       -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
-                             Invalidate the stamp for the specified task such as
-                             'compile' and then run the default task for the
-                             specified target(s).
-       -r PREFILE, --read=PREFILE
-                             Read the specified file before bitbake.conf.
-       -R POSTFILE, --postread=POSTFILE
-                             Read the specified file after bitbake.conf.
-       -v, --verbose         Enable tracing of shell tasks (with 'set -x'). Also
-                             print bb.note(...) messages to stdout (in addition to
-                             writing them to ${T}/log.do_&lt;task&gt;).
-       -D, --debug           Increase the debug level. You can specify this more
-                             than once. -D sets the debug level to 1, where only
-                             bb.debug(1, ...) messages are printed to stdout; -DD
-                             sets the debug level to 2, where both bb.debug(1, ...)
-                             and bb.debug(2, ...) messages are printed; etc.
-                             Without -D, no debug messages are printed. Note that
-                             -D only affects output to stdout. All debug messages
-                             are written to ${T}/log.do_taskname, regardless of the
-                             debug level.
-       -q, --quiet           Output less log message data to the terminal. You can
-                             specify this more than once.
-       -n, --dry-run         Don't execute, just go through the motions.
-       -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
-                             Dump out the signature construction information, with
-                             no task execution. The SIGNATURE_HANDLER parameter is
-                             passed to the handler. Two common values are none and
-                             printdiff but the handler may define more/less. none
-                             means only dump the signature, printdiff means compare
-                             the dumped signature with the cached one.
-       -p, --parse-only      Quit after parsing the BB recipes.
-       -s, --show-versions   Show current and preferred versions of all recipes.
-       -e, --environment     Show the global or per-recipe environment complete
-                             with information about where variables were
-                             set/changed.
-       -g, --graphviz        Save dependency tree information for the specified
-                             targets in the dot syntax.
-       -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
-                             Assume these dependencies don't exist and are already
-                             provided (equivalent to ASSUME_PROVIDED). Useful to
-                             make dependency graphs more appealing
-       -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
-                             Show debug logging for the specified logging domains
-       -P, --profile         Profile the command and save reports.
-       -u UI, --ui=UI        The user interface to use (knotty, ncurses or taskexp
-                             - default knotty).
-       --token=XMLRPCTOKEN   Specify the connection token to be used when
-                             connecting to a remote server.
-       --revisions-changed   Set the exit code depending on whether upstream
-                             floating revisions have changed or not.
-       --server-only         Run bitbake without a UI, only starting a server
-                             (cooker) process.
-       -B BIND, --bind=BIND  The name/address for the bitbake xmlrpc server to bind
-                             to.
-       -T SERVER_TIMEOUT, --idle-timeout=SERVER_TIMEOUT
-                             Set timeout to unload bitbake server due to
-                             inactivity, set to -1 means no unload, default:
-                             Environment variable BB_SERVER_TIMEOUT.
-       --no-setscene         Do not run any setscene tasks. sstate will be ignored
-                             and everything needed, built.
-       --setscene-only       Only run setscene tasks, don't run any real tasks.
-       --remote-server=REMOTE_SERVER
-                             Connect to the specified server.
-       -m, --kill-server     Terminate any running bitbake server.
-       --observe-only        Connect to a server as an observing-only client.
-       --status-only         Check the status of the remote bitbake server.
-       -w WRITEEVENTLOG, --write-log=WRITEEVENTLOG
-                             Writes the event log of the build to a bitbake event
-                             json file. Use '' (empty string) to assign the name
-                             automatically.
-       --runall=RUNALL       Run the specified task for any recipe in the taskgraph
-                             of the specified target (even if it wouldn't otherwise
-                             have run).
-       --runonly=RUNONLY     Run only the specified task within the taskgraph of
-                             the specified targets (and any task dependencies those
-                             tasks may have).
-                </literallayout>
-            </para>
-        </section>
-
-        <section id='bitbake-examples'>
-            <title>Examples</title>
-
-            <para>
-                This section presents some examples showing how to use BitBake.
-            </para>
-
-            <section id='example-executing-a-task-against-a-single-recipe'>
-                <title>Executing a Task Against a Single Recipe</title>
-
-                <para>
-                    Executing tasks for a single recipe file is relatively simple.
-                    You specify the file in question, and BitBake parses
-                    it and executes the specified task.
-                    If you do not specify a task, BitBake executes the default
-                    task, which is "build”.
-                    BitBake obeys inter-task dependencies when doing
-                    so.
-                </para>
-
-                <para>
-                    The following command runs the build task, which is
-                    the default task, on the <filename>foo_1.0.bb</filename>
-                    recipe file:
-                    <literallayout class='monospaced'>
-     $ bitbake -b foo_1.0.bb
-                    </literallayout>
-                    The following command runs the clean task on the
-                    <filename>foo.bb</filename> recipe file:
-                    <literallayout class='monospaced'>
-     $ bitbake -b foo.bb -c clean
-                    </literallayout>
-                    <note>
-                        The "-b" option explicitly does not handle recipe
-                        dependencies.
-                        Other than for debugging purposes, it is instead
-                        recommended that you use the syntax presented in the
-                        next section.
-                    </note>
-                </para>
-            </section>
-
-            <section id='executing-tasks-against-a-set-of-recipe-files'>
-                <title>Executing Tasks Against a Set of Recipe Files</title>
-
-                <para>
-                    There are a number of additional complexities introduced
-                    when one wants to manage multiple <filename>.bb</filename>
-                    files.
-                    Clearly there needs to be a way to tell BitBake what
-                    files are available and, of those, which you
-                    want to execute.
-                    There also needs to be a way for each recipe
-                    to express its dependencies, both for build-time and
-                    runtime.
-                    There must be a way for you to express recipe preferences
-                    when multiple recipes provide the same functionality, or when
-                    there are multiple versions of a recipe.
-                </para>
-
-                <para>
-                    The <filename>bitbake</filename> command, when not using
-                    "--buildfile" or "-b" only accepts a "PROVIDES".
-                    You cannot provide anything else.
-                    By default, a recipe file generally "PROVIDES" its
-                    "packagename" as shown in the following example:
-                    <literallayout class='monospaced'>
-     $ bitbake foo
-                    </literallayout>
-                    This next example "PROVIDES" the package name and also uses
-                    the "-c" option to tell BitBake to just execute the
-                    <filename>do_clean</filename> task:
-                    <literallayout class='monospaced'>
-     $ bitbake -c clean foo
-                    </literallayout>
-                </para>
-            </section>
-
-            <section id='executing-a-list-of-task-and-recipe-combinations'>
-                <title>Executing a List of Task and Recipe Combinations</title>
-
-                <para>
-                    The BitBake command line supports specifying different
-                    tasks for individual targets when you specify multiple
-                    targets.
-                    For example, suppose you had two targets (or recipes)
-                    <filename>myfirstrecipe</filename> and
-                    <filename>mysecondrecipe</filename> and you needed
-                    BitBake to run <filename>taskA</filename> for the first
-                    recipe and <filename>taskB</filename> for the second
-                    recipe:
-                    <literallayout class='monospaced'>
-     $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB
-                    </literallayout>
-                </para>
-            </section>
-
-            <section id='generating-dependency-graphs'>
-                <title>Generating Dependency Graphs</title>
-
-                <para>
-                    BitBake is able to generate dependency graphs using
-                    the <filename>dot</filename> syntax.
-                    You can convert these graphs into images using the
-                    <filename>dot</filename> tool from
-                    <ulink url='http://www.graphviz.org'>Graphviz</ulink>.
-                </para>
-
-                <para>
-                    When you generate a dependency graph, BitBake writes two files
-                    to the current working directory:
-                    <itemizedlist>
-                        <listitem><para>
-                            <emphasis><filename>task-depends.dot</filename>:</emphasis>
-                            Shows dependencies between tasks.
-                            These dependencies match BitBake's internal task execution list.
-                            </para></listitem>
-                        <listitem><para>
-                            <emphasis><filename>pn-buildlist</filename>:</emphasis>
-                            Shows a simple list of targets that are to be built.
-                            </para></listitem>
-                    </itemizedlist>
-                </para>
-
-                <para>
-                    To stop depending on common depends, use the "-I" depend
-                    option and BitBake omits them from the graph.
-                    Leaving this information out can produce more readable graphs.
-                    This way, you can remove from the graph
-                    <filename>DEPENDS</filename> from inherited classes
-                    such as <filename>base.bbclass</filename>.
-                </para>
-
-                <para>
-                    Here are two examples that create dependency graphs.
-                    The second example omits depends common in OpenEmbedded from
-                    the graph:
-                    <literallayout class='monospaced'>
-     $ bitbake -g foo
-
-     $ bitbake -g -I virtual/kernel -I eglibc foo
-                    </literallayout>
-                </para>
-            </section>
-
-            <section id='executing-a-multiple-configuration-build'>
-                <title>Executing a Multiple Configuration Build</title>
-
-                <para>
-                    BitBake is able to build multiple images or packages
-                    using a single command where the different targets
-                    require different configurations (multiple configuration
-                    builds).
-                    Each target, in this scenario, is referred to as a
-                    "multiconfig".
-                </para>
-
-                <para>
-                    To accomplish a multiple configuration build, you must
-                    define each target's configuration separately using
-                    a parallel configuration file in the build directory.
-                    The location for these multiconfig configuration files
-                    is specific.
-                    They must reside in the current build directory in
-                    a sub-directory of <filename>conf</filename> named
-                    <filename>multiconfig</filename>.
-                    Following is an example for two separate targets:
-                    <imagedata fileref="figures/bb_multiconfig_files.png" align="center" width="4in" depth="3in" />
-                </para>
-
-                <para>
-                    The reason for this required file hierarchy
-                    is because the <filename>BBPATH</filename> variable
-                    is not constructed until the layers are parsed.
-                    Consequently, using the configuration file as a
-                    pre-configuration file is not possible unless it is
-                    located in the current working directory.
-                </para>
-
-                <para>
-                    Minimally, each configuration file must define the
-                    machine and the temporary directory BitBake uses
-                    for the build.
-                    Suggested practice dictates that you do not
-                    overlap the temporary directories used during the
-                    builds.
-                </para>
-
-                <para>
-                    Aside from separate configuration files for each
-                    target, you must also enable BitBake to perform multiple
-                    configuration builds.
-                    Enabling is accomplished by setting the
-                    <link linkend='var-bb-BBMULTICONFIG'><filename>BBMULTICONFIG</filename></link>
-                    variable in the <filename>local.conf</filename>
-                    configuration file.
-                    As an example, suppose you had configuration files
-                    for <filename>target1</filename> and
-                    <filename>target2</filename> defined in the build
-                    directory.
-                    The following statement in the
-                    <filename>local.conf</filename> file both enables
-                    BitBake to perform multiple configuration builds and
-                    specifies the two extra multiconfigs:
-                    <literallayout class='monospaced'>
-     BBMULTICONFIG = "target1 target2"
-                    </literallayout>
-                </para>
-
-                <para>
-                    Once the target configuration files are in place and
-                    BitBake has been enabled to perform multiple configuration
-                    builds, use the following command form to start the
-                    builds:
-                    <literallayout class='monospaced'>
-     $ bitbake [mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[mc:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
-                    </literallayout>
-                    Here is an example for two extra multiconfigs:
-                    <filename>target1</filename> and
-                    <filename>target2</filename>:
-                    <literallayout class='monospaced'>
-     $ bitbake mc::<replaceable>target</replaceable> mc:target1:<replaceable>target</replaceable> mc:target2:<replaceable>target</replaceable>
-                    </literallayout>
-                </para>
-            </section>
-
-            <section id='bb-enabling-multiple-configuration-build-dependencies'>
-                <title>Enabling Multiple Configuration Build Dependencies</title>
-
-                <para>
-                    Sometimes dependencies can exist between targets
-                    (multiconfigs) in a multiple configuration build.
-                    For example, suppose that in order to build an image
-                    for a particular architecture, the root filesystem of
-                    another build for a different architecture needs to
-                    exist.
-                    In other words, the image for the first multiconfig depends
-                    on the root filesystem of the second multiconfig.
-                    This dependency is essentially that the task in the recipe
-                    that builds one multiconfig is dependent on the
-                    completion of the task in the recipe that builds
-                    another multiconfig.
-                </para>
-
-                <para>
-                    To enable dependencies in a multiple configuration
-                    build, you must declare the dependencies in the recipe
-                    using the following statement form:
-                    <literallayout class='monospaced'>
-     <replaceable>task_or_package</replaceable>[mcdepends] = "mc:<replaceable>from_multiconfig</replaceable>:<replaceable>to_multiconfig</replaceable>:<replaceable>recipe_name</replaceable>:<replaceable>task_on_which_to_depend</replaceable>"
-                    </literallayout>
-                    To better show how to use this statement, consider an
-                    example with two multiconfigs: <filename>target1</filename>
-                    and <filename>target2</filename>:
-                    <literallayout class='monospaced'>
-     <replaceable>image_task</replaceable>[mcdepends] = "mc:target1:target2:<replaceable>image2</replaceable>:<replaceable>rootfs_task</replaceable>"
-                    </literallayout>
-                    In this example, the
-                    <replaceable>from_multiconfig</replaceable> is "target1" and
-                    the <replaceable>to_multiconfig</replaceable> is "target2".
-                    The task on which the image whose recipe contains
-                    <replaceable>image_task</replaceable> depends on the
-                    completion of the <replaceable>rootfs_task</replaceable>
-                    used to build out <replaceable>image2</replaceable>, which
-                    is associated with the "target2" multiconfig.
-               </para>
-
-               <para>
-                   Once you set up this dependency, you can build the
-                   "target1" multiconfig using a BitBake command as follows:
-                   <literallayout class='monospaced'>
-     $ bitbake mc:target1:<replaceable>image1</replaceable>
-                   </literallayout>
-                   This command executes all the tasks needed to create
-                   <replaceable>image1</replaceable> for the "target1"
-                   multiconfig.
-                   Because of the dependency, BitBake also executes through
-                   the <replaceable>rootfs_task</replaceable> for the "target2"
-                   multiconfig build.
-               </para>
-
-               <para>
-                   Having a recipe depend on the root filesystem of another
-                   build might not seem that useful.
-                   Consider this change to the statement in the
-                   <replaceable>image1</replaceable> recipe:
-                   <literallayout class='monospaced'>
-     <replaceable>image_task</replaceable>[mcdepends] = "mc:target1:target2:<replaceable>image2</replaceable>:<replaceable>image_task</replaceable>"
-                   </literallayout>
-                   In this case, BitBake must create
-                   <replaceable>image2</replaceable> for the "target2"
-                   build since the "target1" build depends on it.
-               </para>
-
-               <para>
-                   Because "target1" and "target2" are enabled for multiple
-                   configuration builds and have separate configuration
-                   files, BitBake places the artifacts for each build in the
-                   respective temporary build directories.
-               </para>
-            </section>
-        </section>
-    </section>
-</chapter>

bitbake/doc/bitbake-user-manual/bitbake-user-manual-style.css

@@ -1,984 +0,0 @@
-/*
-   Generic XHTML / DocBook XHTML CSS Stylesheet.
-
-   Browser wrangling and typographic design by
-      Oyvind Kolas / pippin@gimp.org
-
-   Customised for Poky by
-      Matthew Allum / mallum@o-hand.com
-
-   Thanks to:
-     Liam R. E. Quin
-     William Skaggs
-     Jakub Steiner
-
-   Structure
-   ---------
-
-   The stylesheet is divided into the following sections:
-
-       Positioning
-          Margins, paddings, width, font-size, clearing.
-       Decorations
-          Borders, style
-       Colors
-          Colors
-       Graphics
-          Graphical backgrounds
-       Nasty IE tweaks
-          Workarounds needed to make it work in internet explorer,
-          currently makes the stylesheet non validating, but up until
-          this point it is validating.
-       Mozilla extensions
-          Transparency for footer
-	  Rounded corners on boxes
-
-*/
-
-
-  /*************** /
- /  Positioning   /
-/ ***************/
-
-body {
-  font-family: Verdana, Sans, sans-serif;
-
-  min-width: 640px;
-  width: 80%;
-  margin:  0em auto;
-  padding: 2em 5em 5em 5em;
-  color: #333;
-}
-
-h1,h2,h3,h4,h5,h6,h7 {
-  font-family: Arial, Sans;
-  color: #00557D;
-  clear: both;
-}
-
-h1 {
-  font-size: 2em;
-  text-align: left;
-  padding: 0em 0em 0em 0em;
-  margin: 2em 0em 0em 0em;
-}
-
-h2.subtitle {
-  margin: 0.10em 0em 3.0em 0em;
-  padding: 0em 0em 0em 0em;
-  font-size: 1.8em;
-  padding-left: 20%;
-  font-weight: normal;
-  font-style: italic;
-}
-
-h2 {
-  margin: 2em 0em 0.66em 0em;
-  padding: 0.5em 0em 0em 0em;
-  font-size: 1.5em;
-  font-weight: bold;
-}
-
-h3.subtitle {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-  font-size: 142.14%;
-  text-align: right;
-}
-
-h3 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 140%;
-  font-weight: bold;
-}
-
-h4 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 120%;
-  font-weight: bold;
-}
-
-h5 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 110%;
-  font-weight: bold;
-}
-
-h6 {
-  margin: 1em 0em 0em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 110%;
-  font-weight: bold;
-}
-
-.authorgroup {
-  background-color: transparent;
-  background-repeat: no-repeat;
-  padding-top: 256px;
-  background-image: url("figures/bitbake-title.png");
-  background-position: left top;
-  margin-top: -256px;
-  padding-right: 50px;
-  margin-left: 0px;
-  text-align: right;
-  width: 740px;
-}
-
-h3.author {
-  margin: 0em 0me 0em 0em;
-  padding: 0em 0em 0em 0em;
-  font-weight: normal;
-  font-size: 100%;
-  color: #333;
-  clear: both;
-}
-
-.author tt.email {
-  font-size: 66%;
-}
-
-.titlepage hr {
-  width: 0em;
-  clear: both;
-}
-
-.revhistory {
-  padding-top: 2em;
-  clear: both;
-}
-
-.toc,
-.list-of-tables,
-.list-of-examples,
-.list-of-figures {
-  padding: 1.33em 0em 2.5em 0em;
-  color: #00557D;
-}
-
-.toc p,
-.list-of-tables p,
-.list-of-figures p,
-.list-of-examples p {
-  padding: 0em 0em 0em 0em;
-  padding: 0em 0em 0.3em;
-  margin: 1.5em 0em 0em 0em;
-}
-
-.toc p b,
-.list-of-tables p b,
-.list-of-figures p b,
-.list-of-examples p b{
-  font-size: 100.0%;
-  font-weight: bold;
-}
-
-.toc dl,
-.list-of-tables dl,
-.list-of-figures dl,
-.list-of-examples dl {
-  margin: 0em 0em 0.5em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.toc dt {
-  margin: 0em 0em 0em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.toc dd {
-  margin: 0em 0em 0em 2.6em;
-  padding: 0em 0em 0em 0em;
-}
-
-div.glossary dl,
-div.variablelist dl {
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
-  font-weight: normal;
-  width: 20em;
-  text-align: right;
-}
-
-.variablelist dl dt {
-  margin-top: 0.5em;
-}
-
-.glossary dl dd,
-.variablelist dl dd {
-  margin-top: -1em;
-  margin-left: 25.5em;
-}
-
-.glossary dd p,
-.variablelist dd p {
-  margin-top: 0em;
-  margin-bottom: 1em;
-}
-
-
-div.calloutlist table td {
-  padding: 0em 0em 0em 0em;
-  margin: 0em 0em 0em 0em;
-}
-
-div.calloutlist table td p {
-  margin-top: 0em;
-  margin-bottom: 1em;
-}
-
-div p.copyright {
-  text-align: left;
-}
-
-div.legalnotice p.legalnotice-title {
-  margin-bottom: 0em;
-}
-
-p {
-  line-height: 1.5em;
-  margin-top: 0em;
-
-}
-
-dl {
-  padding-top: 0em;
-}
-
-hr {
-  border: solid 1px;
-}
-
-
-.mediaobject,
-.mediaobjectco {
-  text-align: center;
-}
-
-img {
-  border: none;
-}
-
-ul {
-  padding: 0em 0em 0em 1.5em;
-}
-
-ul li {
-  padding: 0em 0em 0em 0em;
-}
-
-ul li p {
-  text-align: left;
-}
-
-table {
-  width :100%;
-}
-
-th {
-  padding: 0.25em;
-  text-align: left;
-  font-weight: normal;
-  vertical-align: top;
-}
-
-td {
-  padding: 0.25em;
-  vertical-align: top;
-}
-
-p a[id] {
-  margin: 0px;
-  padding: 0px;
-  display: inline;
-  background-image: none;
-}
-
-a {
-  text-decoration: underline;
-  color: #444;
-}
-
-pre {
-    overflow: auto;
-}
-
-a:hover {
-  text-decoration: underline;
-  /*font-weight: bold;*/
-}
-
-/* This style defines how the permalink character
-   appears by itself and when hovered over with
-   the mouse. */
-
-[alt='Permalink'] { color: #eee; }
-[alt='Permalink']:hover { color: black; }
-
-
-div.informalfigure,
-div.informalexample,
-div.informaltable,
-div.figure,
-div.table,
-div.example {
-  margin: 1em 0em;
-  padding: 1em;
-  page-break-inside: avoid;
-}
-
-
-div.informalfigure p.title b,
-div.informalexample p.title b,
-div.informaltable p.title b,
-div.figure p.title b,
-div.example p.title b,
-div.table p.title b{
-    padding-top: 0em;
-    margin-top: 0em;
-    font-size: 100%;
-    font-weight: normal;
-}
-
-.mediaobject .caption,
-.mediaobject .caption p  {
-  text-align: center;
-  font-size: 80%;
-  padding-top: 0.5em;
-  padding-bottom: 0.5em;
-}
-
-.epigraph {
-  padding-left: 55%;
-  margin-bottom: 1em;
-}
-
-.epigraph p {
-  text-align: left;
-}
-
-.epigraph .quote {
-  font-style: italic;
-}
-.epigraph .attribution {
-  font-style: normal;
-  text-align: right;
-}
-
-span.application {
-  font-style: italic;
-}
-
-.programlisting {
-  font-family: monospace;
-  font-size: 80%;
-  white-space: pre;
-  margin: 1.33em 0em;
-  padding: 1.33em;
-}
-
-.tip,
-.warning,
-.caution,
-.note {
-  margin-top: 1em;
-  margin-bottom: 1em;
-
-}
-
-/* force full width of table within div */
-.tip table,
-.warning table,
-.caution table,
-.note table {
-  border: none;
-  width: 100%;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  padding: 0.8em 0.0em 0.0em 0.0em;
-  margin : 0em 0em 0em 0em;
-}
-
-.tip p,
-.warning p,
-.caution p,
-.note p {
-  margin-top: 0.5em;
-  margin-bottom: 0.5em;
-  padding-right: 1em;
-  text-align: left;
-}
-
-.acronym {
-  text-transform: uppercase;
-}
-
-b.keycap,
-.keycap {
-  padding: 0.09em 0.3em;
-  margin: 0em;
-}
-
-.itemizedlist li {
-  clear: none;
-}
-
-.filename {
-  font-size: medium;
-  font-family: Courier, monospace;
-}
-
-
-div.navheader, div.heading{
-  position: absolute;
-  left: 0em;
-  top: 0em;
-  width: 100%;
-  background-color: #cdf;
-  width: 100%;
-}
-
-div.navfooter, div.footing{
-  position: fixed;
-  left: 0em;
-  bottom: 0em;
-  background-color: #eee;
-  width: 100%;
-}
-
-
-div.navheader td,
-div.navfooter td {
-  font-size: 66%;
-}
-
-div.navheader table th {
-  /*font-family: Georgia, Times, serif;*/
-  /*font-size: x-large;*/
-  font-size: 80%;
-}
-
-div.navheader table {
-  border-left: 0em;
-  border-right: 0em;
-  border-top: 0em;
-  width: 100%;
-}
-
-div.navfooter table {
-  border-left: 0em;
-  border-right: 0em;
-  border-bottom: 0em;
-  width: 100%;
-}
-
-div.navheader table td a,
-div.navfooter table td a {
-  color: #777;
-  text-decoration: none;
-}
-
-/* normal text in the footer */
-div.navfooter table td {
-  color: black;
-}
-
-div.navheader table td a:visited,
-div.navfooter table td a:visited {
-  color: #444;
-}
-
-
-/* links in header and footer */
-div.navheader table td a:hover,
-div.navfooter table td a:hover {
-  text-decoration: underline;
-  background-color: transparent;
-  color: #33a;
-}
-
-div.navheader hr,
-div.navfooter hr {
-  display: none;
-}
-
-
-.qandaset tr.question td p {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.qandaset tr.answer td p {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-}
-.answer td {
-  padding-bottom: 1.5em;
-}
-
-.emphasis {
-  font-weight: bold;
-}
-
-
-  /************* /
- / decorations  /
-/ *************/
-
-.titlepage {
-}
-
-.part .title {
-}
-
-.subtitle {
-    border: none;
-}
-
-/*
-h1 {
-  border: none;
-}
-
-h2 {
-  border-top: solid 0.2em;
-  border-bottom: solid 0.06em;
-}
-
-h3 {
-  border-top: 0em;
-  border-bottom: solid 0.06em;
-}
-
-h4 {
-  border: 0em;
-  border-bottom: solid 0.06em;
-}
-
-h5 {
-  border: 0em;
-}
-*/
-
-.programlisting {
-  border: solid 1px;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example {
-  border: 1px solid;
-}
-
-
-
-.tip,
-.warning,
-.caution,
-.note {
-  border: 1px solid;
-}
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  border-bottom: 1px solid;
-}
-
-.question td {
-  border-top: 1px solid black;
-}
-
-.answer {
-}
-
-
-b.keycap,
-.keycap {
-  border: 1px solid;
-}
-
-
-div.navheader, div.heading{
-  border-bottom: 1px solid;
-}
-
-
-div.navfooter, div.footing{
-  border-top: 1px solid;
-}
-
-  /********* /
- /  colors  /
-/ *********/
-
-body {
-  color: #333;
-  background: white;
-}
-
-a {
-  background: transparent;
-}
-
-a:hover {
-  background-color: #dedede;
-}
-
-
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7,
-h8 {
-  background-color: transparent;
-}
-
-hr {
-  border-color: #aaa;
-}
-
-
-.tip, .warning, .caution, .note {
-  border-color: #fff;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  border-bottom-color: #fff;
-}
-
-
-.warning {
-  background-color: #f0f0f2;
-}
-
-.caution {
-  background-color: #f0f0f2;
-}
-
-.tip {
-  background-color: #f0f0f2;
-}
-
-.note {
-  background-color: #f0f0f2;
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
-  color: #044;
-}
-
-div.figure,
-div.table,
-div.example,
-div.informalfigure,
-div.informaltable,
-div.informalexample {
-  border-color: #aaa;
-}
-
-pre.programlisting {
-  color: black;
-  background-color: #fff;
-  border-color: #aaa;
-  border-width: 2px;
-}
-
-.guimenu,
-.guilabel,
-.guimenuitem {
-  background-color: #eee;
-}
-
-
-b.keycap,
-.keycap {
-  background-color: #eee;
-  border-color: #999;
-}
-
-
-div.navheader {
-  border-color: black;
-}
-
-
-div.navfooter {
-  border-color: black;
-}
-
-
-  /*********** /
- /  graphics  /
-/ ***********/
-
-/*
-body {
-  background-image: url("images/body_bg.jpg");
-  background-attachment: fixed;
-}
-
-.navheader,
-.note,
-.tip {
-  background-image: url("images/note_bg.jpg");
-  background-attachment: fixed;
-}
-
-.warning,
-.caution {
-  background-image: url("images/warning_bg.jpg");
-  background-attachment: fixed;
-}
-
-.figure,
-.informalfigure,
-.example,
-.informalexample,
-.table,
-.informaltable {
-  background-image: url("images/figure_bg.jpg");
-  background-attachment: fixed;
-}
-
-*/
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7{
-}
-
-/*
-Example of how to stick an image as part of the title.
-
-div.article .titlepage .title
-{
-  background-image: url("figures/white-on-black.png");
-  background-position: center;
-  background-repeat: repeat-x;
-}
-*/
-
-div.preface .titlepage .title,
-div.colophon .title,
-div.chapter .titlepage .title,
-div.article .titlepage .title
-{
-}
-
-div.section div.section .titlepage .title,
-div.sect2 .titlepage .title {
-    background: none;
-}
-
-
-h1.title {
-  background-color: transparent;
-  background-repeat: no-repeat;
-  height: 256px;
-  text-indent: -9000px;
-  overflow:hidden;
-}
-
-h2.subtitle {
-  background-color: transparent;
-  text-indent: -9000px;
-  overflow:hidden;
-  width: 0px;
-  display: none;
-}
-
-  /*************************************** /
- /  pippin.gimp.org specific alterations  /
-/ ***************************************/
-
-/*
-div.heading, div.navheader {
-  color: #777;
-  font-size: 80%;
-  padding: 0;
-  margin: 0;
-  text-align: left;
-  position: absolute;
-  top: 0px;
-  left: 0px;
-  width: 100%;
-  height: 50px;
-  background: url('/gfx/heading_bg.png') transparent;
-  background-repeat: repeat-x;
-  background-attachment: fixed;
-  border: none;
-}
-
-div.heading a {
-  color: #444;
-}
-
-div.footing, div.navfooter {
-  border: none;
-  color: #ddd;
-  font-size: 80%;
-  text-align:right;
-
-  width: 100%;
-  padding-top: 10px;
-  position: absolute;
-  bottom: 0px;
-  left: 0px;
-
-  background: url('/gfx/footing_bg.png') transparent;
-}
-*/
-
-
-
-  /****************** /
- /  nasty ie tweaks  /
-/ ******************/
-
-/*
-div.heading, div.navheader {
-  width:expression(document.body.clientWidth + "px");
-}
-
-div.footing, div.navfooter {
-  width:expression(document.body.clientWidth + "px");
-  margin-left:expression("-5em");
-}
-body {
-  padding:expression("4em 5em 0em 5em");
-}
-*/
-
-  /**************************************** /
- / mozilla vendor specific css extensions  /
-/ ****************************************/
-/*
-div.navfooter, div.footing{
-  -moz-opacity: 0.8em;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example,
-.tip,
-.warning,
-.caution,
-.note {
-  -moz-border-radius: 0.5em;
-}
-
-b.keycap,
-.keycap {
-  -moz-border-radius: 0.3em;
-}
-*/
-
-table tr td table tr td {
-  display: none;
-}
-
-
-hr {
-  display: none;
-}
-
-table {
-  border: 0em;
-}
-
- .photo {
-  float: right;
-  margin-left:   1.5em;
-  margin-bottom: 1.5em;
-  margin-top: 0em;
-  max-width:      17em;
-  border:     1px solid gray;
-  padding:    3px;
-  background: white;
-}
- .seperator {
-   padding-top: 2em;
-   clear: both;
-  }
-
-  #validators {
-      margin-top: 5em;
-      text-align: right;
-      color: #777;
-  }
-  @media print {
-      body {
-          font-size: 8pt;
-      }
-      .noprint {
-          display: none;
-      }
-  }
-
-
-.tip,
-.note {
-   background: #f0f0f2;
-   color: #333;
-   padding: 20px;
-   margin: 20px;
-}
-
-.tip h3,
-.note h3 {
-   padding: 0em;
-   margin: 0em;
-   font-size: 2em;
-   font-weight: bold;
-   color: #333;
-}
-
-.tip a,
-.note a {
-   color: #333;
-   text-decoration: underline;
-}
-
-.footnote {
-   font-size: small;
-   color: #333;
-}
-
-/* Changes the announcement text */
-.tip h3,
-.warning h3,
-.caution h3,
-.note h3 {
-   font-size:large;
-   color: #00557D;
-}

bitbake/doc/bitbake-user-manual/bitbake-user-manual.xml

@@ -1,88 +0,0 @@
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<book id='bitbake-user-manual' lang='en'
-        xmlns:xi="http://www.w3.org/2003/XInclude"
-        xmlns="http://docbook.org/ns/docbook"
-        >
-    <bookinfo>
-
-        <mediaobject>
-            <imageobject>
-                <imagedata fileref='figures/bitbake-title.png'
-                    format='SVG'
-                    align='left' scalefit='1' width='100%'/>
-            </imageobject>
-        </mediaobject>
-
-        <title>
-            BitBake User Manual
-        </title>
-
-        <authorgroup>
-            <author>
-                <firstname>Richard Purdie, Chris Larson, and </firstname> <surname>Phil Blundell</surname>
-                <affiliation>
-                    <orgname>BitBake Community</orgname>
-                </affiliation>
-                <email>bitbake-devel@lists.openembedded.org</email>
-            </author>
-        </authorgroup>
-
-<!--
-# Add in some revision history if we want it here.
-        <revhistory>
-            <revision>
-                <revnumber>x.x</revnumber>
-                <date>dd month year</date>
-                <revremark>Some relevent comment</revremark>
-            </revision>
-            <revision>
-                <revnumber>x.x</revnumber>
-                <date>dd month year</date>
-                <revremark>Some relevent comment</revremark>
-            </revision>
-            <revision>
-                <revnumber>x.x</revnumber>
-                <date>dd month year</date>
-                <revremark>Some relevent comment</revremark>
-            </revision>
-            <revision>
-                <revnumber>x.x</revnumber>
-                <date>dd month year</date>
-                <revremark>Some relevent comment</revremark>
-            </revision>
-       </revhistory>
--->
-
-        <copyright>
-            <year>2004-2018</year>
-            <holder>Richard Purdie</holder>
-            <holder>Chris Larson</holder>
-            <holder>and Phil Blundell</holder>
-        </copyright>
-
-        <legalnotice>
-            <para>
-                This work is licensed under the Creative Commons Attribution License.
-                To view a copy of this license, visit
-                <ulink url="http://creativecommons.org/licenses/by/2.5/">http://creativecommons.org/licenses/by/2.5/</ulink>
-                or send a letter to Creative Commons, 444 Castro Street,
-                Suite 900, Mountain View, California 94041, USA.
-            </para>
-        </legalnotice>
-    </bookinfo>
-
-    <xi:include href="bitbake-user-manual-intro.xml"/>
-
-    <xi:include href="bitbake-user-manual-execution.xml"/>
-
-    <xi:include href="bitbake-user-manual-metadata.xml"/>
-
-    <xi:include href="bitbake-user-manual-fetching.xml"/>
-
-    <xi:include href="bitbake-user-manual-ref-variables.xml"/>
-
-    <xi:include href="bitbake-user-manual-hello.xml"/>
-
-</book>

bitbake/doc/bitbake-user-manual/html.css

@@ -1,281 +0,0 @@
-/* Feuille de style DocBook du projet Traduc.org                */
-/* DocBook CSS stylesheet of the Traduc.org project             */
-
-/* (c) Jean-Philippe Gu<47>rard - 14 ao<61>t 2004                     */
-/* (c) Jean-Philippe Gu<47>rard - 14 August 2004                   */
-
-/* Cette feuille de style est libre, vous pouvez la             */
-/* redistribuer et la modifier selon les termes de la Licence   */
-/* Art Libre. Vous trouverez un exemplaire de cette Licence sur */
-/* http://tigreraye.org/Petit-guide-du-traducteur.html#licence-art-libre */
-
-/* This work of art is free, you can redistribute it and/or     */
-/* modify it according to terms of the Free Art license. You    */
-/* will find a specimen of this license on the Copyleft         */
-/* Attitude web site: http://artlibre.org as well as on other   */
-/* sites.                                                       */
-/* Please note that the French version of this licence as shown */
-/* on http://tigreraye.org/Petit-guide-du-traducteur.html#licence-art-libre */
-/* is only official licence of this document. The English       */
-/* is only provided to help you understand this licence.        */
-
-/* La derni<6E>re version de cette feuille de style est toujours   */
-/* disponible sur<75>: http://tigreraye.org/style.css              */
-/* Elle est <20>galement disponible sur<75>:                          */
-/* http://www.traduc.org/docs/HOWTO/lecture/style.css           */
-
-/* The latest version of this stylesheet is available from:     */
-/* http://tigreraye.org/style.css                               */
-/* It is also available on:                                     */
-/* http://www.traduc.org/docs/HOWTO/lecture/style.css           */
-
-/* N'h<>sitez pas <20> envoyer vos commentaires et corrections <20>    */
-/* Jean-Philippe Gu<47>rard <jean-philippe.guerard@tigreraye.org>  */
-
-/* Please send feedback and bug reports to                      */
-/* Jean-Philippe Gu<47>rard <jean-philippe.guerard@tigreraye.org>  */
-
-/* $Id: style.css,v 1.14 2004/09/10 20:12:09 fevrier Exp fevrier $ */
-
-/* Pr<50>sentation g<>n<EFBFBD>rale du document */
-/* Overall document presentation */
-
-body {
-    /*
-    font-family: Apolline, "URW Palladio L", Garamond, jGaramond,
-                 "Bitstream Cyberbit", "Palatino Linotype", serif;
-     */
-    margin: 7%;
-    background-color: white;
-}
-
-/* Taille du texte */
-/* Text size */
-
-* { font-size: 100%; }
-
-/* Gestion des textes mis en relief imbriqu<71>s */
-/* Embedded emphasis */
-
-em { font-style: italic; }
-em em { font-style: normal; }
-em em em { font-style: italic; }
-
-/* Titres */
-/* Titles */
-
-h1 { font-size: 200%; font-weight: 900; }
-h2 { font-size: 160%; font-weight: 900; }
-h3 { font-size: 130%; font-weight: bold; }
-h4 { font-size: 115%; font-weight: bold; }
-h5 { font-size: 108%; font-weight: bold; }
-h6 {                  font-weight: bold; }
-
-/* Nom de famille en petites majuscules (uniquement en fran<61>ais) */
-/* Last names in small caps (for French only) */
-
-*[class~="surname"]:lang(fr) { font-variant: small-caps; }
-
-/* Blocs de citation */
-/* Quotation blocs */
-
-div[class~="blockquote"] {
-  border: solid 2px #AAA;
-  padding: 5px;
-  margin: 5px;
-}
-
-div[class~="blockquote"] > table {
-  border: none;
-}
-
-/* Blocs lit<69>raux<75>: fond gris clair */
-/* Literal blocs: light gray background */
-
-*[class~="literallayout"] {
-  background: #f0f0f0;
-  padding: 5px;
-  margin: 5px;
-}
-
-/* Programmes et captures texte<74>: fond bleu clair */
-/* Listing and text screen snapshots: light blue background */
-
-*[class~="programlisting"], *[class~="screen"] {
-  background: #f0f0ff;
-  padding: 5px;
-  margin: 5px;
-}
-
-/* Les textes <20> remplacer sont surlign<67>s en vert p<>le */
-/* Replaceable text in highlighted in pale green */
-
-*[class~="replaceable"] { 
-    background-color: #98fb98;
-    font-style: normal; }
-
-/* Tables<65>: fonds gris clair & bords simples */
-/* Tables: light gray background and solid borders */
-
-*[class~="table"] *[class~="title"] { width:100%; border: 0px; }
-
-table {
-    border: 1px solid #aaa;
-    border-collapse: collapse;
-    padding: 2px;
-    margin: 5px;
-}
-
-/* Listes simples en style table */
-/* Simples lists in table presentation */
-
-table[class~="simplelist"] {
-    background-color: #F0F0F0;
-    margin: 5px;
-    border: solid 1px #AAA;
-}
-
-table[class~="simplelist"] td {
-    border: solid 1px #AAA;
-}
-
-/* Les tables */
-/* Tables */
-
-*[class~="table"] table {
-    background-color: #F0F0F0;
-    border: solid 1px #AAA;
-}
-*[class~="informaltable"] table { background-color: #F0F0F0; }
-
-th,td {
-    vertical-align: baseline;
-    text-align: left;
-    padding: 0.1em 0.3em;
-    empty-cells: show; 
-}
-
-/* Alignement des colonnes */
-/* Colunms alignment */
-
-td[align=center] ,  th[align=center]  { text-align: center; }
-td[align=right] ,   th[align=right]   { text-align: right; }
-td[align=left] ,    th[align=left]    { text-align: left; }
-td[align=justify] , th[align=justify] { text-align: justify; }
-
-/* Pas de marge autour des images */
-/* No inside margins for images */
-
-img { border: 0; }
-
-/* Les liens ne sont pas soulign<67>s */
-/* No underlines for links */
-
-:link , :visited , :active { text-decoration: none; }
-
-/* Prudence<63>: cadre jaune et fond jaune clair */
-/* Caution: yellow border and light yellow background */
-
-*[class~="caution"] {
-    border: solid 2px yellow;
-    background-color: #ffffe0;
-    padding: 1em 6px 1em ;
-    margin: 5px;
-}
-
-*[class~="caution"] th {
-    vertical-align: middle
-}
-
-*[class~="caution"] table {
-    background-color: #ffffe0;
-    border: none;
-}
-
-/* Note importante<74>: cadre jaune et fond jaune clair */
-/* Important: yellow border and light yellow background */
-
-*[class~="important"] {
-    border: solid 2px yellow;
-    background-color: #ffffe0;
-    padding: 1em 6px 1em;
-    margin: 5px;
-}
-
-*[class~="important"] th {
-    vertical-align: middle
-}
-
-*[class~="important"] table  {
-    background-color: #ffffe0;
-    border: none;
-}
-
-/* Mise en <20>vidence<63>: texte l<>g<EFBFBD>rement plus grand */
-/* Highlights: slightly larger texts */
-
-*[class~="highlights"] {
-    font-size:  110%;
-}
-
-/* Note<74>: cadre bleu et fond bleu clair */
-/* Notes: blue border and light blue background */
-
-*[class~="note"]   {
-    border: solid 2px #7099C5;
-    background-color: #f0f0ff;
-    padding: 1em 6px 1em ;
-    margin: 5px;
-}
-
-*[class~="note"] th {
-    vertical-align: middle
-}
-
-*[class~="note"] table {
-    background-color: #f0f0ff;
-    border: none;
-}
-
-/* Astuce<63>: cadre vert et fond vert clair */
-/* Tip: green border and light green background */
-
-*[class~="tip"] {
-    border: solid 2px #00ff00;
-    background-color: #f0ffff;
-    padding: 1em 6px 1em ;
-    margin: 5px;
-}
-
-*[class~="tip"] th {
-    vertical-align: middle;
-}
-
-*[class~="tip"] table {
-    background-color: #f0ffff;
-    border: none;
-}
-
-/* Avertissement<6E>: cadre rouge et fond rouge clair */
-/* Warning: red border and light red background */
-
-*[class~="warning"] {
-    border: solid 2px #ff0000;
-    background-color: #fff0f0; 
-    padding: 1em 6px 1em ;
-    margin: 5px;
-}
-
-*[class~="warning"] th {
-    vertical-align: middle;
-}
-                    
-
-*[class~="warning"] table {
-    background-color: #fff0f0;
-    border: none;
-}
-
-/* Fin */
-/* The End */
-

bitbake/doc/conf.py

@@ -0,0 +1,101 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+import sys
+import datetime
+
+current_version = "dev"
+
+# String used in sidebar
+version = 'Version: ' + current_version
+if current_version == 'dev':
+    version = 'Version: Current Development'
+# Version seen in documentation_options.js and hence in js switchers code
+release = current_version
+
+# -- Project information -----------------------------------------------------
+
+project = 'Bitbake'
+copyright = '2004-%s, Richard Purdie, Chris Larson, and Phil Blundell' \
+    % datetime.datetime.now().year
+author = 'Richard Purdie, Chris Larson, and Phil Blundell'
+
+# external links and substitutions
+extlinks = {
+    'yocto_docs': ('https://docs.yoctoproject.org%s', None),
+    'oe_lists': ('https://lists.openembedded.org%s', None),
+}
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.extlinks',
+]
+autosectionlabel_prefix_document = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# master document name. The default changed from contents to index. so better
+# set it ourselves.
+master_doc = 'index'
+
+# create substitution for project configuration variables
+rst_prolog = """
+.. |project_name| replace:: %s
+.. |copyright| replace:: %s
+.. |author| replace:: %s
+""" % (project, copyright, author)
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+try:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+except ImportError:
+    sys.stderr.write("The Sphinx sphinx_rtd_theme HTML theme was not found.\
+    \nPlease make sure to install the sphinx_rtd_theme python package.\n")
+    sys.exit(1)
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['sphinx-static']
+
+# Add customm CSS and JS files
+html_css_files = ['theme_overrides.css']
+html_js_files = ['switchers.js']
+
+# Hide 'Created using Sphinx' text
+html_show_sphinx = False
+
+# Add 'Last updated' on each page
+html_last_updated_fmt = '%b %d, %Y'
+
+# Remove the trailing 'dot' in section numbers
+html_secnumber_suffix = " "

bitbake/doc/genindex.rst

@@ -0,0 +1,3 @@
+=====
+Index
+=====

bitbake/doc/index.rst

@@ -0,0 +1,38 @@
+.. SPDX-License-Identifier: CC-BY-2.5
+
+===================
+BitBake User Manual
+===================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   bitbake-user-manual/bitbake-user-manual-intro
+   bitbake-user-manual/bitbake-user-manual-execution
+   bitbake-user-manual/bitbake-user-manual-metadata
+   bitbake-user-manual/bitbake-user-manual-fetching
+   bitbake-user-manual/bitbake-user-manual-ref-variables
+   bitbake-user-manual/bitbake-user-manual-hello
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   genindex
+   releases
+
+----
+
+.. include:: <xhtml1-lat1.txt>
+
+| BitBake Community
+| Copyright |copy| |copyright|
+| <bitbake-devel@lists.openembedded.org>
+
+This work is licensed under the Creative Commons Attribution License.  To view a
+copy of this license, visit http://creativecommons.org/licenses/by/2.5/ or send
+a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View,
+California 94041, USA.

bitbake/doc/poky.ent

@@ -1,51 +0,0 @@
-<!ENTITY DISTRO "1.4">
-<!ENTITY DISTRO_NAME "tbd">
-<!ENTITY YOCTO_DOC_VERSION "1.4">
-<!ENTITY POKYVERSION "8.0">
-<!ENTITY YOCTO_POKY "poky-&DISTRO_NAME;-&POKYVERSION;">
-<!ENTITY COPYRIGHT_YEAR "2010-2013">
-<!ENTITY YOCTO_DL_URL "http://downloads.yoctoproject.org">
-<!ENTITY YOCTO_HOME_URL "http://www.yoctoproject.org">
-<!ENTITY YOCTO_LISTS_URL "http://lists.yoctoproject.org">
-<!ENTITY YOCTO_BUGZILLA_URL "http://bugzilla.yoctoproject.org">
-<!ENTITY YOCTO_WIKI_URL "https://wiki.yoctoproject.org">
-<!ENTITY YOCTO_AB_URL "http://autobuilder.yoctoproject.org">
-<!ENTITY YOCTO_GIT_URL "http://git.yoctoproject.org">
-<!ENTITY YOCTO_ADTREPO_URL "http://adtrepo.yoctoproject.org">
-<!ENTITY OE_HOME_URL "http://www.openembedded.org">
-<!ENTITY OE_LISTS_URL "http://lists.linuxtogo.org/cgi-bin/mailman">
-<!ENTITY OE_DOCS_URL "http://docs.openembedded.org">
-<!ENTITY OH_HOME_URL "http://o-hand.com">
-<!ENTITY BITBAKE_HOME_URL "http://developer.berlios.de/projects/bitbake/">
-<!ENTITY YOCTO_DOCS_URL "&YOCTO_HOME_URL;/docs">
-<!ENTITY YOCTO_SOURCES_URL "&YOCTO_HOME_URL;/sources/">
-<!ENTITY YOCTO_AB_PORT_URL "&YOCTO_AB_URL;:8010">
-<!ENTITY YOCTO_AB_NIGHTLY_URL "&YOCTO_AB_URL;/nightly/">
-<!ENTITY YOCTO_POKY_URL "&YOCTO_DL_URL;/releases/poky/">
-<!ENTITY YOCTO_RELEASE_DL_URL "&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;">
-<!ENTITY YOCTO_TOOLCHAIN_DL_URL "&YOCTO_RELEASE_DL_URL;/toolchain/">
-<!ENTITY YOCTO_ADTINSTALLER_DL_URL "&YOCTO_RELEASE_DL_URL;/adt_installer">
-<!ENTITY YOCTO_POKY_DL_URL "&YOCTO_RELEASE_DL_URL;/&YOCTO_POKY;.tar.bz2">
-<!ENTITY YOCTO_MACHINES_DL_URL "&YOCTO_RELEASE_DL_URL;/machines">
-<!ENTITY YOCTO_QEMU_DL_URL "&YOCTO_MACHINES_DL_URL;/qemu">
-<!ENTITY YOCTO_PYTHON-i686_DL_URL "&YOCTO_DL_URL;/releases/miscsupport/python-nativesdk-standalone-i686.tar.bz2">
-<!ENTITY YOCTO_PYTHON-x86_64_DL_URL "&YOCTO_DL_URL;/releases/miscsupport/python-nativesdk-standalone-x86_64.tar.bz2">
-<!ENTITY YOCTO_DOCS_QS_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/yocto-project-qs/yocto-project-qs.html">
-<!ENTITY YOCTO_DOCS_ADT_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/adt-manual/adt-manual.html">
-<!ENTITY YOCTO_DOCS_REF_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/ref-manual/ref-manual.html">
-<!ENTITY YOCTO_DOCS_BSP_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/bsp-guide/bsp-guide.html">
-<!ENTITY YOCTO_DOCS_DEV_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/dev-manual/dev-manual.html">
-<!ENTITY YOCTO_DOCS_KERNEL_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/kernel-manual/kernel-manual.html">
-<!ENTITY YOCTO_ADTPATH_DIR "/opt/poky/&DISTRO;">
-<!ENTITY YOCTO_POKY_TARBALL "&YOCTO_POKY;.tar.bz2">
-<!ENTITY OE_INIT_PATH "&YOCTO_POKY;/oe-init-build-env">
-<!ENTITY OE_INIT_FILE "oe-init-build-env">
-<!ENTITY UBUNTU_HOST_PACKAGES_ESSENTIAL "gawk wget git-core diffstat unzip texinfo \
-     build-essential chrpath">
-<!ENTITY FEDORA_HOST_PACKAGES_ESSENTIAL "gawk make wget tar bzip2 gzip python unzip perl patch \
-     diffutils diffstat git cpp gcc gcc-c++ eglibc-devel texinfo chrpath \
-     ccache">
-<!ENTITY OPENSUSE_HOST_PACKAGES_ESSENTIAL "python gcc gcc-c++ git chrpath make wget python-xml \
-     diffstat texinfo python-curses">
-<!ENTITY CENTOS_HOST_PACKAGES_ESSENTIAL "gawk make wget tar bzip2 gzip python unzip perl patch \
-     diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath">

bitbake/doc/releases.rst

@@ -0,0 +1,130 @@
+.. SPDX-License-Identifier: CC-BY-2.5
+
+=========================
+ Current Release Manuals
+=========================
+
+****************************
+3.1 'dunfell' Release Series
+****************************
+
+- :yocto_docs:`3.1 BitBake User Manual </3.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`3.1.1 BitBake User Manual </3.1.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`3.1.2 BitBake User Manual </3.1.2/bitbake-user-manual/bitbake-user-manual.html>`
+
+==========================
+ Previous Release Manuals
+==========================
+
+*************************
+3.0 'zeus' Release Series
+*************************
+
+- :yocto_docs:`3.0 BitBake User Manual </3.0/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`3.0.1 BitBake User Manual </3.0.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`3.0.2 BitBake User Manual </3.0.2/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`3.0.3 BitBake User Manual </3.0.3/bitbake-user-manual/bitbake-user-manual.html>`
+
+****************************
+2.7 'warrior' Release Series
+****************************
+
+- :yocto_docs:`2.7 BitBake User Manual </2.7/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.7.1 BitBake User Manual </2.7.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.7.2 BitBake User Manual </2.7.2/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.7.3 BitBake User Manual </2.7.3/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.7.4 BitBake User Manual </2.7.4/bitbake-user-manual/bitbake-user-manual.html>`
+
+*************************
+2.6 'thud' Release Series
+*************************
+
+- :yocto_docs:`2.6 BitBake User Manual </2.6/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.6.1 BitBake User Manual </2.6.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.6.2 BitBake User Manual </2.6.2/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.6.3 BitBake User Manual </2.6.3/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.6.4 BitBake User Manual </2.6.4/bitbake-user-manual/bitbake-user-manual.html>`
+
+*************************
+2.5 'sumo' Release Series
+*************************
+
+- :yocto_docs:`2.5 BitBake User Manual </2.5/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.5.1 BitBake User Manual </2.5.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.5.2 BitBake User Manual </2.5.2/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.5.3 BitBake User Manual </2.5.3/bitbake-user-manual/bitbake-user-manual.html>`
+
+**************************
+2.4 'rocko' Release Series
+**************************
+
+- :yocto_docs:`2.4 BitBake User Manual </2.4/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.4.1 BitBake User Manual </2.4.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.4.2 BitBake User Manual </2.4.2/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.4.3 BitBake User Manual </2.4.3/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.4.4 BitBake User Manual </2.4.4/bitbake-user-manual/bitbake-user-manual.html>`
+
+*************************
+2.3 'pyro' Release Series
+*************************
+
+- :yocto_docs:`2.3 BitBake User Manual </2.3/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.3.1 BitBake User Manual </2.3.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.3.2 BitBake User Manual </2.3.2/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.3.3 BitBake User Manual </2.3.3/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.3.4 BitBake User Manual </2.3.4/bitbake-user-manual/bitbake-user-manual.html>`
+
+**************************
+2.2 'morty' Release Series
+**************************
+
+- :yocto_docs:`2.2 BitBake User Manual </2.2/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.2.1 BitBake User Manual </2.2.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.2.2 BitBake User Manual </2.2.2/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.2.3 BitBake User Manual </2.2.3/bitbake-user-manual/bitbake-user-manual.html>`
+
+****************************
+2.1 'krogoth' Release Series
+****************************
+
+- :yocto_docs:`2.1 BitBake User Manual </2.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.1.1 BitBake User Manual </2.1.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.1.2 BitBake User Manual </2.1.2/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.1.3 BitBake User Manual </2.1.3/bitbake-user-manual/bitbake-user-manual.html>`
+
+***************************
+2.0 'jethro' Release Series
+***************************
+
+- :yocto_docs:`1.9 BitBake User Manual </1.9/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.0 BitBake User Manual </2.0/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.0.1 BitBake User Manual </2.0.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.0.2 BitBake User Manual </2.0.2/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`2.0.3 BitBake User Manual </2.0.3/bitbake-user-manual/bitbake-user-manual.html>`
+
+*************************
+1.8 'fido' Release Series
+*************************
+
+- :yocto_docs:`1.8 BitBake User Manual </1.8/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`1.8.1 BitBake User Manual </1.8.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`1.8.2 BitBake User Manual </1.8.2/bitbake-user-manual/bitbake-user-manual.html>`
+
+**************************
+1.7 'dizzy' Release Series
+**************************
+
+- :yocto_docs:`1.7 BitBake User Manual </1.7/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`1.7.1 BitBake User Manual </1.7.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`1.7.2 BitBake User Manual </1.7.2/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`1.7.3 BitBake User Manual </1.7.3/bitbake-user-manual/bitbake-user-manual.html>`
+
+**************************
+1.6 'daisy' Release Series
+**************************
+
+- :yocto_docs:`1.6 BitBake User Manual </1.6/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`1.6.1 BitBake User Manual </1.6.1/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`1.6.2 BitBake User Manual </1.6.2/bitbake-user-manual/bitbake-user-manual.html>`
+- :yocto_docs:`1.6.3 BitBake User Manual </1.6.3/bitbake-user-manual/bitbake-user-manual.html>`
+

bitbake/doc/sphinx-static/switchers.js

@@ -0,0 +1,233 @@
+(function() {
+  'use strict';
+
+  var all_versions = {
+    'dev': 'dev (3.2)',
+    '3.1.2': '3.1.2',
+    '3.0.3': '3.0.3',
+    '2.7.4': '2.7.4',
+  };
+
+  var all_doctypes = {
+      'single': 'Individual Webpages',
+      'mega': "All-in-one 'Mega' Manual",
+  };
+
+  // Simple version comparision
+  // Return 1 if a > b
+  // Return -1 if a < b
+  // Return 0 if a == b
+  function ver_compare(a, b) {
+    if (a == "dev") {
+       return 1;
+    }
+
+    if (a === b) {
+       return 0;
+    }
+
+    var a_components = a.split(".");
+    var b_components = b.split(".");
+
+    var len = Math.min(a_components.length, b_components.length);
+
+    // loop while the components are equal
+    for (var i = 0; i < len; i++) {
+        // A bigger than B
+        if (parseInt(a_components[i]) > parseInt(b_components[i])) {
+            return 1;
+        }
+
+        // B bigger than A
+        if (parseInt(a_components[i]) < parseInt(b_components[i])) {
+            return -1;
+        }
+    }
+
+    // If one's a prefix of the other, the longer one is greater.
+    if (a_components.length > b_components.length) {
+        return 1;
+    }
+
+    if (a_components.length < b_components.length) {
+        return -1;
+    }
+
+    // Otherwise they are the same.
+    return 0;
+  }
+
+  function build_version_select(current_series, current_version) {
+    var buf = ['<select>'];
+
+    $.each(all_versions, function(version, title) {
+      var series = version.substr(0, 3);
+      if (series == current_series) {
+        if (version == current_version)
+            buf.push('<option value="' + version + '" selected="selected">' + title + '</option>');
+        else
+            buf.push('<option value="' + version + '">' + title + '</option>');
+
+        if (version != current_version)
+            buf.push('<option value="' + current_version + '" selected="selected">' + current_version + '</option>');
+      } else {
+        buf.push('<option value="' + version + '">' + title + '</option>');
+      }
+    });
+
+    buf.push('</select>');
+    return buf.join('');
+  }
+
+  function build_doctype_select(current_doctype) {
+    var buf = ['<select>'];
+
+    $.each(all_doctypes, function(doctype, title) {
+      if (doctype == current_doctype)
+        buf.push('<option value="' + doctype + '" selected="selected">' +
+                 all_doctypes[current_doctype] + '</option>');
+      else
+        buf.push('<option value="' + doctype + '">' + title + '</option>');
+    });
+    if (!(current_doctype in all_doctypes)) {
+        // In case we're browsing a doctype that is not yet in all_doctypes.
+        buf.push('<option value="' + current_doctype + '" selected="selected">' +
+                 current_doctype + '</option>');
+        all_doctypes[current_doctype] = current_doctype;
+    }
+    buf.push('</select>');
+    return buf.join('');
+  }
+
+  function navigate_to_first_existing(urls) {
+    // Navigate to the first existing URL in urls.
+    var url = urls.shift();
+
+    // Web browsers won't redirect file:// urls to file urls using ajax but
+    // its useful for local testing
+    if (url.startsWith("file://")) {
+      window.location.href = url;
+      return;
+    }
+
+    if (urls.length == 0) {
+      window.location.href = url;
+      return;
+    }
+    $.ajax({
+      url: url,
+      success: function() {
+        window.location.href = url;
+      },
+      error: function() {
+        navigate_to_first_existing(urls);
+      }
+    });
+  }
+
+  function get_docroot_url() {
+    var url = window.location.href;
+    var root = DOCUMENTATION_OPTIONS.URL_ROOT;
+
+    var urlarray = url.split('/');
+    // Trim off anything after '/'
+    urlarray.pop();
+    var depth = (root.match(/\.\.\//g) || []).length;
+    for (var i = 0; i < depth; i++) {
+      urlarray.pop();
+    }
+
+    return urlarray.join('/') + '/';
+  }
+
+  function on_version_switch() {
+    var selected_version = $(this).children('option:selected').attr('value');
+    var url = window.location.href;
+    var current_version = DOCUMENTATION_OPTIONS.VERSION;
+    var docroot = get_docroot_url()
+
+    var new_versionpath = selected_version + '/';
+    if (selected_version == "dev")
+        new_versionpath = '';
+
+    // dev versions have no version prefix
+    if (current_version == "dev") {
+        var new_url = docroot + new_versionpath + url.replace(docroot, "");
+        var fallback_url = docroot + new_versionpath;
+    } else {
+        var new_url = url.replace('/' + current_version + '/', '/' + new_versionpath);
+        var fallback_url = new_url.replace(url.replace(docroot, ""), "");
+    }
+
+    console.log(get_docroot_url())
+    console.log(url + " to url " + new_url);
+    console.log(url + " to fallback " + fallback_url);
+
+    if (new_url != url) {
+      navigate_to_first_existing([
+        new_url,
+        fallback_url,
+        'https://www.yoctoproject.org/docs/',
+      ]);
+    }
+  }
+
+  function on_doctype_switch() {
+    var selected_doctype = $(this).children('option:selected').attr('value');
+    var url = window.location.href;
+    if (selected_doctype == 'mega') {
+      var docroot = get_docroot_url()
+      var current_version = DOCUMENTATION_OPTIONS.VERSION;
+      // Assume manuals before 3.2 are using old docbook mega-manual
+      if (ver_compare(current_version, "3.2") < 0) {
+        var new_url = docroot + "mega-manual/mega-manual.html";
+      } else {
+        var new_url = docroot + "singleindex.html";
+      }
+    } else {
+      var new_url = url.replace("singleindex.html", "index.html")
+    }
+
+    if (new_url != url) {
+      navigate_to_first_existing([
+        new_url,
+        'https://www.yoctoproject.org/docs/',
+      ]);
+    }
+  }
+
+  // Returns the current doctype based upon the url
+  function doctype_segment_from_url(url) {
+    if (url.includes("singleindex") || url.includes("mega-manual"))
+      return "mega";
+    return "single";
+  }
+
+  $(document).ready(function() {
+    var release = DOCUMENTATION_OPTIONS.VERSION;
+    var current_doctype = doctype_segment_from_url(window.location.href);
+    var current_series = release.substr(0, 3);
+    var version_select = build_version_select(current_series, release);
+
+    $('.version_switcher_placeholder').html(version_select);
+    $('.version_switcher_placeholder select').bind('change', on_version_switch);
+
+    var doctype_select = build_doctype_select(current_doctype);
+
+    $('.doctype_switcher_placeholder').html(doctype_select);
+    $('.doctype_switcher_placeholder select').bind('change', on_doctype_switch);
+
+    if (ver_compare(release, "3.1") < 0) {
+      $('#outdated-warning').html('Version ' + release + ' of the project is now considered obsolete, please select and use a more recent version');
+      $('#outdated-warning').css('padding', '.5em');
+    } else if (release != "dev") {
+      $.each(all_versions, function(version, title) {
+        var series = version.substr(0, 3);
+        if (series == current_series && version != release) {
+          $('#outdated-warning').html('This document is for outdated version ' + release + ', you should select the latest release version in this series, ' + version + '.');
+          $('#outdated-warning').css('padding', '.5em');
+        }
+      });
+    }
+  });
+})();

bitbake/doc/sphinx-static/theme_overrides.css

@@ -0,0 +1,162 @@
+/*
+    SPDX-License-Identifier: CC-BY-2.0-UK
+*/
+
+body {
+  font-family: Verdana, Sans, sans-serif;
+  margin:  0em auto;
+  color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+  font-family: Arial, Sans;
+  color: #00557D;
+  clear: both;
+}
+
+h1 {
+  font-size: 2em;
+  text-align: left;
+  padding: 0em 0em 0em 0em;
+  margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+  margin: 0.10em 0em 3.0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 1.8em;
+  padding-left: 20%;
+  font-weight: normal;
+  font-style: italic;
+}
+
+h2 {
+  margin: 2em 0em 0.66em 0em;
+  padding: 0.5em 0em 0em 0em;
+  font-size: 1.5em;
+  font-weight: bold;
+}
+
+h3.subtitle {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 142.14%;
+  text-align: right;
+}
+
+h3 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 140%;
+  font-weight: bold;
+}
+
+h4 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 120%;
+  font-weight: bold;
+}
+
+h5 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+h6 {
+  margin: 1em 0em 0em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+em {
+  font-weight: bold;
+}
+
+.pre {
+  font-size: medium;
+  font-family: Courier, monospace;
+}
+
+.wy-nav-content a {
+  text-decoration: underline;
+  color: #444;
+  background: transparent;
+}
+
+.wy-nav-content a:hover {
+  text-decoration: underline;
+  background-color: #dedede;
+}
+
+.wy-nav-content a:visited {
+  color: #444;
+}
+
+[alt='Permalink'] { color: #eee; }
+[alt='Permalink']:hover { color: black; }
+
+@media screen {
+    /* content column
+     *
+     * RTD theme's default is 800px as max width for the content, but we have
+     * tables with tons of columns, which need the full width of the view-port.
+     */
+
+    .wy-nav-content{max-width: none; }
+
+    /* inline literal: drop the borderbox, padding and red color */
+    code, .rst-content tt, .rst-content code {
+        color: inherit;
+        border: none;
+        padding: unset;
+        background: inherit;
+        font-size: 85%;
+    }
+
+    .rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal {
+        color: inherit;
+    }
+
+    /* Admonition should be gray, not blue or green */
+    .rst-content .note .admonition-title,
+    .rst-content .tip .admonition-title,
+    .rst-content .warning .admonition-title,
+    .rst-content .caution .admonition-title,
+    .rst-content .important .admonition-title {
+        background: #f0f0f2;
+        color: #00557D;
+
+    }
+
+    .rst-content .note,
+    .rst-content .tip,
+    .rst-content .important,
+    .rst-content .warning,
+    .rst-content .caution  {
+        background: #f0f0f2;
+    }
+
+    /* Remove the icon in front of note/tip element, and before the logo */
+    .icon-home:before, .rst-content .admonition-title:before {
+        display: none
+    }
+
+    /* a custom informalexample container is used in some doc */
+    .informalexample {
+        border: 1px solid;
+        border-color: #aaa;
+        margin: 1em 0em;
+        padding: 1em;
+        page-break-inside: avoid;
+    }
+
+    /* Remove the blue background in the top left corner, around the logo */
+    .wy-side-nav-search {
+        background: inherit;
+    }
+
+}

bitbake/doc/template/component.title.xsl

@@ -1,39 +0,0 @@
-<xsl:stylesheet version="1.0"
-  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-  xmlns:d="http://docbook.org/ns/docbook"
-  xmlns="http://www.w3.org/1999/xhtml"
-  exclude-result-prefixes="d">
-  
-  <xsl:template name="component.title">
-    <xsl:param name="node" select="."/>
-    
-    <xsl:variable name="level">
-      <xsl:choose>
-        <xsl:when test="ancestor::d:section">
-          <xsl:value-of select="count(ancestor::d:section)+1"/>
-        </xsl:when>
-        <xsl:when test="ancestor::d:sect5">6</xsl:when>
-        <xsl:when test="ancestor::d:sect4">5</xsl:when>
-        <xsl:when test="ancestor::d:sect3">4</xsl:when>
-        <xsl:when test="ancestor::d:sect2">3</xsl:when>
-        <xsl:when test="ancestor::d:sect1">2</xsl:when>
-        <xsl:otherwise>1</xsl:otherwise>
-      </xsl:choose>
-    </xsl:variable>
-    <xsl:element name="h{$level+1}" namespace="http://www.w3.org/1999/xhtml">
-      <xsl:attribute name="class">title</xsl:attribute>
-      <xsl:if test="$generate.id.attributes = 0">
-        <xsl:call-template name="anchor">
-          <xsl:with-param name="node" select="$node"/>
-          <xsl:with-param name="conditional" select="0"/>
-        </xsl:call-template>
-      </xsl:if>
-      <xsl:apply-templates select="$node" mode="object.title.markup">
-        <xsl:with-param name="allow-anchors" select="1"/>
-      </xsl:apply-templates>
-      <xsl:call-template name="permalink">
-        <xsl:with-param name="node" select="$node"/>
-      </xsl:call-template>
-    </xsl:element>
-  </xsl:template>
-</xsl:stylesheet>

bitbake/doc/template/db-pdf.xsl

@@ -1,64 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
-  
-  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl" />
-
-  <!-- check project-plan.sh for how this is generated, needed to tweak 
-       the cover page     
-    -->
-  <xsl:include href="/tmp/titlepage.xsl"/> 
-
-  <!-- To force a page break in document, i.e per section add a 
-      <?hard-pagebreak?> tag.
-  -->
- <xsl:template match="processing-instruction('hard-pagebreak')">
-   <fo:block break-before='page' />
- </xsl:template>
-
-  <!--Fix for defualt indent getting TOC all wierd..
-      See http://sources.redhat.com/ml/docbook-apps/2005-q1/msg00455.html 
-      FIXME: must be a better fix
-    -->
-  <xsl:param name="body.start.indent" select="'0'"/>
-  <!--<xsl:param name="title.margin.left" select="'0'"/>-->
-
-  <!-- stop long-ish header titles getting wrapped -->
-  <xsl:param name="header.column.widths">1 10 1</xsl:param>
-
-  <!-- customise headers and footers a little --> 
-
-  <xsl:template name="head.sep.rule">
-   <xsl:if test="$header.rule != 0">
-     <xsl:attribute name="border-bottom-width">0.5pt</xsl:attribute>
-     <xsl:attribute name="border-bottom-style">solid</xsl:attribute>
-     <xsl:attribute name="border-bottom-color">#cccccc</xsl:attribute>
-   </xsl:if>
-  </xsl:template>
-
-  <xsl:template name="foot.sep.rule">
-    <xsl:if test="$footer.rule != 0">
-     <xsl:attribute name="border-top-width">0.5pt</xsl:attribute>
-     <xsl:attribute name="border-top-style">solid</xsl:attribute>
-     <xsl:attribute name="border-top-color">#cccccc</xsl:attribute>
-    </xsl:if>
-  </xsl:template>
-
-  <xsl:attribute-set name="header.content.properties">
-    <xsl:attribute name="color">#cccccc</xsl:attribute>
-  </xsl:attribute-set>
-
-  <xsl:attribute-set name="footer.content.properties">
-    <xsl:attribute name="color">#cccccc</xsl:attribute>
-  </xsl:attribute-set>
-
- 
-  <!-- general settings -->
-
-  <xsl:param name="fop1.extensions" select="1"></xsl:param>
-  <xsl:param name="paper.type" select="'A4'"></xsl:param>
-  <xsl:param name="section.autolabel" select="1"></xsl:param>
-  <xsl:param name="body.font.family" select="'verasans'"></xsl:param>
-  <xsl:param name="title.font.family" select="'verasans'"></xsl:param>
-  <xsl:param name="monospace.font.family" select="'veramono'"></xsl:param>
-
-</xsl:stylesheet>

bitbake/doc/template/division.title.xsl

@@ -1,25 +0,0 @@
-<xsl:stylesheet version="1.0"
-  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-  xmlns:d="http://docbook.org/ns/docbook"
-  xmlns="http://www.w3.org/1999/xhtml"
-  exclude-result-prefixes="d">
-  
-  <xsl:template name="division.title">
-    <xsl:param name="node" select="."/>
-    
-    <h1>
-      <xsl:attribute name="class">title</xsl:attribute>
-      <xsl:call-template name="anchor">
-        <xsl:with-param name="node" select="$node"/>
-        <xsl:with-param name="conditional" select="0"/>
-      </xsl:call-template>
-      <xsl:apply-templates select="$node" mode="object.title.markup">
-        <xsl:with-param name="allow-anchors" select="1"/>
-      </xsl:apply-templates>
-      <xsl:call-template name="permalink">
-        <xsl:with-param name="node" select="$node"/>
-      </xsl:call-template>
-    </h1>
-  </xsl:template>
-</xsl:stylesheet>
-

bitbake/doc/template/fop-config.xml

@@ -1,58 +0,0 @@
-<fop version="1.0">
-
-  <!-- Strict user configuration -->
-  <strict-configuration>true</strict-configuration>
-
-  <!-- Strict FO validation -->
-  <strict-validation>true</strict-validation>
-
-   <!--
-    Set the baseDir so common/openedhand.svg references in plans still
-    work ok. Note, relative file references to current dir should still work.
-    -->	
-  <base>../template</base>
-  <font-base>../template</font-base>
- 
-  <!-- Source resolution in dpi (dots/pixels per inch) for determining the
-       size of pixels in SVG and bitmap images, default: 72dpi -->
-  <!-- <source-resolution>72</source-resolution> -->
-  <!-- Target resolution in dpi (dots/pixels per inch) for specifying the
-       target resolution for generated bitmaps, default: 72dpi -->
-  <!-- <target-resolution>72</target-resolution> -->
- 
-  <!-- default page-height and page-width, in case
-       value is specified as auto -->
-  <default-page-settings height="11in" width="8.26in"/> 
- 
-  <!-- <use-cache>false</use-cache> -->
- 
-  <renderers>
-    <renderer mime="application/pdf">
-      <fonts>
-        <font  metrics-file="VeraMono.xml"
-               kerning="yes" 
-               embed-url="VeraMono.ttf">
-          <font-triplet name="veramono" style="normal" weight="normal"/>
-        </font>
-
-        <font  metrics-file="VeraMoBd.xml"
-               kerning="yes" 
-               embed-url="VeraMoBd.ttf">
-          <font-triplet name="veramono" style="normal" weight="bold"/>
-        </font>
-
-        <font  metrics-file="Vera.xml"
-               kerning="yes" 
-               embed-url="Vera.ttf">
-          <font-triplet name="verasans" style="normal" weight="normal"/>
-          <font-triplet name="verasans" style="normal" weight="bold"/>
-          <font-triplet name="verasans" style="italic" weight="normal"/>
-          <font-triplet name="verasans" style="italic" weight="bold"/>
-        </font>
-        
-        <auto-detect/>
-      </fonts>
-    </renderer>
-  </renderers>
-</fop>
-

bitbake/doc/template/formal.object.heading.xsl

@@ -1,21 +0,0 @@
-<xsl:stylesheet version="1.0"
-  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-  xmlns:d="http://docbook.org/ns/docbook"
-  xmlns="http://www.w3.org/1999/xhtml"
-  exclude-result-prefixes="d">
-  
-  <xsl:template name="formal.object.heading">
-    <xsl:param name="object" select="."/>
-    <xsl:param name="title">
-      <xsl:apply-templates select="$object" mode="object.title.markup">
-        <xsl:with-param name="allow-anchors" select="1"/>
-      </xsl:apply-templates>
-    </xsl:param>
-    <p class="title">
-      <b><xsl:copy-of select="$title"/></b>
-      <xsl:call-template name="permalink">
-        <xsl:with-param name="node" select="$object"/>
-      </xsl:call-template>
-    </p>
-  </xsl:template>
-</xsl:stylesheet>

bitbake/doc/template/gloss-permalinks.xsl

@@ -1,14 +0,0 @@
-<xsl:stylesheet version="1.0"
-  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-  xmlns:d="http://docbook.org/ns/docbook"
-  xmlns="http://www.w3.org/1999/xhtml">
-
-  <xsl:template match="glossentry/glossterm">
-    <xsl:apply-imports/>
-    <xsl:if test="$generate.permalink != 0">
-      <xsl:call-template name="permalink">
-        <xsl:with-param name="node" select=".."/>
-      </xsl:call-template>
-    </xsl:if>
-  </xsl:template>
-</xsl:stylesheet>

bitbake/doc/template/permalinks.xsl

@@ -1,25 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<xsl:stylesheet version="1.0"
-  xmlns="http://www.w3.org/1999/xhtml"
-  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
-
-  <xsl:param name="generate.permalink" select="1"/>
-  <xsl:param name="permalink.text">¶</xsl:param>
-
-  <xsl:template name="permalink">
-    <xsl:param name="node"/>
-
-    <xsl:if test="$generate.permalink != '0'">
-      <span class="permalink">
-        <a alt="Permalink" title="Permalink">
-          <xsl:attribute name="href">
-            <xsl:call-template name="href.target">
-              <xsl:with-param name="object"  select="$node"/>
-            </xsl:call-template>
-          </xsl:attribute>
-          <xsl:copy-of select="$permalink.text"/>
-        </a>
-      </span>
-    </xsl:if>
-  </xsl:template>
-</xsl:stylesheet>

bitbake/doc/template/section.title.xsl

@@ -1,55 +0,0 @@
-<xsl:stylesheet version="1.0"
-  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-  xmlns:d="http://docbook.org/ns/docbook"
-  xmlns="http://www.w3.org/1999/xhtml" exclude-result-prefixes="d">
-
-  <xsl:template name="section.title">
-    <xsl:variable name="section"
-      select="(ancestor::section |
-               ancestor::simplesect|
-               ancestor::sect1|
-               ancestor::sect2|
-               ancestor::sect3|
-               ancestor::sect4|
-               ancestor::sect5)[last()]"/>
-
-    <xsl:variable name="renderas">
-      <xsl:choose>
-        <xsl:when test="$section/@renderas = 'sect1'">1</xsl:when>
-        <xsl:when test="$section/@renderas = 'sect2'">2</xsl:when>
-        <xsl:when test="$section/@renderas = 'sect3'">3</xsl:when>
-        <xsl:when test="$section/@renderas = 'sect4'">4</xsl:when>
-        <xsl:when test="$section/@renderas = 'sect5'">5</xsl:when>
-        <xsl:otherwise><xsl:value-of select="''"/></xsl:otherwise>
-      </xsl:choose>
-    </xsl:variable>
-
-    <xsl:variable name="level">
-      <xsl:choose>
-        <xsl:when test="$renderas != ''">
-          <xsl:value-of select="$renderas"/>
-        </xsl:when>
-        <xsl:otherwise>
-          <xsl:call-template name="section.level">
-            <xsl:with-param name="node" select="$section"/>
-          </xsl:call-template>
-        </xsl:otherwise>
-      </xsl:choose>
-    </xsl:variable>
-
-    <xsl:call-template name="section.heading">
-      <xsl:with-param name="section" select="$section"/>
-      <xsl:with-param name="level" select="$level"/>
-      <xsl:with-param name="title">
-        <xsl:apply-templates select="$section" mode="object.title.markup">
-          <xsl:with-param name="allow-anchors" select="1"/>
-        </xsl:apply-templates>
-        <xsl:if test="$level &gt; 0">
-          <xsl:call-template name="permalink">
-            <xsl:with-param name="node" select="$section"/>
-          </xsl:call-template>
-        </xsl:if>
-      </xsl:with-param>
-    </xsl:call-template>
-  </xsl:template>
-</xsl:stylesheet>

bitbake/doc/tools/docbook-to-pdf

@@ -1,51 +0,0 @@
-#!/bin/sh
-	
-if [ -z "$1" -o -z "$2" ]; then
-   echo "usage: [-v] $0 <docbook file> <templatedir>"
-   echo
-   echo "*NOTE* you need xsltproc, fop and nwalsh docbook stylesheets" 
-   echo "       installed for this to work!"
-   echo
-   exit 0
-fi
-
-FO=`echo $1 | sed s/.xml/.fo/` || exit 1
-PDF=`echo $1 | sed s/.xml/.pdf/` || exit 1
-TEMPLATEDIR=$2
-
-##
-# These URI should be rewritten by your distribution's xml catalog to
-# match your localy installed XSL stylesheets.
-XSL_BASE_URI="http://docbook.sourceforge.net/release/xsl/current"
-
-# Creates a temporary XSL stylesheet based on titlepage.xsl
-xsltproc -o /tmp/titlepage.xsl                                           \
-	 --xinclude                                                      \
-         $XSL_BASE_URI/template/titlepage.xsl \
-         $TEMPLATEDIR/titlepage.templates.xml || exit 1
-
-# Creates the file needed for FOP
-xsltproc --xinclude                    \
-	 --stringparam hyphenate false \
-	 --stringparam formal.title.placement "figure after" \
-	 --stringparam ulink.show 1 \
-         --stringparam  body.font.master  9 \
-         --stringparam  title.font.master  11 \
-         --stringparam draft.watermark.image "$TEMPLATEDIR/draft.png" \
-         --stringparam  chapter.autolabel 1 \
-         --stringparam  appendix.autolabel A \
-         --stringparam  section.autolabel 1 \
-         --stringparam  section.label.includes.component.label 1 \
-         --output $FO               \
-         $TEMPLATEDIR/db-pdf.xsl    \
-	 $1                 || exit 1
-
-# Invokes the Java version of FOP.  Uses the additional configuration file common/fop-config.xml
-fop -c $TEMPLATEDIR/fop-config.xml -fo $FO -pdf $PDF       || exit 1
-
-rm -f $FO
-rm -f  /tmp/titlepage.xsl
-
-echo
-echo " #### Success! $PDF ready. ####"
-echo

bitbake/lib/bb/fetch2/git.py

@@ -236,7 +236,7 @@ class Git(FetchMethod):
                     ud.unresolvedrev[name] = ud.revisions[name]
                 ud.revisions[name] = self.latest_revision(ud, d, name)
 
-        gitsrcname = '%s%s' % (ud.host.replace(':', '.'), ud.path.replace('/', '.').replace('*', '.'))
+        gitsrcname = '%s%s' % (ud.host.replace(':', '.'), ud.path.replace('/', '.').replace('*', '.').replace(' ','_'))
         if gitsrcname.startswith('.'):
             gitsrcname = gitsrcname[1:]
 
@@ -342,7 +342,7 @@ class Git(FetchMethod):
             # We do this since git will use a "-l" option automatically for local urls where possible
             if repourl.startswith("file://"):
                 repourl = repourl[7:]
-            clone_cmd = "LANG=C %s clone --bare --mirror %s %s --progress" % (ud.basecmd, repourl, ud.clonedir)
+            clone_cmd = "LANG=C %s clone --bare --mirror \"%s\" %s --progress" % (ud.basecmd, repourl, ud.clonedir)
             if ud.proto.lower() != 'file':
                 bb.fetch2.check_network_access(d, clone_cmd, ud.url)
             progresshandler = GitProgressHandler(d)
@@ -354,8 +354,8 @@ class Git(FetchMethod):
             if "origin" in output:
               runfetchcmd("%s remote rm origin" % ud.basecmd, d, workdir=ud.clonedir)
 
-            runfetchcmd("%s remote add --mirror=fetch origin %s" % (ud.basecmd, repourl), d, workdir=ud.clonedir)
-            fetch_cmd = "LANG=C %s fetch -f --progress %s refs/*:refs/*" % (ud.basecmd, repourl)
+            runfetchcmd("%s remote add --mirror=fetch origin \"%s\"" % (ud.basecmd, repourl), d, workdir=ud.clonedir)
+            fetch_cmd = "LANG=C %s fetch -f --progress \"%s\" refs/*:refs/*" % (ud.basecmd, repourl)
             if ud.proto.lower() != 'file':
                 bb.fetch2.check_network_access(d, fetch_cmd, ud.url)
             progresshandler = GitProgressHandler(d)
@@ -501,7 +501,7 @@ class Git(FetchMethod):
             raise bb.fetch2.UnpackError("No up to date source found: " + "; ".join(source_error), ud.url)
 
         repourl = self._get_repo_url(ud)
-        runfetchcmd("%s remote set-url origin %s" % (ud.basecmd, repourl), d, workdir=destdir)
+        runfetchcmd("%s remote set-url origin \"%s\"" % (ud.basecmd, repourl), d, workdir=destdir)
 
         if self._contains_lfs(ud, d, destdir):
             if need_lfs and not self._find_git_lfs(d):
@@ -613,7 +613,7 @@ class Git(FetchMethod):
         d.setVar('_BB_GIT_IN_LSREMOTE', '1')
         try:
             repourl = self._get_repo_url(ud)
-            cmd = "%s ls-remote %s %s" % \
+            cmd = "%s ls-remote \"%s\" %s" % \
                 (ud.basecmd, repourl, search)
             if ud.proto.lower() != 'file':
                 bb.fetch2.check_network_access(d, cmd, repourl)

bitbake/lib/bb/tests/fetch.py

@@ -223,6 +223,21 @@ class URITest(unittest.TestCase):
             'query': {},
             'relative': False
         },
+        "git://tfs-example.org:22/tfs/example%20path/example.git": {
+            'uri': 'git://tfs-example.org:22/tfs/example%20path/example.git',
+            'scheme': 'git',
+            'hostname': 'tfs-example.org',
+            'port': 22,
+            'hostport': 'tfs-example.org:22',
+            'path': '/tfs/example path/example.git',
+            'userinfo': '',
+            'userinfo': '',
+            'username': '',
+            'password': '',
+            'params': {},
+            'query': {},
+            'relative': False
+        },
         "http://somesite.net;someparam=1": {
             'uri': 'http://somesite.net;someparam=1',
             'scheme': 'http',
@@ -903,7 +918,7 @@ class FetcherNetworkTest(FetcherTest):
     def test_git_submodule_dbus_broker(self):
         # The following external repositories have show failures in fetch and unpack operations
         # We want to avoid regressions!
-        url = "gitsm://github.com/bus1/dbus-broker;protocol=git;rev=fc874afa0992d0c75ec25acb43d344679f0ee7d2"
+        url = "gitsm://github.com/bus1/dbus-broker;protocol=git;rev=fc874afa0992d0c75ec25acb43d344679f0ee7d2;branch=main"
         fetcher = bb.fetch.Fetch([url], self.d)
         fetcher.download()
         # Previous cwd has been deleted
@@ -2080,6 +2095,38 @@ class GitLfsTest(FetcherTest):
         shutil.rmtree(self.gitdir, ignore_errors=True)
         fetcher.unpack(self.d.getVar('WORKDIR'))
 
+class GitURLWithSpacesTest(FetcherTest):
+    test_git_urls = {
+        "git://tfs-example.org:22/tfs/example%20path/example.git" : {
+            'url': 'git://tfs-example.org:22/tfs/example%20path/example.git',
+            'gitsrcname': 'tfs-example.org.22.tfs.example_path.example.git',
+            'path': '/tfs/example path/example.git'
+        },
+        "git://tfs-example.org:22/tfs/example%20path/example%20repo.git" : {
+            'url': 'git://tfs-example.org:22/tfs/example%20path/example%20repo.git',
+            'gitsrcname': 'tfs-example.org.22.tfs.example_path.example_repo.git',
+            'path': '/tfs/example path/example repo.git'
+        }
+    }
+
+    def test_urls(self):
+
+        # Set fake SRCREV to stop git fetcher from trying to contact non-existent git repo
+        self.d.setVar('SRCREV', '82ea737a0b42a8b53e11c9cde141e9e9c0bd8c40')
+
+        for test_git_url, ref in self.test_git_urls.items():
+
+            fetcher = bb.fetch.Fetch([test_git_url], self.d)
+            ud = fetcher.ud[fetcher.urls[0]]
+
+            self.assertEqual(ud.url, ref['url'])
+            self.assertEqual(ud.path, ref['path'])
+            self.assertEqual(ud.localfile, os.path.join(self.dldir, "git2", ref['gitsrcname']))
+            self.assertEqual(ud.localpath, os.path.join(self.dldir, "git2", ref['gitsrcname']))
+            self.assertEqual(ud.lockfile, os.path.join(self.dldir, "git2", ref['gitsrcname'] + '.lock'))
+            self.assertEqual(ud.clonedir, os.path.join(self.dldir, "git2", ref['gitsrcname']))
+            self.assertEqual(ud.fullmirror, os.path.join(self.dldir, "git2_" + ref['gitsrcname'] + '.tar.gz'))
+
 class NPMTest(FetcherTest):
     def skipIfNoNpm():
         import shutil

bitbake/lib/bb/ui/taskexp.py

@@ -58,7 +58,12 @@ class PackageReverseDepView(Gtk.TreeView):
         self.current = None
         self.filter_model = model.filter_new()
         self.filter_model.set_visible_func(self._filter)
-        self.sort_model = self.filter_model.sort_new_with_model()
+        # The introspected API was fixed but we can't rely on a pygobject that hides this.
+        # https://gitlab.gnome.org/GNOME/pygobject/-/commit/9cdbc56fbac4db2de78dc080934b8f0a7efc892a
+        if hasattr(Gtk.TreeModelSort, "new_with_model"):
+            self.sort_model = Gtk.TreeModelSort.new_with_model(self.filter_model)
+        else:
+            self.sort_model = self.filter_model.sort_new_with_model()
         self.sort_model.set_sort_column_id(COL_DEP_PARENT, Gtk.SortType.ASCENDING)
         self.set_model(self.sort_model)
         self.append_column(Gtk.TreeViewColumn(label, Gtk.CellRendererText(), text=COL_DEP_PARENT))

documentation/.gitignore

@@ -0,0 +1,2 @@
+_build/
+Pipfile.lock

documentation/Makefile

@@ -1,431 +1,35 @@
-# This is a single Makefile to handle all generated Yocto Project documents,
-# which includes the BitBake User Manual and the Toaster User Manual.
-# The Makefile needs to live in the documents directory and all figures used
-# in any manuals must be .PNG files and live in the individual book's figures
-# directory as well as in the figures directory for the mega-manual.
+# Minimal makefile for Sphinx documentation
 #
-# Note that the figures for the Yocto Project Development Tasks Manual
-# differ depending on the BRANCH being built.
-#
-# The Makefile has these targets:
-#    all:       If you leave off the target then "all" is implied.
-#               You will generate HTML and a tarball of files.
-#
-#    pdf:	generates a PDF version of a manual.  Not valid for the
-#		Quick Start or the mega-manual (single, large HTML file
-#		comprised of all Yocto Project manuals).
-#    html:	generates an HTML version of a manual.
-#    tarball:	creates a tarball for the doc files.
-#    validate:	validates
-#    publish:	pushes generated files to the Yocto Project website
-#    clean:	removes files
-#
-# The Makefile can generate an HTML and PDF version of every document except the
-# Yocto Project Quick Start and the single, HTML mega-manual, which is comprised
-# of all the individual Yocto Project manuals.  You can generate these two manuals
-# in HTML form only.  The variable DOC indicates the folder name for a given manual.
-# The variable VER represents the distro version of the Yocto Release for which the
-# manuals are being generated.  The variable BRANCH is used to indicate the
-# branch (edison or denzil) and is used only when DOC=dev-manual or
-# DOC=mega-manual.  If you do not specify a BRANCH, the default branch used
-# will be for the latest Yocto Project release.  If you build for either
-# edison or denzil, you must use BRANCH. You do not need to use BRANCH for
-# any release beyond denzil.
-#
-# To build a manual, you must invoke Makefile with the DOC argument.  If you
-# are going to publish the manual, then you must invoke Makefile with both the
-# DOC and the VER argument.  Furthermore, if you are building or publishing
-# the edison or denzil versions of the Yocto Project Development Tasks Manual or
-# the mega-manual, you must also use the BRANCH argument.
-#
-# Examples:
-#
-#     make DOC=bsp-guide
-#     make html DOC=brief-yoctoprojectqs
-#     make pdf DOC=ref-manual
-#     make DOC=dev-manual BRANCH=edison
-#     make DOC=mega-manual BRANCH=denzil
-#
-# The first example generates the HTML version of the BSP Guide.
-# The second example generates the HTML version only of the Quick Start.  Note
-# that the Quick Start only has an HTML version available.  So, the
-# 'make DOC=brief-yoctoprojectqs' command would be equivalent. The third example
-# generates just the PDF version of the Yocto Project Reference Manual.
-# The fourth example generates the HTML 'edison' version of the YP Development
-# Tasks Manual.  The last example
-# generates the HTML version of the mega-manual and uses the 'denzil'
-# branch when choosing figures for the tarball of figures.  Any example that does
-# not use the BRANCH argument builds the current version of the manual set.
-#
-# The publish target pushes the generated manuals to the Yocto Project
-# website.  Unless you are a developer on the YP team, you will not succeed in
-# pushing manuals to this server.  All files needed for the manual's HTML form are
-# pushed.
-#
-# Examples:
-#
-#    make publish DOC=bsp-guide VER=1.7
-#    make publish DOC=adt-manual VER=1.6
-#    make publish DOC=dev-manual VER=1.1.1 BRANCH=edison
-#    make publish DOC=dev-manual VER=1.2 BRANCH=denzil
-#
-# The first example publishes the 1.7 version of both the PDF and HTML versions of
-# the BSP Guide.  The second example publishes the 1.6 version of both the PDF and
-# HTML versions of the ADT Manual. The third example publishes the 1.1.1 version of
-# the PDF and HTML YP Development Tasks Manual for the 'edison' branch.  The fourth
-# example publishes the 1.2 version of the PDF and HTML YP Development Tasks Manual
-# for the 'denzil' branch.
-#
-# IN MEMORIAM: This comment is to remember Scott Rifenbark (scottrif), whom we lost
-# in January, 2020. Scott was the primary technical writer for the Yocto Project for
-# over 9 years. In that time, he contributed many thousands of patches, built this
-# documentation tree, and enabled tens of thousands of developers to succeed with
-# embedded Linux. He ran this Makefile many thousands of times. Godspeed, Dude.
 
-ifeq ($(DOC),brief-yoctoprojectqs)
-XSLTOPTS = --stringparam html.stylesheet brief-yoctoprojectqs-style.css \
-           --stringparam  chapter.autolabel 0 \
-           --stringparam  section.autolabel 0 \
-           --stringparam  section.label.includes.component.label 0 \
-           --xinclude
-ALLPREQ = html tarball
-TARFILES = brief-yoctoprojectqs-style.css brief-yoctoprojectqs.html figures/bypqs-title.png \
-           figures/yocto-project-transp.png
-MANUALS = $(DOC)/$(DOC).html
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -j auto
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+DESTDIR       = final
 
+ifeq ($(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi),0)
+$(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed")
 endif
 
-ifeq ($(DOC),overview-manual)
-XSLTOPTS = --xinclude
-ALLPREQ = html tarball
-TARFILES = overview-manual-style.css overview-manual.html figures/overview-manual-title.png \
-           figures/git-workflow.png figures/source-repos.png figures/index-downloads.png \
-           figures/yp-download.png figures/YP-flow-diagram.png figures/key-dev-elements.png \
-           figures/poky-reference-distribution.png figures/cross-development-toolchains.png \
-           figures/user-configuration.png figures/layer-input.png figures/source-input.png \
-           figures/package-feeds.png figures/patching.png figures/source-fetching.png \
-           figures/configuration-compile-autoreconf.png figures/analysis-for-package-splitting.png \
-           figures/image-generation.png figures/sdk-generation.png figures/images.png \
-           figures/sdk.png
-MANUALS = $(DOC)/$(DOC).html
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-endif
+.PHONY: help Makefile clean publish
 
-ifeq ($(DOC),bsp-guide)
-XSLTOPTS = --xinclude
-ALLPREQ = html tarball
-TARFILES = bsp-style.css bsp-guide.html figures/bsp-title.png \
-           figures/bsp-dev-flow.png
-MANUALS = $(DOC)/$(DOC).html
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
-
-endif
-
-ifeq ($(DOC),dev-manual)
-XSLTOPTS = --xinclude
-ALLPREQ = html tarball
-#
-# Note that the tarfile might produce the "Cannot stat: No such file or
-# directory" error message for .PNG files that are not present when building
-# a particular branch.  The list of files is all-inclusive for all branches.
-# Note, if you don't provide a BRANCH option, it defaults to the latest stuff.
-# This would be appropriate for "master" branch.
-#
-
-	ifeq ($(BRANCH),edison)
-TARFILES = dev-style.css dev-manual.html \
-           figures/app-dev-flow.png figures/bsp-dev-flow.png \
-           figures/dev-title.png figures/git-workflow.png \
-           figures/index-downloads.png figures/kernel-dev-flow.png \
-           figures/kernel-example-repos-edison.png \
-           figures/kernel-overview-1.png figures/kernel-overview-2.png \
-           figures/kernel-overview-3-edison.png \
-           figures/source-repos.png figures/yp-download.png \
-           figures/wip.png
-	else ifeq ($(BRANCH),denzil)
-TARFILES = dev-style.css dev-manual.html \
-           figures/app-dev-flow.png figures/bsp-dev-flow.png \
-           figures/dev-title.png figures/git-workflow.png \
-           figures/index-downloads.png figures/kernel-dev-flow.png \
-           figures/kernel-example-repos-denzil.png \
-           figures/kernel-overview-1.png figures/kernel-overview-2.png \
-           figures/kernel-overview-3-denzil.png \
-           figures/source-repos.png figures/yp-download.png \
-           figures/wip.png
-        else
-TARFILES = dev-style.css dev-manual.html figures/buildhistory-web.png \
-           figures/dev-title.png figures/buildhistory.png \
-           figures/recipe-workflow.png figures/bitbake-build-flow.png \
-           figures/multiconfig_files.png figures/cute-files-npm-example.png
-	endif
-
-MANUALS = $(DOC)/$(DOC).html
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
-
-endif
-
-ifeq ($(DOC),mega-manual)
-XSLTOPTS = --stringparam html.stylesheet mega-style.css \
-           --stringparam  chapter.autolabel 1 \
-           --stringparam  section.autolabel 1 \
-           --stringparam  section.label.includes.component.label 1 \
-           --xinclude
-ALLPREQ = html tarball
-
-	ifeq ($(BRANCH),edison)
-TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \
-        figures/building-an-image.png  \
-	figures/using-a-pre-built-image.png \
-	figures/poky-title.png \
-	figures/adt-title.png figures/bsp-title.png \
-	figures/kernel-title.png figures/kernel-architecture-overview.png \
-	figures/app-dev-flow.png figures/bsp-dev-flow.png \
-        figures/dev-title.png figures/git-workflow.png \
-        figures/index-downloads.png figures/kernel-dev-flow.png \
-	figures/kernel-example-repos-edison.png \
-	figures/kernel-overview-1.png figures/kernel-overview-2.png \
-	figures/kernel-overview-3-edison.png \
-	figures/source-repos.png figures/yp-download.png \
-	figures/wip.png
-	else ifeq ($(BRANCH),denzil)
-TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \
-        figures/building-an-image.png  \
-	figures/using-a-pre-built-image.png \
-	figures/poky-title.png \
-	figures/adt-title.png figures/bsp-title.png \
-	figures/kernel-title.png figures/kernel-architecture-overview.png \
-	figures/app-dev-flow.png figures/bsp-dev-flow.png \
-        figures/dev-title.png figures/git-workflow.png \
-        figures/index-downloads.png figures/kernel-dev-flow.png \
-	figures/kernel-example-repos-denzil.png \
-	figures/kernel-overview-1.png figures/kernel-overview-2.png \
-	figures/kernel-overview-3-denzil.png \
-	figures/source-repos.png figures/yp-download.png \
-	figures/wip.png
-        else
-TARFILES = mega-manual.html mega-style.css \
-        figures/YP-flow-diagram.png \
-	figures/using-a-pre-built-image.png \
-	figures/poky-title.png figures/buildhistory.png \
-        figures/buildhistory-web.png \
-	figures/sdk-title.png figures/bsp-title.png \
-	figures/kernel-dev-title.png figures/kernel-architecture-overview.png \
-	figures/bsp-dev-flow.png \
-        figures/dev-title.png \
-	figures/git-workflow.png figures/index-downloads.png \
-        figures/kernel-dev-flow.png \
-	figures/kernel-overview-2-generic.png \
-	figures/source-repos.png figures/yp-download.png \
-        figures/profile-title.png figures/kernelshark-all.png \
-        figures/kernelshark-choose-events.png \
-        figures/kernelshark-i915-display.png \
-        figures/kernelshark-output-display.png \
-        figures/oprofileui-busybox.png figures/oprofileui-copy-to-user.png \
-        figures/oprofileui-downloading.png figures/oprofileui-processes.png \
-        figures/perf-probe-do_fork-profile.png \
-        figures/perf-report-cycles-u.png \
-        figures/perf-systemwide.png figures/perf-systemwide-libc.png \
-        figures/perf-wget-busybox-annotate-menu.png \
-        figures/perf-wget-busybox-annotate-udhcpc.png \
-        figures/perf-wget-busybox-debuginfo.png \
-        figures/perf-wget-busybox-dso-zoom.png \
-        figures/perf-wget-busybox-dso-zoom-menu.png \
-        figures/perf-wget-busybox-expanded-stripped.png \
-        figures/perf-wget-flat-stripped.png \
-        figures/perf-wget-g-copy-from-user-expanded-stripped.png \
-        figures/perf-wget-g-copy-to-user-expanded-debuginfo.png \
-        figures/perf-wget-g-copy-to-user-expanded-stripped.png \
-        figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png \
-        figures/pybootchartgui-linux-yocto.png \
-        figures/pychart-linux-yocto-rpm.png \
-        figures/pychart-linux-yocto-rpm-nostrip.png \
-        figures/sched-wakeup-profile.png figures/sysprof-callers.png \
-        figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png \
-        figures/cross-development-toolchains.png \
-	figures/user-configuration.png \
-        figures/source-input.png figures/package-feeds.png \
-        figures/layer-input.png figures/images.png figures/sdk.png \
-	figures/source-fetching.png figures/patching.png \
-        figures/configuration-compile-autoreconf.png \
-	figures/analysis-for-package-splitting.png \
-        figures/image-generation.png figures/key-dev-elements.png\
-	figures/sdk-generation.png figures/recipe-workflow.png \
-	figures/build-workspace-directory.png figures/mega-title.png \
-	figures/toaster-title.png figures/hosted-service.png figures/multiconfig_files.png \
-	figures/simple-configuration.png figures/poky-reference-distribution.png \
-	figures/compatible-layers.png figures/import-layer.png figures/new-project.png \
-	figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \
-	figures/sdk-devtool-add-flow.png figures/sdk-installed-extensible-sdk-directory.png \
-	figures/sdk-devtool-modify-flow.png \
-	figures/sdk-devtool-upgrade-flow.png figures/bitbake-build-flow.png figures/bypqs-title.png \
-	figures/overview-manual-title.png figures/sdk-autotools-flow.png figures/sdk-makefile-flow.png \
-	figures/bb_multiconfig_files.png figures/bitbake-title.png figures/cute-files-npm-example.png
-	endif
-
-MANUALS = $(DOC)/$(DOC).html
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
-
-endif
-
-ifeq ($(DOC),ref-manual)
-XSLTOPTS = --xinclude
-ALLPREQ = html tarball
-TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
-	figures/build-workspace-directory.png
-MANUALS = $(DOC)/$(DOC).html
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
-endif
-
-ifeq ($(DOC),sdk-manual)
-XSLTOPTS = --xinclude
-ALLPREQ = html tarball
-TARFILES = sdk-manual.html sdk-style.css figures/sdk-title.png \
-           figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \
-	   figures/sdk-installed-extensible-sdk-directory.png figures/sdk-devtool-add-flow.png \
-	   figures/sdk-devtool-modify-flow.png \
-	   figures/sdk-devtool-upgrade-flow.png figures/sdk-autotools-flow.png figures/sdk-makefile-flow.png
-MANUALS = $(DOC)/$(DOC).html
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
-endif
-
-ifeq ($(DOC),profile-manual)
-XSLTOPTS = --xinclude
-ALLPREQ = html tarball
-TARFILES = profile-manual.html profile-manual-style.css \
-           figures/profile-title.png figures/kernelshark-all.png \
-           figures/kernelshark-choose-events.png \
-           figures/kernelshark-i915-display.png \
-           figures/kernelshark-output-display.png \
-           figures/oprofileui-busybox.png figures/oprofileui-copy-to-user.png \
-           figures/oprofileui-downloading.png figures/oprofileui-processes.png \
-           figures/perf-probe-do_fork-profile.png \
-           figures/perf-report-cycles-u.png \
-           figures/perf-systemwide.png figures/perf-systemwide-libc.png \
-           figures/perf-wget-busybox-annotate-menu.png \
-           figures/perf-wget-busybox-annotate-udhcpc.png \
-           figures/perf-wget-busybox-debuginfo.png \
-           figures/perf-wget-busybox-dso-zoom.png \
-           figures/perf-wget-busybox-dso-zoom-menu.png \
-           figures/perf-wget-busybox-expanded-stripped.png \
-           figures/perf-wget-flat-stripped.png \
-           figures/perf-wget-g-copy-from-user-expanded-stripped.png \
-           figures/perf-wget-g-copy-to-user-expanded-debuginfo.png \
-           figures/perf-wget-g-copy-to-user-expanded-stripped.png \
-           figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png \
-           figures/pybootchartgui-linux-yocto.png \
-           figures/pychart-linux-yocto-rpm.png \
-           figures/pychart-linux-yocto-rpm-nostrip.png \
-           figures/sched-wakeup-profile.png figures/sysprof-callers.png \
-           figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png
-MANUALS = $(DOC)/$(DOC).html
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
-endif
-
-ifeq ($(DOC),kernel-dev)
-XSLTOPTS = --xinclude
-ALLPREQ = html tarball
-TARFILES = kernel-dev.html kernel-dev-style.css \
-           figures/kernel-dev-title.png figures/kernel-overview-2-generic.png \
-           figures/kernel-architecture-overview.png figures/kernel-dev-flow.png
-MANUALS = $(DOC)/$(DOC).html
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
-endif
-
-ifeq ($(DOC),toaster-manual)
-XSLTOPTS = --xinclude
-ALLPREQ = html tarball
-TARFILES = toaster-manual.html toaster-manual-style.css \
-	   figures/toaster-title.png figures/simple-configuration.png \
-	   figures/hosted-service.png \
-	   figures/compatible-layers.png figures/import-layer.png figures/new-project.png
-MANUALS = $(DOC)/$(DOC).html
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
-endif
-
-
-##
-# These URI should be rewritten by your distribution's xml catalog to
-# match your locally installed XSL stylesheets.
-XSL_BASE_URI  = http://docbook.sourceforge.net/release/xsl/1.76.1
-XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl
-
-all: $(ALLPREQ)
-
-pdf:
-ifeq ($(DOC),brief-yoctoprojectqs)
-	@echo " "
-	@echo "ERROR: You cannot generate a PDF file for brief-yoctoprojectqs."
-	@echo " "
-
-else ifeq ($(DOC),mega-manual)
-	@echo " "
-	@echo "ERROR: You cannot generate a mega-manual PDF file."
-	@echo " "
-
-else
-
-	cd $(DOC); ../tools/poky-docbook-to-pdf $(DOC).xml ../template; cd ..
-endif
-
-html:
-ifeq ($(DOC),mega-manual)
-#       See http://www.sagehill.net/docbookxsl/HtmlOutput.html
-	@echo " "
-	@echo "******** Building "$(DOC)
-	@echo " "
-	cd $(DOC); xsltproc $(XSLTOPTS) -o $(DOC).html $(DOC)-customization.xsl $(DOC).xml; cd ..
-	@echo " "
-	@echo "******** Using mega-manual.sed to process external links"
-	@echo " "
-	cd $(DOC); sed -f ../tools/mega-manual.sed < mega-manual.html > mega-output.html; cd ..
-	@echo " "
-	@echo "******** Cleaning up transient file mega-output.html"
-	@echo " "
-	cd $(DOC); rm mega-manual.html; mv mega-output.html mega-manual.html; cd ..
-else
-#       See http://www.sagehill.net/docbookxsl/HtmlOutput.html
-	@echo " "
-	@echo "******** Building "$(DOC)
-	@echo " "
-	cd $(DOC); xsltproc $(XSLTOPTS) -o $(DOC).html $(DOC)-customization.xsl $(DOC).xml; cd ..
-endif
-
-
-tarball: html
-	@echo " "
-	@echo "******** Creating Tarball of document files"
-	@echo " "
-	cd $(DOC); tar -cvzf $(DOC).tgz $(TARFILES); cd ..
-
-validate:
-	cd $(DOC); xmllint --postvalid --xinclude --noout $(DOC).xml; cd ..
-
-
-publish:
-	@if test -f $(DOC)/$(DOC).html; \
-	  then \
-            echo " "; \
-            echo "******** Publishing "$(DOC)".html"; \
-            echo " "; \
-            scp -r $(MANUALS) $(STYLESHEET) www.yoctoproject.org:/var/www/www.yoctoproject.org-docs/$(VER)/$(DOC); \
-            cd $(DOC); scp -r $(FIGURES) www.yoctoproject.org:/var/www/www.yoctoproject.org-docs/$(VER)/$(DOC); \
-	else \
-          echo " "; \
-          echo $(DOC)".html missing.  Generate the file first then try again."; \
-          echo " "; \
-	fi
+publish: Makefile html singlehtml
+	rm -rf $(BUILDDIR)/$(DESTDIR)/
+	mkdir -p $(BUILDDIR)/$(DESTDIR)/
+	cp -r $(BUILDDIR)/html/* $(BUILDDIR)/$(DESTDIR)/
+	cp $(BUILDDIR)/singlehtml/index.html $(BUILDDIR)/$(DESTDIR)/singleindex.html
+	sed -i -e 's@index.html#@singleindex.html#@g' $(BUILDDIR)/$(DESTDIR)/singleindex.html
 
 clean:
-	rm -rf $(MANUALS); rm $(DOC)/$(DOC).tgz;
+	@rm -rf $(BUILDDIR)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

documentation/Pipfile

@@ -0,0 +1,14 @@
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[dev-packages]
+
+[packages]
+sphinx = "*"
+sphinx-rtd-theme = "*"
+pyyaml = "*"
+
+[requires]
+python_version = "3"

documentation/README

@@ -34,22 +34,17 @@ Manual Organization
 
 Folders exist for individual manuals as follows:
 
-* sdk-manual       - The Yocto Project Software Development Kit (SDK) Developer's Guide.
-* bsp-guide        - The Yocto Project Board Support Package (BSP) Developer's Guide
-* dev-manual       - The Yocto Project Development Tasks Manual
-* kernel-dev       - The Yocto Project Linux Kernel Development Tasks Manual
-* ref-manual       - The Yocto Project Reference Manual
-* yocto-project-qs - The Yocto Project Quick Start
-* mega-manual      - The Yocto Project Mega-Manual, which is an aggregated manual comprised
-                     of all YP manuals and guides
-* profile-manual   - The Yocto Project Profile and Tracing Manual
-* toaster-manual   - The Toaster Manual
+* sdk-manual           - The Yocto Project Software Development Kit (SDK) Developer's Guide.
+* bsp-guide            - The Yocto Project Board Support Package (BSP) Developer's Guide
+* dev-manual           - The Yocto Project Development Tasks Manual
+* kernel-dev           - The Yocto Project Linux Kernel Development Tasks Manual
+* ref-manual           - The Yocto Project Reference Manual
+* brief-yoctoprojectqs - The Yocto Project Quick Start
+* profile-manual       - The Yocto Project Profile and Tracing Manual
+* toaster-manual       - The Toaster Manual
+* test-manual          - The Test Environment Manual
 
-Each folder is self-contained regarding content and figures.  Note that there
-is a sed file needed to process the links of the mega-manual.  The sed file
-is located in the tools directory.  Also note that the figures folder in the
-mega-manual directory contains duplicates of all the figures in the YP folders
-directories for all YP manuals and guides.
+Each folder is self-contained regarding content and figures.
 
 If you want to find HTML versions of the Yocto Project manuals on the web,
 go to http://www.yoctoproject.org and click on the "Documentation" tab.  From
@@ -60,23 +55,8 @@ currently being developed.
 In general, the Yocto Project site (http://www.yoctoproject.org) is a great
 reference for both information and downloads.
 
-Makefile
-========
-
-The Makefile processes manual directories to create HTML, PDF,
-tarballs, etc.  Details on how the Makefile work are documented
-inside the Makefile.  See that file for more information.
-
-To build a manual, you run the make command and pass it the name
-of the folder containing the manual's contents.
-For example, the following command run from the documentation directory
-creates an HTML version of the SDK manual.
-The DOC variable specifies the manual you are making:
-
-     $ make DOC=sdk-manual
-
-poky.ent
-========
+poky.yaml
+=========
 
 This file defines variables used for documentation production.  The variables
 are used to define release pathnames, URLs for the published manuals, etc.
@@ -85,9 +65,263 @@ template
 ========
 Contains various templates, fonts, and some old PNG files.
 
-tools
-=====
-Contains a tool to convert the DocBook files to PDF format.  This folder also
-contains the mega-manual.sed file, which is used by Makefile to process
-cross-references from within the manual that normally go to an external
-manual.
+Sphinx
+======
+
+The Yocto Project documentation was migrated from the original DocBook
+format to Sphinx based documentation for the Yocto Project 3.2
+release. This section will provide additional information related to
+the Sphinx migration, and guidelines for developers willing to
+contribute to the Yocto Project documentation.
+
+   Sphinx is a tool that makes it easy to create intelligent and
+   beautiful documentation, written by Georg Brandl and licensed under
+   the BSD license. It was originally created for the Python
+   documentation.
+
+Extensive documentation is available on the Sphinx website:
+https://www.sphinx-doc.org/en/master/. Sphinx is designed to be
+extensible thanks to the ability to write our own custom extensions,
+as Python modules, which will be executed during the generation of the
+documentation.
+
+Yocto Project documentation website
+===================================
+
+A new website has been created to host the Yocto Project
+documentation, it can be found at: https://docs.yoctoproject.org/.
+
+The entire Yocto Project documentation, as well as the BitBake manual
+is published on this website, including all previously released
+versions. A version switcher was added, as a drop-down menu on the top
+of the page to switch back and forth between the various versions of
+the current active Yocto Project releases.
+
+Transition pages have been added (as rst file) to show links to old
+versions of the Yocto Project documentation with links to each manual
+generated with DocBook.
+
+How to build the Yocto Project documentation
+============================================
+
+Sphinx is written in Python. While it might work with Python2, for
+obvious reasons, we will only support building the Yocto Project
+documentation with Python3.
+
+Sphinx might be available in your Linux distro packages repositories,
+however it is not recommend using distro packages, as they might be
+old versions, especially if you are using an LTS version of your
+distro. The recommended method to install Sphinx and all required
+dependencies is to use the Python Package Index (pip).
+
+To install all required packages run:
+
+ $ pip3 install sphinx sphinx_rtd_theme pyyaml
+
+To build the documentation locally, run:
+
+ $ cd documentation
+ $ make html
+
+The resulting HTML index page will be _build/html/index.html, and you
+can browse your own copy of the locally generated documentation with
+your browser.
+
+Alternatively, you can use Pipenv to automatically install all required
+dependencies in a virtual environment:
+
+ $ cd documentation
+ $ pipenv install
+ $ pipenv run make html
+
+Sphinx theme and CSS customization
+==================================
+
+The Yocto Project documentation is currently based on the "Read the
+Docs" Sphinx theme, with a few changes to make sure the look and feel
+of the project documentation is preserved.
+
+Most of the theme changes can be done using the file
+'sphinx-static/theme_overrides.css'. Most CSS changes in this file
+were inherited from the DocBook CSS stylesheets.
+
+Sphinx design guidelines and principles
+=======================================
+
+The initial Docbook to Sphinx migration was done with an automated
+tool called Pandoc (https://pandoc.org/). The tool produced some clean
+output markdown text files. After the initial automated conversion
+additional changes were done to fix up headings, images and links. In
+addition Sphinx has built in mechanisms (directives) which were used
+to replace similar functions implemented in Docbook such as glossary,
+variables substitutions, notes and references.
+
+Headings
+========
+
+The layout of the Yocto Project manuals is organized as follows
+
+    Book
+      Chapter
+        Section
+          Section
+            Section
+
+The following headings styles are defined in Sphinx:
+
+    Book              => overline ===
+      Chapter         => overline ***
+        Section       => ====
+          Section     => ----
+            Section   => ^^^^
+              Section => """" or ~~~~
+
+With this proposal, we preserve the same TOCs between Sphinx and Docbook.
+
+Built-in glossary
+=================
+
+Sphinx has a glossary directive. From
+https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary:
+
+    This directive must contain a reST definition list with terms and
+    definitions. The definitions will then be referencable with the
+    [https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-term
+    'term' role].
+
+So anywhere in any of the Yocto Project manuals, :term:`VAR` can be
+used to refer to an item from the glossary, and a link is created
+automatically. A general index of terms is also generated by Sphinx
+automatically.
+
+Global substitutions
+====================
+
+The Yocto Project documentation makes heavy use of global
+variables. In Docbook these variables are stored in the file
+poky.ent. This Docbook feature is not handled automatically with
+Pandoc. Sphinx has builtin support for substitutions
+(https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions),
+however there are important shortcomings. For example they cannot be
+used/nested inside code-block sections.
+
+A Sphinx extension was implemented to support variable substitutions
+to mimic the DocBook based documentation behavior. Variabes
+substitutions are done while reading/parsing the .rst files. The
+pattern for variables substitutions is the same as with DocBook,
+e.g. `&VAR;`.
+
+The implementation of the extension can be found here in the file
+documentation/sphinx/yocto-vars.py, this extension is enabled by
+default when building the Yocto Project documentation.  All variables
+are set in a file call poky.yaml, which was initially generated from
+poky.ent. The file was converted into YAML so that it is easier to
+process by the custom Sphinx extension (which is a Python module).
+
+For example, the following .rst content will produce the 'expected'
+content:
+
+  .. code-block::
+      $ mkdir ~/poky-&DISTRO;
+      or
+      $ git clone &YOCTO_GIT_URL;/git/poky -b &DISTRO_NAME_NO_CAP;
+
+Variables can be nested, like it was the case for DocBook:
+
+  YOCTO_HOME_URL : "http://www.yoctoproject.org"
+  YOCTO_DOCS_URL : "&YOCTO_HOME_URL;/docs"
+
+Note directive
+==============
+
+Sphinx has a builtin 'note' directive that produces clean Note section
+in the output file. There are various types of directives such as
+"attention", "caution", "danger", "error", "hint", "important", "tip",
+"warning", "admonition" that are supported, and additional directive
+can be added as Sphinx extension if needed.
+
+Figures
+=======
+
+The Yocto Project documentation has many figures/images. Sphinx has a
+'figure' directive which is straight forward to use. To include a
+figure in the body of the documentation:
+
+  .. image:: figures/YP-flow-diagram.png
+
+Links and References
+====================
+
+The following types of links can be used: links to other locations in
+the same document, to locations in other documents and to external
+websites.
+
+More information can be found here:
+https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html.
+
+References
+==========
+
+The following extension is enabed by default:
+sphinx.ext.autosectionlabel
+(https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html).
+
+This extension allows you to refer sections by their titles. Note that
+autosectionlabel_prefix_document is enabled by default, so that we can
+insert references from any document.
+
+For example, to insert an HTML link to a section from
+documentaion/manual/intro.rst, use:
+
+  Please check this :ref:`manual/intro:Cross-References to Locations in the Same Document`
+
+Alternatively a custom text can be used instead of using the section
+text:
+
+  Please check this :ref:`section <manual/intro:Cross-References to Locations in the Same Document>`
+
+TIP: The following command can be used to dump all the references that
+     are defined in the project documentation:
+
+       python -msphinx.ext.intersphinx <path to build folder>/html/objects.inv
+
+This dump contains all links and for each link it shows the default
+"Link Text" that Sphinx would use. If the default link text is not
+appropriate, a custom link text can be used in the ':ref:' directive.
+
+Extlinks
+========
+
+The sphinx.ext.extlinks extension is enabled by default
+(https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#use-the-external-links-extension),
+and it is configured with:
+
+  'yocto_home': ('https://yoctoproject.org%s', None),
+  'yocto_wiki': ('https://wiki.yoctoproject.org%s', None),
+  'yocto_dl': ('https://downloads.yoctoproject.org%s', None),
+  'yocto_lists': ('https://lists.yoctoproject.org%s', None),
+  'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None),
+  'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None),
+  'yocto_docs': ('https://docs.yoctoproject.org%s', None),
+  'yocto_git': ('https://git.yoctoproject.org%s', None),
+  'oe_home': ('https://www.openembedded.org%s', None),
+  'oe_lists': ('https://lists.openembedded.org%s', None),
+
+It creates convenient shortcuts which can be used throughout the
+documentation rst files, as:
+
+  Please check this :yocto_wiki:`wiki page </Weekly_Status>`
+
+Intersphinx links
+=================
+
+The sphinx.ext.intersphinx extension is enabled by default
+(https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html),
+so that we can cross reference content from other Sphinx based
+documentation projects, such as the BitBake manual.
+
+References to the bitbake manual can be done like this:
+
+  See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option
+or
+  :term:`bitbake:BB_NUMBER_PARSE_THREADS`

documentation/_templates/breadcrumbs.html

@@ -0,0 +1,14 @@
+{% extends "!breadcrumbs.html" %}
+
+{% block breadcrumbs %}
+    <li>
+      <span class="doctype_switcher_placeholder">{{ doctype or 'single' }}</span>
+      <span class="version_switcher_placeholder">{{ release }}</span>
+    </li>
+    <li> &raquo;</li>
+    {% for doc in parents %}
+      <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
+    {% endfor %}
+    <li>{{ title }}</li>
+{% endblock %}
+

documentation/_templates/footer.html

@@ -0,0 +1,12 @@
+<footer>
+  <hr/>
+  <div role="contentinfo">
+    <p> A Linux Foundation Collaborative Project.
+        <br> All Rights Reserved. Linux Foundation&reg; and Yocto Project&reg; are registered trademarks of the Linux Foundation.
+        <br>Linux&reg; is a registered trademark of Linus Torvalds.
+        <br>&copy; Copyright {{ copyright }}
+        <br>Last updated on {{ last_updated }}
+    </p>
+  </div>
+</footer>
+

documentation/_templates/layout.html

@@ -0,0 +1,7 @@
+{% extends "!layout.html" %}
+
+{% block extrabody %}
+<div id="outdated-warning" style="text-align: center; background-color: #FFBABA; color: #6A0E0E;">
+</div>
+{% endblock %}
+

documentation/adt-manual/adt-command.xml

@@ -1,265 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='using-the-command-line'>
-<title>Using the Command Line</title>
-
-    <para>
-        Recall that earlier the manual discussed how to use an existing toolchain
-        tarball that had been installed into the default installation
-        directory, <filename>/opt/poky/&DISTRO;</filename>, which is outside of the
-        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-        (see the section "<link linkend='using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball)</link>".
-        And, that sourcing your architecture-specific environment setup script
-        initializes a suitable cross-toolchain development environment.
-    </para>
-
-    <para>
-        During this setup, locations for the compiler, QEMU scripts, QEMU binary,
-        a special version of <filename>pkgconfig</filename> and other useful
-        utilities are added to the <filename>PATH</filename> variable.
-        Also, variables to assist
-        <filename>pkgconfig</filename> and <filename>autotools</filename>
-        are also defined so that, for example, <filename>configure.sh</filename>
-        can find pre-generated test results for tests that need target hardware
-        on which to run.
-        You can see the
-        "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>"
-        section for the list of cross-toolchain environment variables
-        established by the script.
-    </para>
-
-    <para>
-        Collectively, these conditions allow you to easily use the toolchain
-        outside of the OpenEmbedded build environment on both Autotools-based
-        projects and Makefile-based projects.
-        This chapter provides information for both these types of projects.
-    </para>
-
-
-<section id='autotools-based-projects'>
-<title>Autotools-Based Projects</title>
-
-    <para>
-        Once you have a suitable cross-toolchain installed, it is very easy to
-        develop a project outside of the OpenEmbedded build system.
-        This section presents a simple "Helloworld" example that shows how
-        to set up, compile, and run the project.
-    </para>
-
-    <section id='creating-and-running-a-project-based-on-gnu-autotools'>
-        <title>Creating and Running a Project Based on GNU Autotools</title>
-
-        <para>
-            Follow these steps to create a simple Autotools-based project:
-            <orderedlist>
-                <listitem><para><emphasis>Create your directory:</emphasis>
-                    Create a clean directory for your project and then make
-                    that directory your working location:
-                    <literallayout class='monospaced'>
-     $ mkdir $HOME/helloworld
-     $ cd $HOME/helloworld
-                    </literallayout></para></listitem>
-                <listitem><para><emphasis>Populate the directory:</emphasis>
-                    Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
-                    and <filename>configure.in</filename> files as follows:
-                    <itemizedlist>
-                        <listitem><para>For <filename>hello.c</filename>, include
-                            these lines:
-                            <literallayout class='monospaced'>
-     #include &lt;stdio.h&gt;
-
-     main()
-        {
-           printf("Hello World!\n");
-        }
-                            </literallayout></para></listitem>
-                        <listitem><para>For <filename>Makefile.am</filename>,
-                            include these lines:
-                            <literallayout class='monospaced'>
-     bin_PROGRAMS = hello
-     hello_SOURCES = hello.c
-                            </literallayout></para></listitem>
-                        <listitem><para>For <filename>configure.in</filename>,
-                            include these lines:
-                            <literallayout class='monospaced'>
-     AC_INIT(hello.c)
-     AM_INIT_AUTOMAKE(hello,0.1)
-     AC_PROG_CC
-     AC_PROG_INSTALL
-     AC_OUTPUT(Makefile)
-                            </literallayout></para></listitem>
-                    </itemizedlist></para></listitem>
-                <listitem><para><emphasis>Source the cross-toolchain
-                    environment setup file:</emphasis>
-                    Installation of the cross-toolchain creates a cross-toolchain
-                    environment setup script in the directory that the ADT
-                    was installed.
-                    Before you can use the tools to develop your project, you must
-                    source this setup script.
-                    The script begins with the string "environment-setup" and contains
-                    the machine architecture, which is followed by the string
-                    "poky-linux".
-                    Here is an example that sources a script from the
-                    default ADT installation directory that uses the
-                    32-bit Intel x86 Architecture and the
-                    &DISTRO_NAME; Yocto Project release:
-                    <literallayout class='monospaced'>
-     $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
-                    </literallayout></para></listitem>
-                <listitem><para><emphasis>Generate the local aclocal.m4
-                    files and create the configure script:</emphasis>
-                    The following GNU Autotools generate the local
-                    <filename>aclocal.m4</filename> files and create the
-                    configure script:
-                    <literallayout class='monospaced'>
-     $ aclocal
-     $ autoconf
-                    </literallayout></para></listitem>
-                <listitem><para><emphasis>Generate files needed by GNU
-                    coding standards:</emphasis>
-                    GNU coding standards require certain files in order for the
-                    project to be compliant.
-                    This command creates those files:
-                    <literallayout class='monospaced'>
-     $ touch NEWS README AUTHORS ChangeLog
-                    </literallayout></para></listitem>
-                <listitem><para><emphasis>Generate the configure
-                    file:</emphasis>
-                    This command generates the <filename>configure</filename>:
-                    <literallayout class='monospaced'>
-     $ automake -a
-                    </literallayout></para></listitem>
-                <listitem><para><emphasis>Cross-compile the project:</emphasis>
-                    This command compiles the project using the cross-compiler.
-                    The
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
-                    environment variable provides the minimal arguments for
-                    GNU configure:
-                    <literallayout class='monospaced'>
-     $ ./configure ${CONFIGURE_FLAGS}
-                    </literallayout></para></listitem>
-                <listitem><para><emphasis>Make and install the project:</emphasis>
-                    These two commands generate and install the project into the
-                    destination directory:
-                    <literallayout class='monospaced'>
-     $ make
-     $ make install DESTDIR=./tmp
-                    </literallayout></para></listitem>
-                <listitem><para><emphasis>Verify the installation:</emphasis>
-                    This command is a simple way to verify the installation
-                    of your project.
-                    Running the command prints the architecture on which
-                    the binary file can run.
-                    This architecture should be the same architecture that
-                    the installed cross-toolchain supports.
-                    <literallayout class='monospaced'>
-     $ file ./tmp/usr/local/bin/hello
-                    </literallayout></para></listitem>
-                <listitem><para><emphasis>Execute your project:</emphasis>
-                    To execute the project in the shell, simply enter the name.
-                    You could also copy the binary to the actual target hardware
-                    and run the project there as well:
-                    <literallayout class='monospaced'>
-     $ ./hello
-                    </literallayout>
-                    As expected, the project displays the "Hello World!" message.
-                    </para></listitem>
-            </orderedlist>
-        </para>
-    </section>
-
-    <section id='passing-host-options'>
-        <title>Passing Host Options</title>
-
-        <para>
-            For an Autotools-based project, you can use the cross-toolchain by just
-            passing the appropriate host option to <filename>configure.sh</filename>.
-            The host option you use is derived from the name of the environment setup
-            script found in the directory in which you installed the cross-toolchain.
-            For example, the host option for an ARM-based target that uses the GNU EABI
-            is <filename>armv5te-poky-linux-gnueabi</filename>.
-            You will notice that the name of the script is
-            <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
-            Thus, the following command works to update your project and
-            rebuild it using the appropriate cross-toolchain tools:
-            <literallayout class='monospaced'>
-     $ ./configure --host=armv5te-poky-linux-gnueabi \
-        --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
-            </literallayout>
-            <note>
-                If the <filename>configure</filename> script results in problems recognizing the
-                <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option,
-                regenerate the script to enable the support by doing the following and then
-                run the script again:
-                <literallayout class='monospaced'>
-     $ libtoolize --automake
-     $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
-        [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
-     $ autoconf
-     $ autoheader
-     $ automake -a
-                </literallayout>
-            </note>
-        </para>
-    </section>
-</section>
-
-<section id='makefile-based-projects'>
-<title>Makefile-Based Projects</title>
-
-    <para>
-        For Makefile-based projects, the cross-toolchain environment variables
-        established by running the cross-toolchain environment setup script
-        are subject to general <filename>make</filename> rules.
-    </para>
-
-    <para>
-        To illustrate this, consider the following four cross-toolchain
-        environment variables:
-        <literallayout class='monospaced'>
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
-        </literallayout>
-        Now, consider the following three cases:
-        <itemizedlist>
-            <listitem><para><emphasis>Case 1 - No Variables Set in the <filename>Makefile</filename>:</emphasis>
-                Because these variables are not specifically set in the
-                <filename>Makefile</filename>, the variables retain their
-                values based on the environment.
-                </para></listitem>
-            <listitem><para><emphasis>Case 2 - Variables Set in the <filename>Makefile</filename>:</emphasis>
-                Specifically setting variables in the
-                <filename>Makefile</filename> during the build results in the
-                environment settings of the variables being overwritten.
-                </para></listitem>
-            <listitem><para><emphasis>Case 3 - Variables Set when the <filename>Makefile</filename> is Executed from the Command Line:</emphasis>
-                Executing the <filename>Makefile</filename> from the command
-                line results in the variables being overwritten with
-                command-line content regardless of what is being set in the
-                <filename>Makefile</filename>.
-                In this case, environment variables are not considered unless
-                you use the "-e" flag during the build:
-                <literallayout class='monospaced'>
-     $ make -e <replaceable>file</replaceable>
-                </literallayout>
-                If you use this flag, then the environment values of the
-                variables override any variables specifically set in the
-                <filename>Makefile</filename>.
-                </para></listitem>
-        </itemizedlist>
-        <note>
-            For the list of variables set up by the cross-toolchain environment
-            setup script, see the
-            "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>"
-            section.
-        </note>
-    </para>
-</section>
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/adt-manual/adt-intro.xml

@@ -1,180 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='adt-intro'>
-    <title>The Application Development Toolkit (ADT)</title>
-
-    <para>
-        Part of the Yocto Project development solution is an Application Development
-        Toolkit (ADT).
-        The ADT provides you with a custom-built, cross-development
-        platform suited for developing a user-targeted product application.
-    </para>
-
-    <para>
-        Fundamentally, the ADT consists of the following:
-        <itemizedlist>
-            <listitem><para>An architecture-specific cross-toolchain and matching
-                sysroot both built by the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.
-                The toolchain and sysroot are based on a
-                <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
-                configuration and extensions,
-                which allows you to cross-develop on the host machine for the target hardware.
-                </para></listitem>
-            <listitem><para>The Eclipse IDE Yocto Plug-in.</para></listitem>
-            <listitem><para>The Quick EMUlator (QEMU), which lets you simulate target hardware.
-                </para></listitem>
-            <listitem><para>Various user-space tools that greatly enhance your application
-                development experience.</para></listitem>
-        </itemizedlist>
-    </para>
-
-    <section id='the-cross-development-toolchain'>
-        <title>The Cross-Development Toolchain</title>
-
-        <para>
-            The
-            <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink>
-            consists of a cross-compiler, cross-linker, and cross-debugger
-            that are used to develop user-space applications for targeted
-            hardware.
-            This toolchain is created either by running the ADT Installer
-            script, a toolchain installer script, or through a
-            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-            that is based on your Metadata configuration or extension for
-            your targeted device.
-            The cross-toolchain works with a matching target sysroot.
-        </para>
-    </section>
-
-    <section id='sysroot'>
-        <title>Sysroot</title>
-
-        <para>
-            The matching target sysroot contains needed headers and libraries for generating
-            binaries that run on the target architecture.
-            The sysroot is based on the target root filesystem image that is built by
-            the OpenEmbedded build system and uses the same Metadata configuration
-            used to build the cross-toolchain.
-        </para>
-    </section>
-
-    <section id='eclipse-overview'>
-        <title>Eclipse Yocto Plug-in</title>
-
-        <para>
-            The Eclipse IDE is a popular development environment and it fully supports
-            development using the Yocto Project.
-            When you install and configure the Eclipse Yocto Project Plug-in into
-            the Eclipse IDE, you maximize your Yocto Project experience.
-            Installing and configuring the Plug-in results in an environment that
-            has extensions specifically designed to let you more easily develop software.
-            These extensions allow for cross-compilation, deployment, and execution of
-            your output into a QEMU emulation session.
-            You can also perform cross-debugging and profiling.
-            The environment also supports a suite of tools that allows you to perform
-            remote profiling, tracing, collection of power data, collection of
-            latency data, and collection of performance data.
-        </para>
-
-        <para>
-            For information about the application development workflow that uses the Eclipse
-            IDE and for a detailed example of how to install and configure the Eclipse
-            Yocto Project Plug-in, see the
-            "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working Within Eclipse</ulink>" section
-            of the Yocto Project Development Manual.
-        </para>
-    </section>
-
-    <section id='the-qemu-emulator'>
-        <title>The QEMU Emulator</title>
-
-        <para>
-            The QEMU emulator allows you to simulate your hardware while running your
-            application or image.
-            QEMU is made available a number of ways:
-            <itemizedlist>
-                <listitem><para>
-                    If you use the ADT Installer script to install ADT, you can
-                    specify whether or not to install QEMU.
-                    </para></listitem>
-                <listitem><para>
-                    If you have cloned the <filename>poky</filename> Git
-                    repository to create a
-                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
-                    and you have sourced the environment setup script, QEMU is
-                    installed and automatically available.
-                    </para></listitem>
-                <listitem><para>
-                    If you have downloaded a Yocto Project release and unpacked
-                    it to create a
-                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
-                    and you have sourced the environment setup script, QEMU is
-                    installed and automatically available.
-                    </para></listitem>
-                <listitem><para>
-                    If you have installed the cross-toolchain tarball and you
-                    have sourced the toolchain's setup environment script, QEMU
-                    is also installed and automatically available.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-
-    <section id='user-space-tools'>
-        <title>User-Space Tools</title>
-
-        <para>
-            User-space tools are included as part of the Yocto Project.
-            You will find these tools helpful during development.
-            The tools include LatencyTOP, PowerTOP, OProfile, Perf, SystemTap, and Lttng-ust.
-            These tools are common development tools for the Linux platform.
-            <itemizedlist>
-                <listitem><para><emphasis>LatencyTOP:</emphasis> LatencyTOP focuses on latency
-                    that causes skips in audio,
-                    stutters in your desktop experience, or situations that overload your server
-                    even when you have plenty of CPU power left.
-                    </para></listitem>
-                <listitem><para><emphasis>PowerTOP:</emphasis> Helps you determine what
-                    software is using the most power.
-                    You can find out more about PowerTOP at
-                    <ulink url='https://01.org/powertop/'></ulink>.</para></listitem>
-                <listitem><para><emphasis>OProfile:</emphasis> A system-wide profiler for Linux
-                    systems that is capable of profiling all running code at low overhead.
-                    You can find out more about OProfile at
-                    <ulink url='http://oprofile.sourceforge.net/about/'></ulink>.
-                    For examples on how to setup and use this tool, see the
-                    "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>OProfile</ulink>"
-                    section in the Yocto Project Profiling and Tracing Manual.
-                    </para></listitem>
-                <listitem><para><emphasis>Perf:</emphasis> Performance counters for Linux used
-                    to keep track of certain types of hardware and software events.
-                    For more information on these types of counters see
-                    <ulink url='https://perf.wiki.kernel.org/'></ulink>.
-                    For examples on how to setup and use this tool, see the
-                    "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>"
-                    section in the Yocto Project Profiling and Tracing Manual.
-                    </para></listitem>
-                <listitem><para><emphasis>SystemTap:</emphasis> A free software infrastructure
-                    that simplifies information gathering about a running Linux system.
-                    This information helps you diagnose performance or functional problems.
-                    SystemTap is not available as a user-space tool through the Eclipse IDE Yocto Plug-in.
-                    See <ulink url='http://sourceware.org/systemtap'></ulink> for more information
-                    on SystemTap.
-                    For examples on how to setup and use this tool, see the
-                    "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-systemtap'>SystemTap</ulink>"
-                    section in the Yocto Project Profiling and Tracing Manual.</para></listitem>
-                <listitem><para><emphasis>Lttng-ust:</emphasis> A User-space Tracer designed to
-                    provide detailed information on user-space activity.
-                    See <ulink url='http://lttng.org/ust'></ulink> for more information on Lttng-ust.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/adt-manual/adt-manual-customization.xsl

@@ -1,27 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
-
-  <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-<!--
-
-  <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-  <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
-
--->
-
-  <xsl:include href="../template/permalinks.xsl"/>
-  <xsl:include href="../template/section.title.xsl"/>
-  <xsl:include href="../template/component.title.xsl"/>
-  <xsl:include href="../template/division.title.xsl"/>
-  <xsl:include href="../template/formal.object.heading.xsl"/>
-
-  <xsl:param name="html.stylesheet" select="'adt-style.css'" />
-  <xsl:param name="chapter.autolabel" select="1" />
-  <xsl:param name="appendix.autolabel" select="A" />
-  <xsl:param name="section.autolabel" select="1" />
-  <xsl:param name="section.label.includes.component.label" select="1" />
-  <xsl:param name="generate.id.attributes" select="1" />
-
-</xsl:stylesheet>

documentation/adt-manual/adt-manual-eclipse-customization.xsl

@@ -1,35 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet
-	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-	xmlns="http://www.w3.org/1999/xhtml"
-	xmlns:fo="http://www.w3.org/1999/XSL/Format"
-	version="1.0">
-
-  <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" />
-
-<!--
-
-  <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" />
-
-  <xsl:import
-	  href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" />
-
--->
-
-  <xsl:param name="chunker.output.indent" select="'yes'"/>
-  <xsl:param name="chunk.quietly" select="1"/>
-  <xsl:param name="chunk.first.sections" select="1"/>
-  <xsl:param name="chunk.section.depth" select="10"/>
-  <xsl:param name="use.id.as.filename" select="1"/>
-  <xsl:param name="ulink.target" select="'_self'" />
-  <xsl:param name="base.dir" select="'html/adt-manual/'"/>
-  <xsl:param name="html.stylesheet" select="'../book.css'"/>
-  <xsl:param name="eclipse.manifest" select="0"/>
-  <xsl:param name="create.plugin.xml" select="0"/>
-  <xsl:param name="suppress.navigation" select="1"/>
-  <xsl:param name="generate.index" select="0"/>
-  <xsl:param name="chapter.autolabel" select="1" />
-  <xsl:param name="appendix.autolabel" select="1" />
-  <xsl:param name="section.autolabel" select="1" />
-  <xsl:param name="section.label.includes.component.label" select="1" />
-</xsl:stylesheet>

documentation/adt-manual/adt-manual-intro.xml

@@ -1,33 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='adt-manual-intro'>
-<title>Introduction</title>
-
-    <para>
-        Welcome to the Yocto Project Application Developer's Guide.
-        This manual provides information that lets you begin developing applications
-        using the Yocto Project.
-    </para>
-
-    <para>
-        The Yocto Project provides an application development environment based on
-        an Application Development Toolkit (ADT) and the availability of stand-alone
-        cross-development toolchains and other tools.
-        This manual describes the ADT and how you can configure and install it,
-        how to access and use the cross-development toolchains, how to
-        customize the development packages installation,
-        how to use command-line development for both Autotools-based and
-        Makefile-based projects, and an introduction to the
-        <trademark class='trade'>Eclipse</trademark> IDE Yocto Plug-in.
-        <note>
-            The ADT is distribution-neutral and does not require the Yocto
-            Project reference distribution, which is called Poky.
-            This manual, however, uses examples that use the Poky distribution.
-        </note>
-    </para>
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/adt-manual/adt-manual.xml

@@ -1,140 +0,0 @@
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<book id='adt-manual' lang='en'
-      xmlns:xi="http://www.w3.org/2003/XInclude"
-      xmlns="http://docbook.org/ns/docbook"
-      >
-    <bookinfo>
-
-        <mediaobject>
-            <imageobject>
-                <imagedata fileref='figures/adt-title.png'
-                    format='SVG'
-                    align='left' scalefit='1' width='100%'/>
-            </imageobject>
-        </mediaobject>
-
-        <title>
-            Yocto Project Application Developer's Guide
-        </title>
-
-        <authorgroup>
-            <author>
-                <firstname>Jessica</firstname> <surname>Zhang</surname>
-                <affiliation>
-                    <orgname>Intel Corporation</orgname>
-                </affiliation>
-                <email>jessica.zhang@intel.com</email>
-            </author>
-        </authorgroup>
-
-        <revhistory>
-            <revision>
-                <revnumber>1.0</revnumber>
-                <date>6 April 2011</date>
-                <revremark>Released with the Yocto Project 1.0 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.0.1</revnumber>
-                <date>23 May 2011</date>
-                <revremark>Released with the Yocto Project 1.0.1 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.1</revnumber>
-                <date>6 October 2011</date>
-                <revremark>Released with the Yocto Project 1.1 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.2</revnumber>
-                <date>April 2012</date>
-                <revremark>Released with the Yocto Project 1.2 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.3</revnumber>
-                <date>October 2012</date>
-                <revremark>Released with the Yocto Project 1.3 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.4</revnumber>
-                <date>April 2013</date>
-                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.5</revnumber>
-                <date>October 2013</date>
-                <revremark>Released with the Yocto Project 1.5 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.5.1</revnumber>
-                <date>January 2014</date>
-                <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.6</revnumber>
-                <date>April 2014</date>
-                <revremark>Released with the Yocto Project 1.6 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.7</revnumber>
-                <date>October 2014</date>
-                <revremark>Released with the Yocto Project 1.7 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.8</revnumber>
-                <date>April 2015</date>
-                <revremark>Released with the Yocto Project 1.8 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.0</revnumber>
-                <date>October 2015</date>
-                <revremark>Released with the Yocto Project 2.0 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.1</revnumber>
-                <date>Sometime in 2016</date>
-                <revremark>Released with the future Yocto Project 2.1 Release.</revremark>
-            </revision>
-       </revhistory>
-
-    <copyright>
-      <year>&COPYRIGHT_YEAR;</year>
-      <holder>Linux Foundation</holder>
-    </copyright>
-
-    <legalnotice>
-      <para>
-        Permission is granted to copy, distribute and/or modify this document under
-        the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
-      </para>
-      <note>
-          For the latest version of this manual associated with this
-          Yocto Project release, see the
-          <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>
-          from the Yocto Project website.
-      </note>
-
-    </legalnotice>
-
-    </bookinfo>
-
-    <xi:include href="adt-manual-intro.xml"/>
-
-    <xi:include href="adt-intro.xml"/>
-
-    <xi:include href="adt-prepare.xml"/>
-
-    <xi:include href="adt-package.xml"/>
-
-    <xi:include href="adt-command.xml"/>
-
-<!--    <index id='index'>
-      <title>Index</title>
-    </index>
--->
-
-</book>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/adt-manual/adt-package.xml

@@ -1,102 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='adt-package'>
-<title>Optionally Customizing the Development Packages Installation</title>
-
-    <para>
-        Because the Yocto Project is suited for embedded Linux development, it is
-        likely that you will need to customize your development packages installation.
-        For example, if you are developing a minimal image, then you might not need
-        certain packages (e.g. graphics support packages).
-        Thus, you would like to be able to remove those packages from your target sysroot.
-    </para>
-
-<section id='package-management-systems'>
-    <title>Package Management Systems</title>
-
-    <para>
-        The OpenEmbedded build system supports the generation of sysroot files using
-        three different Package Management Systems (PMS):
-        <itemizedlist>
-            <listitem><para><emphasis>OPKG:</emphasis> A less well known PMS whose use
-                originated in the OpenEmbedded and OpenWrt embedded Linux projects.
-                This PMS works with files packaged in an <filename>.ipk</filename> format.
-                See <ulink url='http://en.wikipedia.org/wiki/Opkg'></ulink> for more
-                information about OPKG.</para></listitem>
-            <listitem><para><emphasis>RPM:</emphasis> A more widely known PMS intended for GNU/Linux
-                distributions.
-                This PMS works with files packaged in an <filename>.rpm</filename> format.
-                The build system currently installs through this PMS by default.
-                See <ulink url='http://en.wikipedia.org/wiki/RPM_Package_Manager'></ulink>
-                for more information about RPM.</para></listitem>
-            <listitem><para><emphasis>Debian:</emphasis> The PMS for Debian-based systems
-                is built on many PMS tools.
-                The lower-level PMS tool <filename>dpkg</filename> forms the base of the Debian PMS.
-                For information on dpkg see
-                <ulink url='http://en.wikipedia.org/wiki/Dpkg'></ulink>.</para></listitem>
-        </itemizedlist>
-    </para>
-</section>
-
-<section id='configuring-the-pms'>
-    <title>Configuring the PMS</title>
-
-    <para>
-        Whichever PMS you are using, you need to be sure that the
-        <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
-        variable in the <filename>conf/local.conf</filename>
-        file is set to reflect that system.
-        The first value you choose for the variable specifies the package file format for the root
-        filesystem at sysroot.
-        Additional values specify additional formats for convenience or testing.
-        See the <filename>conf/local.conf</filename> configuration file for
-        details.
-    </para>
-
-    <note>
-        For build performance information related to the PMS, see the
-        "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package.bbclass</filename></ulink>"
-        section in the Yocto Project Reference Manual.
-    </note>
-
-    <para>
-        As an example, consider a scenario where you are using OPKG and you want to add
-        the <filename>libglade</filename> package to the target sysroot.
-    </para>
-
-    <para>
-        First, you should generate the IPK file for the
-        <filename>libglade</filename> package and add it
-        into a working <filename>opkg</filename> repository.
-        Use these commands:
-        <literallayout class='monospaced'>
-     $ bitbake libglade
-     $ bitbake package-index
-        </literallayout>
-    </para>
-
-    <para>
-        Next, source the cross-toolchain environment setup script found in the
-        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
-        Follow that by setting up the installation destination to point to your
-        sysroot as <replaceable>sysroot_dir</replaceable>.
-        Finally, have an OPKG configuration file <replaceable>conf_file</replaceable>
-        that corresponds to the <filename>opkg</filename> repository you have just created.
-        The following command forms should now work:
-        <literallayout class='monospaced'>
-     $ opkg-cl –f <replaceable>conf_file</replaceable> -o <replaceable>sysroot_dir</replaceable> update
-     $ opkg-cl –f <replaceable>cconf_file</replaceable> -o <replaceable>sysroot_dir</replaceable> \
-        --force-overwrite install libglade
-     $ opkg-cl –f <replaceable>cconf_file</replaceable> -o <replaceable>sysroot_dir</replaceable> \
-        --force-overwrite install libglade-dbg
-     $ opkg-cl –f <replaceable>conf_file&gt; -o </replaceable>sysroot_dir&gt; \
-        --force-overwrite install libglade-dev
-        </literallayout>
-    </para>
-</section>
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/adt-manual/adt-prepare.xml

@@ -1,999 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='adt-prepare'>
-
-<title>Preparing for Application Development</title>
-
-<para>
-    In order to develop applications, you need set up your host development system.
-    Several ways exist that allow you to install cross-development tools, QEMU, the
-    Eclipse Yocto Plug-in, and other tools.
-    This chapter describes how to prepare for application development.
-</para>
-
-<section id='installing-the-adt'>
-    <title>Installing the ADT and Toolchains</title>
-
-    <para>
-        The following list describes installation methods that set up varying
-        degrees of tool availability on your system.
-        Regardless of the installation method you choose,
-        you must <filename>source</filename> the cross-toolchain
-        environment setup script, which establishes several key
-        environment variables, before you use a toolchain.
-        See the
-        "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>"
-        section for more information.
-    </para>
-
-    <note>
-        <para>
-            Avoid mixing installation methods when installing toolchains for
-            different architectures.
-            For example, avoid using the ADT Installer to install some
-            toolchains and then hand-installing cross-development toolchains
-            by running the toolchain installer for different architectures.
-            Mixing installation methods can result in situations where the
-            ADT Installer becomes unreliable and might not install the
-            toolchain.
-        </para>
-
-        <para>
-            If you must mix installation methods, you might avoid problems by
-            deleting <filename>/var/lib/opkg</filename>, thus purging the
-            <filename>opkg</filename> package metadata.
-        </para>
-    </note>
-
-    <para>
-        <itemizedlist>
-            <listitem><para><emphasis>Use the ADT installer script:</emphasis>
-                This method is the recommended way to install the ADT because it
-                automates much of the process for you.
-                For example, you can configure the installation to install the QEMU emulator
-                and the user-space NFS, specify which root filesystem profiles to download,
-                and define the target sysroot location.</para></listitem>
-            <listitem><para><emphasis>Use an existing toolchain:</emphasis>
-                Using this method, you select and download an architecture-specific
-                toolchain installer and then run the script to hand-install the toolchain.
-                If you use this method, you just get the cross-toolchain and QEMU - you do not
-                get any of the other mentioned benefits had you run the ADT Installer script.</para></listitem>
-            <listitem><para><emphasis>Use the toolchain from within the Build Directory:</emphasis>
-                If you already have a
-                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
-                you can build the cross-toolchain within the directory.
-                However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you
-                do not get any of the other benefits without taking separate steps.</para></listitem>
-        </itemizedlist>
-    </para>
-
-    <section id='using-the-adt-installer'>
-        <title>Using the ADT Installer</title>
-
-        <para>
-            To run the ADT Installer, you need to get the ADT Installer tarball, be sure
-            you have the necessary host development packages that support the ADT Installer,
-            and then run the ADT Installer Script.
-        </para>
-
-        <para>
-            For a list of the host packages needed to support ADT installation and use, see the
-            "ADT Installer Extras" lists in the
-            "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" section
-            of the Yocto Project Reference Manual.
-        </para>
-
-        <section id='getting-the-adt-installer-tarball'>
-            <title>Getting the ADT Installer Tarball</title>
-
-            <para>
-                The ADT Installer is contained in the ADT Installer tarball.
-                You can get the tarball using either of these methods:
-                <itemizedlist>
-                    <listitem><para><emphasis>Download the Tarball:</emphasis>
-                        You can download the tarball from
-                        <ulink url='&YOCTO_ADTINSTALLER_DL_URL;'></ulink> into
-                        any directory.</para></listitem>
-                    <listitem><para><emphasis>Build the Tarball:</emphasis>
-                        You can use
-                        <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
-                        to generate the tarball inside an existing
-                        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
-                        </para>
-                        <para>If you use BitBake to generate the ADT Installer
-                        tarball, you must <filename>source</filename> the
-                        environment setup script
-                        (<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
-                        or
-                        <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
-                        located in the Source Directory before running the
-                        <filename>bitbake</filename> command that creates the
-                        tarball.</para>
-                        <para>The following example commands establish
-                        the
-                        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
-                        check out the current release branch, set up the
-                        build environment while also creating the default
-                        Build Directory, and run the
-                        <filename>bitbake</filename> command that results in the
-                        tarball
-                        <filename>poky/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>:
-                        <note>
-                            Before using BitBake to build the ADT tarball, be
-                            sure to make sure your
-                            <filename>local.conf</filename> file is properly
-                            configured.
-                            See the
-                            "<ulink url='&YOCTO_DOCS_REF_URL;#user-configuration'>User Configuration</ulink>"
-                            section in the Yocto Project Reference Manual for
-                            general configuration information.
-                        </note>
-                        <literallayout class='monospaced'>
-     $ cd ~
-     $ git clone git://git.yoctoproject.org/poky
-     $ cd poky
-     $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
-     $ source &OE_INIT_FILE;
-     $ bitbake adt-installer
-                        </literallayout></para></listitem>
-                </itemizedlist>
-            </para>
-        </section>
-
-        <section id='configuring-and-running-the-adt-installer-script'>
-            <title>Configuring and Running the ADT Installer Script</title>
-
-            <para>
-                Before running the ADT Installer script, you need to unpack the tarball.
-                You can unpack the tarball in any directory you wish.
-                For example, this command copies the ADT Installer tarball from where
-                it was built into the home directory and then unpacks the tarball into
-                a top-level directory named <filename>adt-installer</filename>:
-                <literallayout class='monospaced'>
-     $ cd ~
-     $ cp poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME
-     $ tar -xjf adt_installer.tar.bz2
-                </literallayout>
-                Unpacking it creates the directory <filename>adt-installer</filename>,
-                which contains the ADT Installer script (<filename>adt_installer</filename>)
-                and its configuration file (<filename>adt_installer.conf</filename>).
-            </para>
-
-            <para>
-                Before you run the script, however, you should examine the ADT Installer configuration
-                file and be sure you are going to get what you want.
-                Your configurations determine which kernel and filesystem image are downloaded.
-            </para>
-
-            <para>
-                The following list describes the configurations you can define for the ADT Installer.
-                For configuration values and restrictions, see the comments in
-                the <filename>adt-installer.conf</filename> file:
-
-                <itemizedlist>
-                    <listitem><para><filename>YOCTOADT_REPO</filename>: This area
-                        includes the IPKG-based packages and the root filesystem upon which
-                        the installation is based.
-                        If you want to set up your own IPKG repository pointed to by
-                        <filename>YOCTOADT_REPO</filename>, you need to be sure that the
-                        directory structure follows the same layout as the reference directory
-                        set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.
-                        Also, your repository needs to be accessible through HTTP.</para></listitem>
-                    <listitem><para><filename>YOCTOADT_TARGETS</filename>: The machine
-                        target architectures for which you want to set up cross-development
-                        environments.</para></listitem>
-                    <listitem><para><filename>YOCTOADT_QEMU</filename>: Indicates whether
-                        or not to install the emulator QEMU.</para></listitem>
-                    <listitem><para><filename>YOCTOADT_NFS_UTIL</filename>: Indicates whether
-                        or not to install user-mode NFS.
-                        If you plan to use the Eclipse IDE Yocto plug-in against QEMU,
-                        you should install NFS.
-                        <note>To boot QEMU images using our userspace NFS server, you need
-                            to be running <filename>portmap</filename> or <filename>rpcbind</filename>.
-                            If you are running <filename>rpcbind</filename>, you will also need to add the
-                            <filename>-i</filename> option when <filename>rpcbind</filename> starts up.
-                            Please make sure you understand the security implications of doing this.
-                            You might also have to modify your firewall settings to allow
-                            NFS booting to work.</note></para></listitem>
-                    <listitem><para><filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>: The root
-                        filesystem images you want to download from the
-                        <filename>YOCTOADT_IPKG_REPO</filename> repository.</para></listitem>
-                    <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_</filename><replaceable>arch</replaceable>: The
-                        particular root filesystem used to extract and create the target sysroot.
-                        The value of this variable must have been specified with
-                        <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>.
-                        For example, if you downloaded both <filename>minimal</filename> and
-                        <filename>sato-sdk</filename> images by setting
-                        <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>
-                        to "minimal sato-sdk", then <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>
-                        must be set to either "minimal" or "sato-sdk".
-                        </para></listitem>
-                    <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_</filename><replaceable>arch</replaceable>: The
-                        location on the development host where the target sysroot is created.
-                        </para></listitem>
-                </itemizedlist>
-            </para>
-
-            <para>
-                After you have configured the <filename>adt_installer.conf</filename> file,
-                run the installer using the following command:
-                <literallayout class='monospaced'>
-     $ cd adt-installer
-     $ ./adt_installer
-                </literallayout>
-                Once the installer begins to run, you are asked to enter the
-                location for cross-toolchain installation.
-                The default location is
-                <filename>/opt/poky/</filename><replaceable>release</replaceable>.
-                After either accepting the default location or selecting your
-                own location, you are prompted to run the installation script
-                interactively or in silent mode.
-                If you want to closely monitor the installation,
-                choose “I” for interactive mode rather than “S” for silent mode.
-                Follow the prompts from the script to complete the installation.
-            </para>
-
-            <para>
-                Once the installation completes, the ADT, which includes the
-                cross-toolchain, is installed in the selected installation
-                directory.
-                You will notice environment setup files for the cross-toolchain
-                in the installation directory, and image tarballs in the
-                <filename>adt-installer</filename> directory according to your
-                installer configurations, and the target sysroot located
-                according to the
-                <filename>YOCTOADT_TARGET_SYSROOT_LOC_</filename><replaceable>arch</replaceable>
-                variable also in your configuration file.
-            </para>
-         </section>
-    </section>
-
-    <section id='using-an-existing-toolchain-tarball'>
-        <title>Using a Cross-Toolchain Tarball</title>
-
-        <para>
-            If you want to simply install a cross-toolchain by hand, you can
-            do so by running the toolchain installer.
-            The installer includes the pre-built cross-toolchain, the
-            <filename>runqemu</filename> script, and support files.
-            If you use this method to install the cross-toolchain, you
-            might still need to install the target sysroot by installing and
-            extracting it separately.
-            For information on how to install the sysroot, see the
-            "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.
-        </para>
-
-        <para>
-            Follow these steps:
-            <orderedlist>
-                <listitem><para><emphasis>Get your toolchain installer using one of the following methods:</emphasis>
-                    <itemizedlist>
-                        <listitem><para>Go to
-                            <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
-                            and find the folder that matches your host
-                            development system (i.e. <filename>i686</filename>
-                            for 32-bit machines or <filename>x86_64</filename>
-                            for 64-bit machines).</para>
-                            <para>Go into that folder and download the toolchain
-                            installer whose name includes the appropriate target
-                            architecture.
-                            The toolchains provided by the Yocto Project
-                            are based off of the
-                            <filename>core-image-sato</filename> image and
-                            contain libraries appropriate for developing
-                            against that image.
-                            For example, if your host development system is a
-                            64-bit x86 system and you are going to use
-                            your cross-toolchain for a 32-bit x86
-                            target, go into the <filename>x86_64</filename>
-                            folder and download the following installer:
-                            <literallayout class='monospaced'>
-     poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
-                            </literallayout></para></listitem>
-                        <listitem><para>Build your own toolchain installer.
-                            For cases where you cannot use an installer
-                            from the download area, you can build your own as
-                            described in the
-                            "<link linkend='optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</link>"
-                            section.</para></listitem>
-                    </itemizedlist></para></listitem>
-                <listitem><para><emphasis>Once you have the installer, run it to install the toolchain:</emphasis>
-                    <note>
-                        You must change the permissions on the toolchain
-                        installer script so that it is executable.
-                    </note></para>
-                    <para>The following command shows how to run the installer
-                    given a toolchain tarball for a 64-bit x86 development host
-                    system and a 32-bit x86 target architecture.
-                    The example assumes the toolchain installer is located
-                    in <filename>~/Downloads/</filename>.
-                    <literallayout class='monospaced'>
-     $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
-                    </literallayout>
-                    The first thing the installer prompts you for is the
-                    directory into which you want to install the toolchain.
-                    The default directory used is
-                    <filename>/opt/poky/&DISTRO;</filename>.
-                    If you do not have write permissions for the directory
-                    into which you are installing the toolchain, the
-                    toolchain installer notifies you and exits.
-                    Be sure you have write permissions in the directory and
-                    run the installer again.</para>
-                    <para>When the script finishes, the cross-toolchain is
-                    installed.
-                    You will notice environment setup files for the
-                    cross-toolchain in the installation directory.
-                    </para></listitem>
-            </orderedlist>
-        </para>
-    </section>
-
-    <section id='using-the-toolchain-from-within-the-build-tree'>
-        <title>Using BitBake and the Build Directory</title>
-
-        <para>
-            A final way of making the cross-toolchain available is to use BitBake
-            to generate the toolchain within an existing
-            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
-            This method does not install the toolchain into the default
-            <filename>/opt</filename> directory.
-            As with the previous method, if you need to install the target sysroot, you must
-            do that separately as well.
-        </para>
-
-        <para>
-            Follow these steps to generate the toolchain into the Build Directory:
-            <orderedlist>
-                <listitem><para><emphasis>Set up the Build Environment:</emphasis>
-                    Source the OpenEmbedded build environment setup
-                    script (i.e.
-                    <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
-                    or
-                    <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
-                    located in the
-                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
-                    </para></listitem>
-                <listitem><para><emphasis>Check your Local Configuration File:</emphasis>
-                    At this point, you should be sure that the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable
-                    in the <filename>local.conf</filename> file found in the
-                    <filename>conf</filename> directory of the Build Directory
-                    is set for the target architecture.
-                    Comments within the <filename>local.conf</filename> file
-                    list the values you can use for the
-                    <filename>MACHINE</filename> variable.
-                    If you do not change the <filename>MACHINE</filename>
-                    variable, the OpenEmbedded build system uses
-                    <filename>qemux86</filename> as the default target
-                    machine when building the cross-toolchain.
-                    <note>
-                        You can populate the Build Directory with the
-                        cross-toolchains for more than a single architecture.
-                        You just need to edit the <filename>MACHINE</filename>
-                        variable in the <filename>local.conf</filename> file and
-                        re-run the <filename>bitbake</filename> command.
-                    </note></para></listitem>
-                <listitem><para><emphasis>Make Sure Your Layers are Enabled:</emphasis>
-                    Examine the <filename>conf/bblayers.conf</filename> file
-                    and make sure that you have enabled all the compatible
-                    layers for your target machine.
-                    The OpenEmbedded build system needs to be aware of each
-                    layer you want included when building images and
-                    cross-toolchains.
-                    For information on how to enable a layer, see the
-                    "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
-                    section in the Yocto Project Development Manual.
-                    </para></listitem>
-                <listitem><para><emphasis>Generate the Cross-Toolchain:</emphasis>
-                    Run <filename>bitbake meta-ide-support</filename> to
-                    complete the cross-toolchain generation.
-                    Once the <filename>bitbake</filename> command finishes,
-                    the cross-toolchain is
-                    generated and populated within the Build Directory.
-                    You will notice environment setup files for the
-                    cross-toolchain that contain the string
-                    "<filename>environment-setup</filename>" in the
-                    Build Directory's <filename>tmp</filename> folder.</para>
-                    <para>Be aware that when you use this method to install the
-                    toolchain, you still need to separately extract and install
-                    the sysroot filesystem.
-                    For information on how to do this, see the
-                    "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.
-                    </para></listitem>
-            </orderedlist>
-        </para>
-    </section>
-</section>
-
-<section id='setting-up-the-cross-development-environment'>
-    <title>Setting Up the Cross-Development Environment</title>
-
-    <para>
-        Before you can develop using the cross-toolchain, you need to set up the
-        cross-development environment by sourcing the toolchain's environment setup script.
-        If you used the ADT Installer or hand-installed cross-toolchain,
-        then you can find this script in the directory you chose for installation.
-        For this release, the default installation directory is
-        <filename>&YOCTO_ADTPATH_DIR;</filename>.
-        If you installed the toolchain in the
-        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
-        you can find the environment setup
-        script for the toolchain in the Build Directory's <filename>tmp</filename> directory.
-    </para>
-
-    <para>
-        Be sure to run the environment setup script that matches the
-        architecture for which you are developing.
-        Environment setup scripts begin with the string
-        "<filename>environment-setup</filename>" and include as part of their
-        name the architecture.
-        For example, the toolchain environment setup script for a 64-bit
-        IA-based architecture installed in the default installation directory
-        would be the following:
-        <literallayout class='monospaced'>
-     &YOCTO_ADTPATH_DIR;/environment-setup-x86_64-poky-linux
-        </literallayout>
-        When you run the setup script, many environment variables are
-        defined:
-        <literallayout class='monospaced'>
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link
-     <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags
-        </literallayout>
-    </para>
-</section>
-
-<section id='securing-kernel-and-filesystem-images'>
-    <title>Securing Kernel and Filesystem Images</title>
-
-    <para>
-        You will need to have a kernel and filesystem image to boot using your
-        hardware or the QEMU emulator.
-        Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem
-        as the target sysroot, you need to extract the root filesystem.
-    </para>
-
-    <section id='getting-the-images'>
-        <title>Getting the Images</title>
-
-        <para>
-            To get the kernel and filesystem images, you either have to build them or download
-            pre-built versions.
-            For an example of how to build these images, see the
-            "<ulink url='&YOCTO_DOCS_QS_URL;#qs-buiding-images'>Buiding Images</ulink>"
-            section of the Yocto Project Quick Start.
-            For an example of downloading pre-build versions, see the
-            "<link linkend='using-pre-built'>Example Using Pre-Built Binaries and QEMU</link>"
-            section.
-        </para>
-
-        <para>
-            The Yocto Project ships basic kernel and filesystem images for several
-            architectures (<filename>x86</filename>, <filename>x86-64</filename>,
-            <filename>mips</filename>, <filename>powerpc</filename>, and <filename>arm</filename>)
-            that you can use unaltered in the QEMU emulator.
-            These kernel images reside in the release
-            area - <ulink url='&YOCTO_MACHINES_DL_URL;'></ulink>
-            and are ideal for experimentation using Yocto Project.
-            For information on the image types you can build using the OpenEmbedded build system,
-            see the
-            "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
-            chapter in the Yocto Project Reference Manual.
-        </para>
-
-        <para>
-            If you are planning on developing against your image and you are not
-            building or using one of the Yocto Project development images
-            (e.g. <filename>core-image-*-dev</filename>), you must be sure to
-            include the development packages as part of your image recipe.
-        </para>
-
-        <para>
-            If you plan on remotely deploying and debugging your
-            application from within the Eclipse IDE, you must have an image
-            that contains the Yocto Target Communication Framework (TCF) agent
-            (<filename>tcf-agent</filename>).
-            You can do this by including the <filename>eclipse-debug</filename>
-            image feature.
-            <note>
-                See the
-                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>"
-                section in the Yocto Project Reference Manual for information on
-                image features.
-            </note>
-            To include the <filename>eclipse-debug</filename> image feature,
-            modify your <filename>local.conf</filename> file in the
-            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-            so that the
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
-            variable includes the "eclipse-debug" feature.
-            After modifying the configuration file, you can rebuild the image.
-            Once the image is rebuilt, the <filename>tcf-agent</filename>
-            will be included in the image and is launched automatically after
-            the boot.
-        </para>
-    </section>
-
-    <section id='extracting-the-root-filesystem'>
-        <title>Extracting the Root Filesystem</title>
-
-        <para>
-            If you install your toolchain by hand or build it using BitBake and
-            you need a root filesystem, you need to extract it separately.
-            If you use the ADT Installer to install the ADT, the root
-            filesystem is automatically extracted and installed.
-        </para>
-
-        <para>
-            Here are some cases where you need to extract the root filesystem:
-            <itemizedlist>
-                <listitem><para>You want to boot the image using NFS.
-                    </para></listitem>
-                <listitem><para>You want to use the root filesystem as the
-                    target sysroot.
-                    For example, the Eclipse IDE environment with the Eclipse
-                    Yocto Plug-in installed allows you to use QEMU to boot
-                    under NFS.</para></listitem>
-                <listitem><para>You want to develop your target application
-                    using the root filesystem as the target sysroot.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-
-        <para>
-            To extract the root filesystem, first <filename>source</filename>
-            the cross-development environment setup script to establish
-            necessary environment variables.
-            If you built the toolchain in the Build Directory, you will find
-            the toolchain environment script in the
-            <filename>tmp</filename> directory.
-            If you installed the toolchain by hand, the environment setup
-            script is located in <filename>/opt/poky/&DISTRO;</filename>.
-        </para>
-
-        <para>
-            After sourcing the environment script, use the
-            <filename>runqemu-extract-sdk</filename> command and provide the
-            filesystem image.
-        </para>
-
-        <para>
-            Following is an example.
-            The second command sets up the environment.
-            In this case, the setup script is located in the
-            <filename>/opt/poky/&DISTRO;</filename> directory.
-            The third command extracts the root filesystem from a previously
-            built filesystem that is located in the
-            <filename>~/Downloads</filename> directory.
-            Furthermore, this command extracts the root filesystem into the
-            <filename>qemux86-sato</filename> directory:
-            <literallayout class='monospaced'>
-     $ cd ~
-     $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
-     $ runqemu-extract-sdk \
-        ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \
-        $HOME/qemux86-sato
-            </literallayout>
-            You could now point to the target sysroot at
-            <filename>qemux86-sato</filename>.
-        </para>
-    </section>
-</section>
-
-<section id='optionally-building-a-toolchain-installer'>
-    <title>Optionally Building a Toolchain Installer</title>
-
-    <para>
-        As an alternative to locating and downloading a toolchain installer,
-        you can build the toolchain installer if you have a
-        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
-        <note>
-            Although not the preferred method, it is also possible to use
-            <filename>bitbake meta-toolchain</filename> to build the toolchain
-            installer.
-            If you do use this method, you must separately install and extract
-            the target sysroot.
-            For information on how to install the sysroot, see the
-            "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
-            section.
-        </note>
-    </para>
-
-    <para>
-        To build the toolchain installer and populate the SDK image, use the
-        following command:
-        <literallayout class='monospaced'>
-     $ bitbake <replaceable>image</replaceable> -c populate_sdk
-        </literallayout>
-        The command results in a toolchain installer that contains the sysroot
-        that matches your target root filesystem.
-    </para>
-
-    <para>
-        Another powerful feature is that the toolchain is completely
-        self-contained.
-        The binaries are linked against their own copy of
-        <filename>libc</filename>, which results in no dependencies
-        on the target system.
-        To achieve this, the pointer to the dynamic loader is
-        configured at install time since that path cannot be dynamically
-        altered.
-        This is the reason for a wrapper around the
-        <filename>populate_sdk</filename> archive.
-    </para>
-
-    <para>
-        Another feature is that only one set of cross-canadian toolchain
-        binaries are produced per architecture.
-        This feature takes advantage of the fact that the target hardware can
-        be passed to <filename>gcc</filename> as a set of compiler options.
-        Those options are set up by the environment script and contained in
-        variables such as
-        <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
-        and
-        <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>.
-        This reduces the space needed for the tools.
-        Understand, however, that a sysroot is still needed for every target
-        since those binaries are target-specific.
-    </para>
-
-    <para>
-         Remember, before using any BitBake command, you
-         must source the build environment setup script
-         (i.e.
-         <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
-         or
-         <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
-         located in the Source Directory and you must make sure your
-         <filename>conf/local.conf</filename> variables are correct.
-         In particular, you need to be sure the
-         <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
-         variable matches the architecture for which you are building and that
-         the
-         <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
-         variable is correctly set if you are building a toolchain designed to
-         run on an architecture that differs from your current development host
-         machine (i.e. the build machine).
-    </para>
-
-    <para>
-        When the <filename>bitbake</filename> command completes, the toolchain
-        installer will be in
-        <filename>tmp/deploy/sdk</filename> in the Build Directory.
-        <note>
-            By default, this toolchain does not build static binaries.
-            If you want to use the toolchain to build these types of libraries,
-            you need to be sure your image has the appropriate static
-            development libraries.
-            Use the
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
-            variable inside your <filename>local.conf</filename> file to
-            install the appropriate library packages.
-            Following is an example using <filename>glibc</filename> static
-            development libraries:
-            <literallayout class='monospaced'>
-     IMAGE_INSTALL_append = " glibc-staticdev"
-            </literallayout>
-        </note>
-    </para>
-</section>
-
-<section id='optionally-using-an-external-toolchain'>
-    <title>Optionally Using an External Toolchain</title>
-
-    <para>
-        You might want to use an external toolchain as part of your
-        development.
-        If this is the case, the fundamental steps you need to accomplish
-        are as follows:
-        <itemizedlist>
-            <listitem><para>
-                Understand where the installed toolchain resides.
-                For cases where you need to build the external toolchain, you
-                would need to take separate steps to build and install the
-                toolchain.
-                </para></listitem>
-            <listitem><para>
-                Make sure you add the layer that contains the toolchain to
-                your <filename>bblayers.conf</filename> file through the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
-                variable.
-                </para></listitem>
-            <listitem><para>
-                Set the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNAL_TOOLCHAIN'><filename>EXTERNAL_TOOLCHAIN</filename></ulink>
-                variable in your <filename>local.conf</filename> file
-                to the location in which you installed the toolchain.
-                </para></listitem>
-        </itemizedlist>
-        A good example of an external toolchain used with the Yocto Project
-        is <trademark class='registered'>Mentor Graphics</trademark>
-        Sourcery G++ Toolchain.
-        You can see information on how to use that particular layer in the
-        <filename>README</filename> file at
-        <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
-        You can find further information by reading about the
-        <ulink url='&YOCTO_DOCS_REF_URL;#var-TCMODE'><filename>TCMODE</filename></ulink>
-        variable in the Yocto Project Reference Manual's variable glossary.
-    </para>
-</section>
-
-    <section id='using-pre-built'>
-        <title>Example Using Pre-Built Binaries and QEMU</title>
-
-        <para>
-            If hardware, libraries and services are stable, you can get started by using a pre-built binary
-            of the filesystem image, kernel, and toolchain and run it using the QEMU emulator.
-            This scenario is useful for developing application software.
-        </para>
-
-        <mediaobject>
-            <imageobject>
-            <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/>
-            </imageobject>
-            <caption>
-                <para>Using a Pre-Built Image</para>
-            </caption>
-        </mediaobject>
-
-        <para>
-            For this scenario, you need to do several things:
-        </para>
-
-        <itemizedlist>
-            <listitem><para>Install the appropriate stand-alone toolchain tarball.</para></listitem>
-            <listitem><para>Download the pre-built image that will boot with QEMU.
-                You need to be sure to get the QEMU image that matches your target machine’s
-                architecture (e.g. x86, ARM, etc.).</para></listitem>
-            <listitem><para>Download the filesystem image for your target machine's architecture.
-                </para></listitem>
-            <listitem><para>Set up the environment to emulate the hardware and then start the QEMU emulator.
-                </para></listitem>
-        </itemizedlist>
-
-        <section id='installing-the-toolchain'>
-            <title>Installing the Toolchain</title>
-
-            <para>
-                You can download a tarball installer, which includes the
-                pre-built toolchain, the <filename>runqemu</filename>
-                script, and support files from the appropriate directory under
-                <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
-                Toolchains are available for 32-bit and 64-bit x86 development
-                systems from the <filename>i686</filename> and
-                <filename>x86_64</filename> directories, respectively.
-                The toolchains the Yocto Project provides are based off the
-                <filename>core-image-sato</filename> image and contain
-                libraries appropriate for developing against that image.
-                Each type of development system supports five or more target
-                architectures.
-            </para>
-
-            <para>
-                The names of the tarball installer scripts are such that a
-                string representing the host system appears first in the
-                filename and then is immediately followed by a string
-                representing the target architecture.
-            </para>
-
-            <literallayout class='monospaced'>
-     poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh
-
-     Where:
-         <replaceable>host_system</replaceable> is a string representing your development system:
-
-                    i686 or x86_64.
-
-         <replaceable>image_type</replaceable> is a string representing the image you wish to
-                develop a Software Development Toolkit (SDK) for use against.
-                The Yocto Project builds toolchain installers using the
-                following BitBake command:
-
-                    bitbake core-image-sato -c populate_sdk
-
-         <replaceable>arch</replaceable> is a string representing the tuned target architecture:
-
-                    i586, x86_64, powerpc, mips, armv7a or armv5te
-
-         <replaceable>release_version</replaceable> is a string representing the release number of the
-                Yocto Project:
-
-                    &DISTRO;, &DISTRO;+snapshot
-            </literallayout>
-
-            <para>
-                For example, the following toolchain installer is for a 64-bit
-                development host system and a i586-tuned target architecture
-                based off the SDK for <filename>core-image-sato</filename>:
-                <literallayout class='monospaced'>
-     poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
-                </literallayout>
-            </para>
-
-            <para>
-                Toolchains are self-contained and by default are installed into
-                <filename>/opt/poky</filename>.
-                However, when you run the toolchain installer, you can choose an
-                installation directory.
-            </para>
-
-            <para>
-                The following command shows how to run the installer given a toolchain tarball
-                for a 64-bit x86 development host system and a 32-bit x86 target architecture.
-                You must change the permissions on the toolchain
-                installer script so that it is executable.
-            </para>
-
-            <para>
-                The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>.
-                <note>
-                    If you do not have write permissions for the directory into which you are installing
-                    the toolchain, the toolchain installer notifies you and exits.
-                    Be sure you have write permissions in the directory and run the installer again.
-                </note>
-            </para>
-
-            <para>
-                <literallayout class='monospaced'>
-     $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
-                </literallayout>
-            </para>
-
-            <para>
-                For more information on how to install tarballs, see the
-                "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and
-                "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" sections in the Yocto Project Application Developer's Guide.
-            </para>
-        </section>
-
-        <section id='downloading-the-pre-built-linux-kernel'>
-            <title>Downloading the Pre-Built Linux Kernel</title>
-
-            <para>
-                You can download the pre-built Linux kernel suitable for running in the QEMU emulator from
-                <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.
-                Be sure to use the kernel that matches the architecture you want to simulate.
-                Download areas exist for the five supported machine architectures:
-                <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>,
-                <filename>qemux86</filename>, and <filename>qemux86-64</filename>.
-            </para>
-
-            <para>
-                Most kernel files have one of the following forms:
-                <literallayout class='monospaced'>
-     *zImage-qemu<replaceable>arch</replaceable>.bin
-     vmlinux-qemu<replaceable>arch</replaceable>.bin
-
-     Where:
-         <replaceable>arch</replaceable> is a string representing the target architecture:
-                x86, x86-64, ppc, mips, or arm.
-                </literallayout>
-            </para>
-
-            <para>
-                You can learn more about downloading a Yocto Project kernel in the
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>"
-                bulleted item in the Yocto Project Development Manual.
-            </para>
-        </section>
-
-        <section id='downloading-the-filesystem'>
-            <title>Downloading the Filesystem</title>
-
-            <para>
-                You can also download the filesystem image suitable for your target architecture from
-                <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.
-                Again, be sure to use the filesystem that matches the architecture you want
-                to simulate.
-            </para>
-
-            <para>
-                The filesystem image has two tarball forms: <filename>ext3</filename> and
-                <filename>tar</filename>.
-                You must use the <filename>ext3</filename> form when booting an image using the
-                QEMU emulator.
-                The <filename>tar</filename> form can be flattened out in your host development system
-                and used for build purposes with the Yocto Project.
-                <literallayout class='monospaced'>
-     core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.ext3
-     core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.tar.bz2
-
-     Where:
-         <replaceable>profile</replaceable> is the filesystem image's profile:
-                   lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato,
-                   sato-dev, or sato-sdk. For information on these types of image
-                   profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
-                   chapter in the Yocto Project Reference Manual.
-
-         <replaceable>arch</replaceable> is a string representing the target architecture:
-                x86, x86-64, ppc, mips, or arm.
-                </literallayout>
-            </para>
-        </section>
-
-        <section id='setting-up-the-environment-and-starting-the-qemu-emulator'>
-            <title>Setting Up the Environment and Starting the QEMU Emulator</title>
-
-            <para>
-                Before you start the QEMU emulator, you need to set up the emulation environment.
-                The following command form sets up the emulation environment.
-                <literallayout class='monospaced'>
-     $ source &YOCTO_ADTPATH_DIR;/environment-setup-<replaceable>arch</replaceable>-poky-linux-<replaceable>if</replaceable>
-
-     Where:
-         <replaceable>arch</replaceable> is a string representing the target architecture:
-                i586, x86_64, ppc603e, mips, or armv5te.
-
-         <replaceable>if</replaceable> is a string representing an embedded application binary interface.
-              Not all setup scripts include this string.
-                </literallayout>
-            </para>
-
-            <para>
-                Finally, this command form invokes the QEMU emulator
-                <literallayout class='monospaced'>
-     $ runqemu <replaceable>qemuarch</replaceable> <replaceable>kernel-image</replaceable> <replaceable>filesystem-image</replaceable>
-
-     Where:
-         <replaceable>qemuarch</replaceable> is a string representing the target architecture: qemux86, qemux86-64,
-                    qemuppc, qemumips, or qemuarm.
-
-         <replaceable>kernel-image</replaceable> is the architecture-specific kernel image.
-
-         <replaceable>filesystem-image</replaceable> is the .ext3 filesystem image.
-
-                </literallayout>
-            </para>
-
-            <para>
-                Continuing with the example, the following two commands setup the emulation
-                environment and launch QEMU.
-                This example assumes the root filesystem (<filename>.ext3</filename> file) and
-                the pre-built kernel image file both reside in your home directory.
-                The kernel and filesystem are for a 32-bit target architecture.
-                <literallayout class='monospaced'>
-     $ cd $HOME
-     $ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux
-     $ runqemu qemux86 bzImage-qemux86.bin \
-     core-image-sato-qemux86.ext3
-                </literallayout>
-            </para>
-
-            <para>
-                The environment in which QEMU launches varies depending on the filesystem image and on the
-                target architecture.
-                For example, if you source the environment for the ARM target
-                architecture and then boot the minimal QEMU image, the emulator comes up in a new
-                shell in command-line mode.
-                However, if you boot the SDK image, QEMU comes up with a GUI.
-                <note>Booting the PPC image results in QEMU launching in the same shell in
-                command-line mode.</note>
-            </para>
-        </section>
-</section>
-
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/adt-manual/adt-style.css

@@ -1,984 +0,0 @@
-/*
-   Generic XHTML / DocBook XHTML CSS Stylesheet.
-
-   Browser wrangling and typographic design by
-      Oyvind Kolas / pippin@gimp.org
-
-   Customised for Poky by
-      Matthew Allum / mallum@o-hand.com
-
-   Thanks to:
-     Liam R. E. Quin
-     William Skaggs
-     Jakub Steiner
-
-   Structure
-   ---------
-
-   The stylesheet is divided into the following sections:
-
-       Positioning
-          Margins, paddings, width, font-size, clearing.
-       Decorations
-          Borders, style
-       Colors
-          Colors
-       Graphics
-          Graphical backgrounds
-       Nasty IE tweaks
-          Workarounds needed to make it work in internet explorer,
-          currently makes the stylesheet non validating, but up until
-          this point it is validating.
-       Mozilla extensions
-          Transparency for footer
-	  Rounded corners on boxes
-
-*/
-
-
-  /*************** /
- /  Positioning   /
-/ ***************/
-
-body {
-  font-family: Verdana, Sans, sans-serif;
-
-  min-width: 640px;
-  width: 80%;
-  margin:  0em auto;
-  padding: 2em 5em 5em 5em;
-  color: #333;
-}
-
-h1,h2,h3,h4,h5,h6,h7 {
-  font-family: Arial, Sans;
-  color: #00557D;
-  clear: both;
-}
-
-h1 {
-  font-size: 2em;
-  text-align: left;
-  padding: 0em 0em 0em 0em;
-  margin: 2em 0em 0em 0em;
-}
-
-h2.subtitle {
-  margin: 0.10em 0em 3.0em 0em;
-  padding: 0em 0em 0em 0em;
-  font-size: 1.8em;
-  padding-left: 20%;
-  font-weight: normal;
-  font-style: italic;
-}
-
-h2 {
-  margin: 2em 0em 0.66em 0em;
-  padding: 0.5em 0em 0em 0em;
-  font-size: 1.5em;
-  font-weight: bold;
-}
-
-h3.subtitle {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-  font-size: 142.14%;
-  text-align: right;
-}
-
-h3 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 140%;
-  font-weight: bold;
-}
-
-h4 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 120%;
-  font-weight: bold;
-}
-
-h5 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 110%;
-  font-weight: bold;
-}
-
-h6 {
-  margin: 1em 0em 0em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 110%;
-  font-weight: bold;
-}
-
-.authorgroup {
-  background-color: transparent;
-  background-repeat: no-repeat;
-  padding-top: 256px;
-  background-image: url("figures/adt-title.png");
-  background-position: left top;
-  margin-top: -256px;
-  padding-right: 50px;
-  margin-left: 0px;
-  text-align: right;
-  width: 740px;
-}
-
-h3.author {
-  margin: 0em 0me 0em 0em;
-  padding: 0em 0em 0em 0em;
-  font-weight: normal;
-  font-size: 100%;
-  color: #333;
-  clear: both;
-}
-
-.author tt.email {
-  font-size: 66%;
-}
-
-.titlepage hr {
-  width: 0em;
-  clear: both;
-}
-
-.revhistory {
-  padding-top: 2em;
-  clear: both;
-}
-
-.toc,
-.list-of-tables,
-.list-of-examples,
-.list-of-figures {
-  padding: 1.33em 0em 2.5em 0em;
-  color: #00557D;
-}
-
-.toc p,
-.list-of-tables p,
-.list-of-figures p,
-.list-of-examples p {
-  padding: 0em 0em 0em 0em;
-  padding: 0em 0em 0.3em;
-  margin: 1.5em 0em 0em 0em;
-}
-
-.toc p b,
-.list-of-tables p b,
-.list-of-figures p b,
-.list-of-examples p b{
-  font-size: 100.0%;
-  font-weight: bold;
-}
-
-.toc dl,
-.list-of-tables dl,
-.list-of-figures dl,
-.list-of-examples dl {
-  margin: 0em 0em 0.5em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.toc dt {
-  margin: 0em 0em 0em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.toc dd {
-  margin: 0em 0em 0em 2.6em;
-  padding: 0em 0em 0em 0em;
-}
-
-div.glossary dl,
-div.variablelist dl {
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
-  font-weight: normal;
-  width: 20em;
-  text-align: right;
-}
-
-.variablelist dl dt {
-  margin-top: 0.5em;
-}
-
-.glossary dl dd,
-.variablelist dl dd {
-  margin-top: -1em;
-  margin-left: 25.5em;
-}
-
-.glossary dd p,
-.variablelist dd p {
-  margin-top: 0em;
-  margin-bottom: 1em;
-}
-
-
-div.calloutlist table td {
-  padding: 0em 0em 0em 0em;
-  margin: 0em 0em 0em 0em;
-}
-
-div.calloutlist table td p {
-  margin-top: 0em;
-  margin-bottom: 1em;
-}
-
-div p.copyright {
-  text-align: left;
-}
-
-div.legalnotice p.legalnotice-title {
-  margin-bottom: 0em;
-}
-
-p {
-  line-height: 1.5em;
-  margin-top: 0em;
-
-}
-
-dl {
-  padding-top: 0em;
-}
-
-hr {
-  border: solid 1px;
-}
-
-
-.mediaobject,
-.mediaobjectco {
-  text-align: center;
-}
-
-img {
-  border: none;
-}
-
-ul {
-  padding: 0em 0em 0em 1.5em;
-}
-
-ul li {
-  padding: 0em 0em 0em 0em;
-}
-
-ul li p {
-  text-align: left;
-}
-
-table {
-  width :100%;
-}
-
-th {
-  padding: 0.25em;
-  text-align: left;
-  font-weight: normal;
-  vertical-align: top;
-}
-
-td {
-  padding: 0.25em;
-  vertical-align: top;
-}
-
-p a[id] {
-  margin: 0px;
-  padding: 0px;
-  display: inline;
-  background-image: none;
-}
-
-a {
-  text-decoration: underline;
-  color: #444;
-}
-
-pre {
-    overflow: auto;
-}
-
-a:hover {
-  text-decoration: underline;
-  /*font-weight: bold;*/
-}
-
-/* This style defines how the permalink character
-   appears by itself and when hovered over with
-   the mouse. */
-
-[alt='Permalink'] { color: #eee; }
-[alt='Permalink']:hover { color: black; }
-
-
-div.informalfigure,
-div.informalexample,
-div.informaltable,
-div.figure,
-div.table,
-div.example {
-  margin: 1em 0em;
-  padding: 1em;
-  page-break-inside: avoid;
-}
-
-
-div.informalfigure p.title b,
-div.informalexample p.title b,
-div.informaltable p.title b,
-div.figure p.title b,
-div.example p.title b,
-div.table p.title b{
-    padding-top: 0em;
-    margin-top: 0em;
-    font-size: 100%;
-    font-weight: normal;
-}
-
-.mediaobject .caption,
-.mediaobject .caption p  {
-  text-align: center;
-  font-size: 80%;
-  padding-top: 0.5em;
-  padding-bottom: 0.5em;
-}
-
-.epigraph {
-  padding-left: 55%;
-  margin-bottom: 1em;
-}
-
-.epigraph p {
-  text-align: left;
-}
-
-.epigraph .quote {
-  font-style: italic;
-}
-.epigraph .attribution {
-  font-style: normal;
-  text-align: right;
-}
-
-span.application {
-  font-style: italic;
-}
-
-.programlisting {
-  font-family: monospace;
-  font-size: 80%;
-  white-space: pre;
-  margin: 1.33em 0em;
-  padding: 1.33em;
-}
-
-.tip,
-.warning,
-.caution,
-.note {
-  margin-top: 1em;
-  margin-bottom: 1em;
-
-}
-
-/* force full width of table within div */
-.tip table,
-.warning table,
-.caution table,
-.note table {
-  border: none;
-  width: 100%;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  padding: 0.8em 0.0em 0.0em 0.0em;
-  margin : 0em 0em 0em 0em;
-}
-
-.tip p,
-.warning p,
-.caution p,
-.note p {
-  margin-top: 0.5em;
-  margin-bottom: 0.5em;
-  padding-right: 1em;
-  text-align: left;
-}
-
-.acronym {
-  text-transform: uppercase;
-}
-
-b.keycap,
-.keycap {
-  padding: 0.09em 0.3em;
-  margin: 0em;
-}
-
-.itemizedlist li {
-  clear: none;
-}
-
-.filename {
-  font-size: medium;
-  font-family: Courier, monospace;
-}
-
-
-div.navheader, div.heading{
-  position: absolute;
-  left: 0em;
-  top: 0em;
-  width: 100%;
-  background-color: #cdf;
-  width: 100%;
-}
-
-div.navfooter, div.footing{
-  position: fixed;
-  left: 0em;
-  bottom: 0em;
-  background-color: #eee;
-  width: 100%;
-}
-
-
-div.navheader td,
-div.navfooter td {
-  font-size: 66%;
-}
-
-div.navheader table th {
-  /*font-family: Georgia, Times, serif;*/
-  /*font-size: x-large;*/
-  font-size: 80%;
-}
-
-div.navheader table {
-  border-left: 0em;
-  border-right: 0em;
-  border-top: 0em;
-  width: 100%;
-}
-
-div.navfooter table {
-  border-left: 0em;
-  border-right: 0em;
-  border-bottom: 0em;
-  width: 100%;
-}
-
-div.navheader table td a,
-div.navfooter table td a {
-  color: #777;
-  text-decoration: none;
-}
-
-/* normal text in the footer */
-div.navfooter table td {
-  color: black;
-}
-
-div.navheader table td a:visited,
-div.navfooter table td a:visited {
-  color: #444;
-}
-
-
-/* links in header and footer */
-div.navheader table td a:hover,
-div.navfooter table td a:hover {
-  text-decoration: underline;
-  background-color: transparent;
-  color: #33a;
-}
-
-div.navheader hr,
-div.navfooter hr {
-  display: none;
-}
-
-
-.qandaset tr.question td p {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.qandaset tr.answer td p {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-}
-.answer td {
-  padding-bottom: 1.5em;
-}
-
-.emphasis {
-  font-weight: bold;
-}
-
-
-  /************* /
- / decorations  /
-/ *************/
-
-.titlepage {
-}
-
-.part .title {
-}
-
-.subtitle {
-    border: none;
-}
-
-/*
-h1 {
-  border: none;
-}
-
-h2 {
-  border-top: solid 0.2em;
-  border-bottom: solid 0.06em;
-}
-
-h3 {
-  border-top: 0em;
-  border-bottom: solid 0.06em;
-}
-
-h4 {
-  border: 0em;
-  border-bottom: solid 0.06em;
-}
-
-h5 {
-  border: 0em;
-}
-*/
-
-.programlisting {
-  border: solid 1px;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example {
-  border: 1px solid;
-}
-
-
-
-.tip,
-.warning,
-.caution,
-.note {
-  border: 1px solid;
-}
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  border-bottom: 1px solid;
-}
-
-.question td {
-  border-top: 1px solid black;
-}
-
-.answer {
-}
-
-
-b.keycap,
-.keycap {
-  border: 1px solid;
-}
-
-
-div.navheader, div.heading{
-  border-bottom: 1px solid;
-}
-
-
-div.navfooter, div.footing{
-  border-top: 1px solid;
-}
-
-  /********* /
- /  colors  /
-/ *********/
-
-body {
-  color: #333;
-  background: white;
-}
-
-a {
-  background: transparent;
-}
-
-a:hover {
-  background-color: #dedede;
-}
-
-
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7,
-h8 {
-  background-color: transparent;
-}
-
-hr {
-  border-color: #aaa;
-}
-
-
-.tip, .warning, .caution, .note {
-  border-color: #fff;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  border-bottom-color: #fff;
-}
-
-
-.warning {
-  background-color: #f0f0f2;
-}
-
-.caution {
-  background-color: #f0f0f2;
-}
-
-.tip {
-  background-color: #f0f0f2;
-}
-
-.note {
-  background-color: #f0f0f2;
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
-  color: #044;
-}
-
-div.figure,
-div.table,
-div.example,
-div.informalfigure,
-div.informaltable,
-div.informalexample {
-  border-color: #aaa;
-}
-
-pre.programlisting {
-  color: black;
-  background-color: #fff;
-  border-color: #aaa;
-  border-width: 2px;
-}
-
-.guimenu,
-.guilabel,
-.guimenuitem {
-  background-color: #eee;
-}
-
-
-b.keycap,
-.keycap {
-  background-color: #eee;
-  border-color: #999;
-}
-
-
-div.navheader {
-  border-color: black;
-}
-
-
-div.navfooter {
-  border-color: black;
-}
-
-
-  /*********** /
- /  graphics  /
-/ ***********/
-
-/*
-body {
-  background-image: url("images/body_bg.jpg");
-  background-attachment: fixed;
-}
-
-.navheader,
-.note,
-.tip {
-  background-image: url("images/note_bg.jpg");
-  background-attachment: fixed;
-}
-
-.warning,
-.caution {
-  background-image: url("images/warning_bg.jpg");
-  background-attachment: fixed;
-}
-
-.figure,
-.informalfigure,
-.example,
-.informalexample,
-.table,
-.informaltable {
-  background-image: url("images/figure_bg.jpg");
-  background-attachment: fixed;
-}
-
-*/
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7{
-}
-
-/*
-Example of how to stick an image as part of the title.
-
-div.article .titlepage .title
-{
-  background-image: url("figures/white-on-black.png");
-  background-position: center;
-  background-repeat: repeat-x;
-}
-*/
-
-div.preface .titlepage .title,
-div.colophon .title,
-div.chapter .titlepage .title,
-div.article .titlepage .title
-{
-}
-
-div.section div.section .titlepage .title,
-div.sect2 .titlepage .title {
-    background: none;
-}
-
-
-h1.title {
-  background-color: transparent;
-  background-repeat: no-repeat;
-  height: 256px;
-  text-indent: -9000px;
-  overflow:hidden;
-}
-
-h2.subtitle {
-  background-color: transparent;
-  text-indent: -9000px;
-  overflow:hidden;
-  width: 0px;
-  display: none;
-}
-
-  /*************************************** /
- /  pippin.gimp.org specific alterations  /
-/ ***************************************/
-
-/*
-div.heading, div.navheader {
-  color: #777;
-  font-size: 80%;
-  padding: 0;
-  margin: 0;
-  text-align: left;
-  position: absolute;
-  top: 0px;
-  left: 0px;
-  width: 100%;
-  height: 50px;
-  background: url('/gfx/heading_bg.png') transparent;
-  background-repeat: repeat-x;
-  background-attachment: fixed;
-  border: none;
-}
-
-div.heading a {
-  color: #444;
-}
-
-div.footing, div.navfooter {
-  border: none;
-  color: #ddd;
-  font-size: 80%;
-  text-align:right;
-
-  width: 100%;
-  padding-top: 10px;
-  position: absolute;
-  bottom: 0px;
-  left: 0px;
-
-  background: url('/gfx/footing_bg.png') transparent;
-}
-*/
-
-
-
-  /****************** /
- /  nasty ie tweaks  /
-/ ******************/
-
-/*
-div.heading, div.navheader {
-  width:expression(document.body.clientWidth + "px");
-}
-
-div.footing, div.navfooter {
-  width:expression(document.body.clientWidth + "px");
-  margin-left:expression("-5em");
-}
-body {
-  padding:expression("4em 5em 0em 5em");
-}
-*/
-
-  /**************************************** /
- / mozilla vendor specific css extensions  /
-/ ****************************************/
-/*
-div.navfooter, div.footing{
-  -moz-opacity: 0.8em;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example,
-.tip,
-.warning,
-.caution,
-.note {
-  -moz-border-radius: 0.5em;
-}
-
-b.keycap,
-.keycap {
-  -moz-border-radius: 0.3em;
-}
-*/
-
-table tr td table tr td {
-  display: none;
-}
-
-
-hr {
-  display: none;
-}
-
-table {
-  border: 0em;
-}
-
- .photo {
-  float: right;
-  margin-left:   1.5em;
-  margin-bottom: 1.5em;
-  margin-top: 0em;
-  max-width:      17em;
-  border:     1px solid gray;
-  padding:    3px;
-  background: white;
-}
- .seperator {
-   padding-top: 2em;
-   clear: both;
-  }
-
-  #validators {
-      margin-top: 5em;
-      text-align: right;
-      color: #777;
-  }
-  @media print {
-      body {
-          font-size: 8pt;
-      }
-      .noprint {
-          display: none;
-      }
-  }
-
-
-.tip,
-.note {
-   background: #f0f0f2;
-   color: #333;
-   padding: 20px;
-   margin: 20px;
-}
-
-.tip h3,
-.note h3 {
-   padding: 0em;
-   margin: 0em;
-   font-size: 2em;
-   font-weight: bold;
-   color: #333;
-}
-
-.tip a,
-.note a {
-   color: #333;
-   text-decoration: underline;
-}
-
-.footnote {
-   font-size: small;
-   color: #333;
-}
-
-/* Changes the announcement text */
-.tip h3,
-.warning h3,
-.caution h3,
-.note h3 {
-   font-size:large;
-   color: #00557D;
-}

documentation/boilerplate.rst

@@ -0,0 +1,18 @@
+.. include:: <xhtml1-lat1.txt>
+.. include:: <xhtml1-symbol.txt>
+
+----
+
+| |project_name|
+| <docs@lists.yoctoproject.org>
+
+Permission is granted to copy, distribute and/or modify this document under the
+terms of the `Creative Commons Attribution-Share Alike 2.0 UK: England & Wales
+<http://creativecommons.org/licenses/by-sa/2.0/uk/>`_ as published by Creative
+Commons.
+
+To report any inaccuracies or problems with this (or any other Yocto Project)
+manual, or to send additions or changes, please send email/patches to the Yocto
+Project documentation mailing list at ``docs@lists.yoctoproject.org`` or
+log into the freenode ``#yocto`` channel.
+

documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-customization.xsl

@@ -1,24 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
-
-  <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-<!--
-
-  <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-  <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
-
--->
-
-  <xsl:import href="brief-yoctoprojectqs-titlepage.xsl"/>
-
-  <xsl:include href="../template/permalinks.xsl"/>
-  <xsl:include href="../template/section.title.xsl"/>
-  <xsl:include href="../template/component.title.xsl"/>
-  <xsl:include href="../template/division.title.xsl"/>
-  <xsl:include href="../template/formal.object.heading.xsl"/>
-
-  <xsl:param name="generate.toc" select="'article nop'"></xsl:param>
-  <xsl:param name="html.stylesheet" select="'brief-yoctoprojectqs-style.css'" />
-</xsl:stylesheet>

documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-style.css

@@ -1,989 +0,0 @@
-/*
-   Generic XHTML / DocBook XHTML CSS Stylesheet.
-
-   Browser wrangling and typographic design by
-      Oyvind Kolas / pippin@gimp.org
-
-   Customised for Poky by
-      Matthew Allum / mallum@o-hand.com
-
-   Thanks to:
-     Liam R. E. Quin
-     William Skaggs
-     Jakub Steiner
-
-   Structure
-   ---------
-
-   The stylesheet is divided into the following sections:
-
-       Positioning
-          Margins, paddings, width, font-size, clearing.
-       Decorations
-          Borders, style
-       Colors
-          Colors
-       Graphics
-          Graphical backgrounds
-       Nasty IE tweaks
-          Workarounds needed to make it work in internet explorer,
-          currently makes the stylesheet non validating, but up until
-          this point it is validating.
-       Mozilla extensions
-          Transparency for footer
-	  Rounded corners on boxes
-
-*/
-
-
-  /*************** /
- /  Positioning   /
-/ ***************/
-
-body {
-  font-family: Verdana, Sans, sans-serif;
-
-  min-width: 640px;
-  width: 80%;
-  margin:  0em auto;
-  padding: 2em 5em 5em 5em;
-  color: #333;
-}
-
-h1,h2,h3,h4,h5,h6,h7 {
-  font-family: Arial, Sans;
-  color: #00557D;
-  clear: both;
-}
-
-h1 {
-  font-size: 2em;
-  text-align: left;
-  padding: 0em 0em 0em 0em;
-  margin: 2em 0em 0em 0em;
-}
-
-h2.subtitle {
-  margin: 0.10em 0em 3.0em 0em;
-  padding: 0em 0em 0em 0em;
-  font-size: 1.8em;
-  padding-left: 20%;
-  font-weight: normal;
-  font-style: italic;
-}
-
-h2 {
-  margin: 2em 0em 0.66em 0em;
-  padding: 0.5em 0em 0em 0em;
-  font-size: 1.5em;
-  font-weight: bold;
-}
-
-h3.subtitle {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-  font-size: 142.14%;
-  text-align: right;
-}
-
-h3 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 140%;
-  font-weight: bold;
-}
-
-h4 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 120%;
-  font-weight: bold;
-}
-
-h5 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 110%;
-  font-weight: bold;
-}
-
-h6 {
-  margin: 1em 0em 0em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 110%;
-  font-weight: bold;
-}
-
-.authorgroup {
-  background-color: transparent;
-  background-repeat: no-repeat;
-  padding-top: 256px;
-  background-image: url("figures/bypqs-title.png");
-  background-position: left top;
-  margin-top: -256px;
-  padding-right: 50px;
-  margin-left: 0px;
-  text-align: right;
-  width: 740px;
-}
-
-h3.author {
-  margin: 0em 0me 0em 0em;
-  padding: 0em 0em 0em 0em;
-  font-weight: normal;
-  font-size: 100%;
-  color: #333;
-  clear: both;
-}
-
-.author tt.email {
-  font-size: 66%;
-}
-
-.titlepage hr {
-  width: 0em;
-  clear: both;
-}
-
-.revhistory {
-  padding-top: 2em;
-  clear: both;
-}
-
-.toc,
-.list-of-tables,
-.list-of-examples,
-.list-of-figures {
-  padding: 1.33em 0em 2.5em 0em;
-  color: #00557D;
-}
-
-.toc p,
-.list-of-tables p,
-.list-of-figures p,
-.list-of-examples p {
-  padding: 0em 0em 0em 0em;
-  padding: 0em 0em 0.3em;
-  margin: 1.5em 0em 0em 0em;
-}
-
-.toc p b,
-.list-of-tables p b,
-.list-of-figures p b,
-.list-of-examples p b{
-  font-size: 100.0%;
-  font-weight: bold;
-}
-
-.toc dl,
-.list-of-tables dl,
-.list-of-figures dl,
-.list-of-examples dl {
-  margin: 0em 0em 0.5em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.toc dt {
-  margin: 0em 0em 0em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.toc dd {
-  margin: 0em 0em 0em 2.6em;
-  padding: 0em 0em 0em 0em;
-}
-
-div.glossary dl,
-div.variablelist dl {
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
-  font-weight: normal;
-  width: 20em;
-  text-align: right;
-}
-
-.variablelist dl dt {
-  margin-top: 0.5em;
-}
-
-.glossary dl dd,
-.variablelist dl dd {
-  margin-top: -1em;
-  margin-left: 25.5em;
-}
-
-.glossary dd p,
-.variablelist dd p {
-  margin-top: 0em;
-  margin-bottom: 1em;
-}
-
-
-div.calloutlist table td {
-  padding: 0em 0em 0em 0em;
-  margin: 0em 0em 0em 0em;
-}
-
-div.calloutlist table td p {
-  margin-top: 0em;
-  margin-bottom: 1em;
-}
-
-div p.copyright {
-  text-align: left;
-}
-
-div.legalnotice p.legalnotice-title {
-  margin-bottom: 0em;
-}
-
-p {
-  line-height: 1.5em;
-  margin-top: 0em;
-
-}
-
-dl {
-  padding-top: 0em;
-}
-
-hr {
-  border: solid 1px;
-}
-
-
-.mediaobject,
-.mediaobjectco {
-  text-align: center;
-}
-
-img {
-  border: none;
-}
-
-ul {
-  padding: 0em 0em 0em 1.5em;
-}
-
-ul li {
-  padding: 0em 0em 0em 0em;
-}
-
-ul li p {
-  text-align: left;
-}
-
-table {
-  width :100%;
-}
-
-th {
-  padding: 0.25em;
-  text-align: left;
-  font-weight: normal;
-  vertical-align: top;
-}
-
-td {
-  padding: 0.25em;
-  vertical-align: top;
-}
-
-p a[id] {
-  margin: 0px;
-  padding: 0px;
-  display: inline;
-  background-image: none;
-}
-
-a {
-  text-decoration: underline;
-  color: #444;
-}
-
-pre {
-    overflow: auto;
-}
-
-a:hover {
-  text-decoration: underline;
-  /*font-weight: bold;*/
-}
-
-/* This style defines how the permalink character
-   appears by itself and when hovered over with
-   the mouse. */
-
-[alt='Permalink'] { color: #eee; }
-[alt='Permalink']:hover { color: black; }
-
-
-div.informalfigure,
-div.informalexample,
-div.informaltable,
-div.figure,
-div.table,
-div.example {
-  margin: 1em 0em;
-  padding: 1em;
-  page-break-inside: avoid;
-}
-
-
-div.informalfigure p.title b,
-div.informalexample p.title b,
-div.informaltable p.title b,
-div.figure p.title b,
-div.example p.title b,
-div.table p.title b{
-    padding-top: 0em;
-    margin-top: 0em;
-    font-size: 100%;
-    font-weight: normal;
-}
-
-.mediaobject .caption,
-.mediaobject .caption p  {
-  text-align: center;
-  font-size: 80%;
-  padding-top: 0.5em;
-  padding-bottom: 0.5em;
-}
-
-.epigraph {
-  padding-left: 55%;
-  margin-bottom: 1em;
-}
-
-.epigraph p {
-  text-align: left;
-}
-
-.epigraph .quote {
-  font-style: italic;
-}
-.epigraph .attribution {
-  font-style: normal;
-  text-align: right;
-}
-
-span.application {
-  font-style: italic;
-}
-
-.programlisting {
-  font-family: monospace;
-  font-size: 80%;
-  white-space: pre;
-  margin: 1.33em 0em;
-  padding: 1.33em;
-}
-
-.tip,
-.warning,
-.caution,
-.note {
-  margin-top: 1em;
-  margin-bottom: 1em;
-
-}
-
-/* force full width of table within div */
-.tip table,
-.warning table,
-.caution table,
-.note table {
-  border: none;
-  width: 100%;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  padding: 0.8em 0.0em 0.0em 0.0em;
-  margin : 0em 0em 0em 0em;
-}
-
-.tip p,
-.warning p,
-.caution p,
-.note p {
-  margin-top: 0.5em;
-  margin-bottom: 0.5em;
-  padding-right: 1em;
-  text-align: left;
-}
-
-.acronym {
-  text-transform: uppercase;
-}
-
-b.keycap,
-.keycap {
-  padding: 0.09em 0.3em;
-  margin: 0em;
-}
-
-.itemizedlist li {
-  clear: none;
-}
-
-.filename {
-  font-size: medium;
-  font-family: Courier, monospace;
-}
-
-
-div.navheader, div.heading{
-  position: absolute;
-  left: 0em;
-  top: 0em;
-  width: 100%;
-  background-color: #cdf;
-  width: 100%;
-}
-
-div.navfooter, div.footing{
-  position: fixed;
-  left: 0em;
-  bottom: 0em;
-  background-color: #eee;
-  width: 100%;
-}
-
-
-div.navheader td,
-div.navfooter td {
-  font-size: 66%;
-}
-
-div.navheader table th {
-  /*font-family: Georgia, Times, serif;*/
-  /*font-size: x-large;*/
-  font-size: 80%;
-}
-
-div.navheader table {
-  border-left: 0em;
-  border-right: 0em;
-  border-top: 0em;
-  width: 100%;
-}
-
-div.navfooter table {
-  border-left: 0em;
-  border-right: 0em;
-  border-bottom: 0em;
-  width: 100%;
-}
-
-div.navheader table td a,
-div.navfooter table td a {
-  color: #777;
-  text-decoration: none;
-}
-
-/* normal text in the footer */
-div.navfooter table td {
-  color: black;
-}
-
-div.navheader table td a:visited,
-div.navfooter table td a:visited {
-  color: #444;
-}
-
-
-/* links in header and footer */
-div.navheader table td a:hover,
-div.navfooter table td a:hover {
-  text-decoration: underline;
-  background-color: transparent;
-  color: #33a;
-}
-
-div.navheader hr,
-div.navfooter hr {
-  display: none;
-}
-
-
-.qandaset tr.question td p {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.qandaset tr.answer td p {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-}
-.answer td {
-  padding-bottom: 1.5em;
-}
-
-.emphasis {
-  font-weight: bold;
-}
-
-
-  /************* /
- / decorations  /
-/ *************/
-
-.titlepage {
-}
-
-.part .title {
-}
-
-.subtitle {
-    border: none;
-}
-
-/*
-h1 {
-  border: none;
-}
-
-h2 {
-  border-top: solid 0.2em;
-  border-bottom: solid 0.06em;
-}
-
-h3 {
-  border-top: 0em;
-  border-bottom: solid 0.06em;
-}
-
-h4 {
-  border: 0em;
-  border-bottom: solid 0.06em;
-}
-
-h5 {
-  border: 0em;
-}
-*/
-
-.programlisting {
-  border: solid 1px;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example {
-  border: 1px solid;
-}
-
-
-
-.tip,
-.warning,
-.caution,
-.note {
-  border: 1px solid;
-}
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  border-bottom: 1px solid;
-}
-
-.question td {
-  border-top: 1px solid black;
-}
-
-.answer {
-}
-
-
-b.keycap,
-.keycap {
-  border: 1px solid;
-}
-
-
-div.navheader, div.heading{
-  border-bottom: 1px solid;
-}
-
-
-div.navfooter, div.footing{
-  border-top: 1px solid;
-}
-
-  /********* /
- /  colors  /
-/ *********/
-
-body {
-  color: #333;
-  background: white;
-}
-
-a {
-  background: transparent;
-}
-
-a:hover {
-  background-color: #dedede;
-}
-
-
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7,
-h8 {
-  background-color: transparent;
-}
-
-hr {
-  border-color: #aaa;
-}
-
-
-.tip, .warning, .caution, .note {
-  border-color: #fff;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  border-bottom-color: #fff;
-}
-
-
-.warning {
-  background-color: #f0f0f2;
-}
-
-.caution {
-  background-color: #f0f0f2;
-}
-
-.tip {
-  background-color: #f0f0f2;
-}
-
-.note {
-  background-color: #f0f0f2;
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
-  color: #044;
-}
-
-div.figure,
-div.table,
-div.example,
-div.informalfigure,
-div.informaltable,
-div.informalexample {
-  border-color: #aaa;
-}
-
-pre.programlisting {
-  color: black;
-  background-color: #fff;
-  border-color: #aaa;
-  border-width: 2px;
-}
-
-.guimenu,
-.guilabel,
-.guimenuitem {
-  background-color: #eee;
-}
-
-
-b.keycap,
-.keycap {
-  background-color: #eee;
-  border-color: #999;
-}
-
-
-div.navheader {
-  border-color: black;
-}
-
-
-div.navfooter {
-  border-color: black;
-}
-
-
-.writernotes {
-  color: red;
-}
-
-
-  /*********** /
- /  graphics  /
-/ ***********/
-
-/*
-body {
-  background-image: url("images/body_bg.jpg");
-  background-attachment: fixed;
-}
-
-.navheader,
-.note,
-.tip {
-  background-image: url("images/note_bg.jpg");
-  background-attachment: fixed;
-}
-
-.warning,
-.caution {
-  background-image: url("images/warning_bg.jpg");
-  background-attachment: fixed;
-}
-
-.figure,
-.informalfigure,
-.example,
-.informalexample,
-.table,
-.informaltable {
-  background-image: url("images/figure_bg.jpg");
-  background-attachment: fixed;
-}
-
-*/
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7{
-}
-
-/*
-Example of how to stick an image as part of the title.
-
-div.article .titlepage .title
-{
-  background-image: url("figures/white-on-black.png");
-  background-position: center;
-  background-repeat: repeat-x;
-}
-*/
-
-div.preface .titlepage .title,
-div.colophon .title,
-div.chapter .titlepage .title {
-  background-position: bottom;
-  background-repeat: repeat-x;
-}
-
-div.section div.section .titlepage .title,
-div.sect2 .titlepage .title {
-    background: none;
-}
-
-
-h1.title {
-  background-color: transparent;
-  background-repeat: no-repeat;
-  height: 256px;
-  text-indent: -9000px;
-  overflow:hidden;
-}
-
-h2.subtitle {
-  background-color: transparent;
-  text-indent: -9000px;
-  overflow:hidden;
-  width: 0px;
-  display: none;
-}
-
-  /*************************************** /
- /  pippin.gimp.org specific alterations  /
-/ ***************************************/
-
-/*
-div.heading, div.navheader {
-  color: #777;
-  font-size: 80%;
-  padding: 0;
-  margin: 0;
-  text-align: left;
-  position: absolute;
-  top: 0px;
-  left: 0px;
-  width: 100%;
-  height: 50px;
-  background: url('/gfx/heading_bg.png') transparent;
-  background-repeat: repeat-x;
-  background-attachment: fixed;
-  border: none;
-}
-
-div.heading a {
-  color: #444;
-}
-
-div.footing, div.navfooter {
-  border: none;
-  color: #ddd;
-  font-size: 80%;
-  text-align:right;
-
-  width: 100%;
-  padding-top: 10px;
-  position: absolute;
-  bottom: 0px;
-  left: 0px;
-
-  background: url('/gfx/footing_bg.png') transparent;
-}
-*/
-
-
-
-  /****************** /
- /  nasty ie tweaks  /
-/ ******************/
-
-/*
-div.heading, div.navheader {
-  width:expression(document.body.clientWidth + "px");
-}
-
-div.footing, div.navfooter {
-  width:expression(document.body.clientWidth + "px");
-  margin-left:expression("-5em");
-}
-body {
-  padding:expression("4em 5em 0em 5em");
-}
-*/
-
-  /**************************************** /
- / mozilla vendor specific css extensions  /
-/ ****************************************/
-/*
-div.navfooter, div.footing{
-  -moz-opacity: 0.8em;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example,
-.tip,
-.warning,
-.caution,
-.note {
-  -moz-border-radius: 0.5em;
-}
-
-b.keycap,
-.keycap {
-  -moz-border-radius: 0.3em;
-}
-*/
-
-table tr td table tr td {
-  display: none;
-}
-
-
-hr {
-  display: none;
-}
-
-table {
-  border: 0em;
-}
-
- .photo {
-  float: right;
-  margin-left:   1.5em;
-  margin-bottom: 1.5em;
-  margin-top: 0em;
-  max-width:      17em;
-  border:     1px solid gray;
-  padding:    3px;
-  background: white;
-}
- .seperator {
-   padding-top: 2em;
-   clear: both;
-  }
-
-  #validators {
-      margin-top: 5em;
-      text-align: right;
-      color: #777;
-  }
-  @media print {
-      body {
-          font-size: 8pt;
-      }
-      .noprint {
-          display: none;
-      }
-  }
-
-
-.tip,
-.note {
-   background: #f0f0f2;
-   color: #333;
-   padding: 20px;
-   margin: 20px;
-}
-
-.tip h3,
-.note h3 {
-   padding: 0em;
-   margin: 0em;
-   font-size: 2em;
-   font-weight: bold;
-   color: #333;
-}
-
-.tip a,
-.note a {
-   color: #333;
-   text-decoration: underline;
-}
-
-.footnote {
-   font-size: small;
-   color: #333;
-}
-
-/* Changes the announcement text */
-.tip h3,
-.warning h3,
-.caution h3,
-.note h3 {
-   font-size:large;
-   color: #00557D;
-}

documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.rst

@@ -0,0 +1,430 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+=========================
+Yocto Project Quick Build
+=========================
+
+Welcome!
+========
+
+This short document steps you through the process for a typical
+image build using the Yocto Project. The document also introduces how to
+configure a build for specific hardware. You will use Yocto Project to
+build a reference embedded OS called Poky.
+
+.. note::
+
+   -  The examples in this paper assume you are using a native Linux
+      system running a recent Ubuntu Linux distribution. If the machine
+      you want to use Yocto Project on to build an image
+      (:term:`Build Host`) is not
+      a native Linux system, you can still perform these steps by using
+      CROss PlatformS (CROPS) and setting up a Poky container. See the
+      :ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)`
+      section
+      in the Yocto Project Development Tasks Manual for more
+      information.
+
+   -  You may use Windows Subsystem For Linux v2 to set up a build host
+      using Windows 10.
+
+      .. note::
+
+         The Yocto Project is not compatible with WSLv1, it is
+         compatible but not officially supported nor validated with
+         WSLv2, if you still decide to use WSL please upgrade to WSLv2.
+
+      See the :ref:`dev-manual/dev-manual-start:setting up to use windows
+      subsystem for linux (wslv2)` section in the Yocto Project Development
+      Tasks Manual for more information.
+
+If you want more conceptual or background information on the Yocto
+Project, see the :doc:`../overview-manual/overview-manual`.
+
+Compatible Linux Distribution
+=============================
+
+Make sure your :term:`Build Host` meets the
+following requirements:
+
+-  50 Gbytes of free disk space
+
+-  Runs a supported Linux distribution (i.e. recent releases of Fedora,
+   openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux
+   distributions that support the Yocto Project, see the
+   :ref:`ref-manual/ref-system-requirements:supported linux distributions`
+   section in the Yocto Project Reference Manual. For detailed
+   information on preparing your build host, see the
+   :ref:`dev-manual/dev-manual-start:preparing the build host`
+   section in the Yocto Project Development Tasks Manual.
+
+-
+
+   -  Git 1.8.3.1 or greater
+   -  tar 1.28 or greater
+   -  Python 3.5.0 or greater.
+   -  gcc 5.0 or greater.
+
+If your build host does not meet any of these three listed version
+requirements, you can take steps to prepare the system so that you
+can still use the Yocto Project. See the
+:ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions`
+section in the Yocto Project Reference Manual for information.
+
+Build Host Packages
+===================
+
+You must install essential host packages on your build host. The
+following command installs the host packages based on an Ubuntu
+distribution:
+
+.. code-block:: shell
+
+  $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
+
+.. note::
+
+   For host package requirements on all supported Linux distributions,
+   see the :ref:`ref-manual/ref-system-requirements:required packages for the build host`
+   section in the Yocto Project Reference Manual.
+
+Use Git to Clone Poky
+=====================
+
+Once you complete the setup instructions for your machine, you need to
+get a copy of the Poky repository on your build host. Use the following
+commands to clone the Poky repository.
+
+.. code-block:: shell
+
+   $ git clone git://git.yoctoproject.org/poky
+   Cloning into 'poky'...
+   remote: Counting
+   objects: 432160, done. remote: Compressing objects: 100%
+   (102056/102056), done. remote: Total 432160 (delta 323116), reused
+   432037 (delta 323000) Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
+   Resolving deltas: 100% (323116/323116), done.
+   Checking connectivity... done.
+
+Move to the ``poky`` directory and take a look at the tags:
+
+.. code-block:: shell
+
+   $ cd poky
+   $ git fetch --tags
+   $ git tag
+   1.1_M1.final
+   1.1_M1.rc1
+   1.1_M1.rc2
+   1.1_M2.final
+   1.1_M2.rc1
+   .
+   .
+   .
+   yocto-2.5
+   yocto-2.5.1
+   yocto-2.5.2
+   yocto-2.6
+   yocto-2.6.1
+   yocto-2.6.2
+   yocto-2.7
+   yocto_1.5_M5.rc8
+
+For this example, check out the branch based on the
+``&DISTRO_REL_TAG;`` release:
+
+.. code-block:: shell
+
+   $ git checkout tags/&DISTRO_REL_TAG; -b my-&DISTRO_REL_TAG;
+   Switched to a new branch 'my-&DISTRO_REL_TAG;'
+
+The previous Git checkout command creates a local branch named
+``my-&DISTRO_REL_TAG;``. The files available to you in that branch exactly
+match the repository's files in the ``&DISTRO_NAME_NO_CAP;`` development
+branch at the time of the Yocto Project &DISTRO_REL_TAG; release.
+
+For more options and information about accessing Yocto Project related
+repositories, see the
+:ref:`dev-manual/dev-manual-start:locating yocto project source files`
+section in the Yocto Project Development Tasks Manual.
+
+Building Your Image
+===================
+
+Use the following steps to build your image. The build process creates
+an entire Linux distribution, including the toolchain, from source.
+
+.. note::
+
+   -  If you are working behind a firewall and your build host is not
+      set up for proxies, you could encounter problems with the build
+      process when fetching source code (e.g. fetcher failures or Git
+      failures).
+
+   -  If you do not know your proxy settings, consult your local network
+      infrastructure resources and get that information. A good starting
+      point could also be to check your web browser settings. Finally,
+      you can find more information on the
+      ":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`"
+      page of the Yocto Project Wiki.
+
+#. **Initialize the Build Environment:** From within the ``poky``
+   directory, run the :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\``
+   environment
+   setup script to define Yocto Project's build environment on your
+   build host.
+
+   .. code-block:: shell
+
+      $ cd ~/poky
+      $ source oe-init-build-env
+      You had no conf/local.conf file. This configuration file has therefore been
+      created for you with some default values. You may wish to edit it to, for
+      example, select a different MACHINE (target hardware). See conf/local.conf
+      for more information as common configuration options are commented.
+
+      You had no conf/bblayers.conf file. This configuration file has therefore
+      been created for you with some default values. To add additional metadata
+      layers into your configuration please add entries to conf/bblayers.conf.
+
+      The Yocto Project has extensive documentation about OE including a reference
+      manual which can be found at:
+          http://yoctoproject.org/documentation
+
+      For more information about OpenEmbedded see their website:
+          http://www.openembedded.org/
+
+      ### Shell environment set up for builds. ###
+
+      You can now run 'bitbake <target>'
+
+      Common targets are:
+          core-image-minimal
+          core-image-sato
+          meta-toolchain
+          meta-ide-support
+
+      You can also run generated qemu images with a command like 'runqemu qemux86-64'
+
+   Among other things, the script creates the :term:`Build Directory`, which is
+   ``build`` in this case and is located in the :term:`Source Directory`.  After
+   the script runs, your current working directory is set to the Build
+   Directory. Later, when the build completes, the Build Directory contains all the
+   files created during the build.
+
+#. **Examine Your Local Configuration File:** When you set up the build
+   environment, a local configuration file named ``local.conf`` becomes
+   available in a ``conf`` subdirectory of the Build Directory. For this
+   example, the defaults are set to build for a ``qemux86`` target,
+   which is suitable for emulation. The package manager used is set to
+   the RPM package manager.
+
+   .. tip::
+
+      You can significantly speed up your build and guard against fetcher
+      failures by using mirrors. To use mirrors, add these lines to your
+      local.conf file in the Build directory: ::
+
+         SSTATE_MIRRORS = "\
+         file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \
+         file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \
+         file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \
+         "
+
+
+      The previous examples showed how to add sstate paths for Yocto Project
+      &YOCTO_DOC_VERSION_MINUS_ONE;, &YOCTO_DOC_VERSION;, and a development
+      area. For a complete index of sstate locations, see http://sstate.yoctoproject.org/.
+
+#. **Start the Build:** Continue with the following command to build an OS
+   image for the target, which is ``core-image-sato`` in this example:
+
+   .. code-block:: shell
+
+      $ bitbake core-image-sato
+
+   For information on using the ``bitbake`` command, see the
+   :ref:`usingpoky-components-bitbake` section in the Yocto Project Overview and
+   Concepts Manual, or see the ":ref:`BitBake Command
+   <bitbake:bitbake-user-manual-command>`" section in the BitBake User Manual.
+
+#. **Simulate Your Image Using QEMU:** Once this particular image is
+   built, you can start QEMU, which is a Quick EMUlator that ships with
+   the Yocto Project:
+
+   .. code-block:: shell
+
+      $ runqemu qemux86-64
+
+   If you want to learn more about running QEMU, see the
+   :ref:`dev-manual/dev-manual-qemu:using the quick emulator (qemu)` chapter in
+   the Yocto Project Development Tasks Manual.
+
+#. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing
+   ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU.
+
+Customizing Your Build for Specific Hardware
+============================================
+
+So far, all you have done is quickly built an image suitable for
+emulation only. This section shows you how to customize your build for
+specific hardware by adding a hardware layer into the Yocto Project
+development environment.
+
+In general, layers are repositories that contain related sets of
+instructions and configurations that tell the Yocto Project what to do.
+Isolating related metadata into functionally specific layers facilitates
+modular development and makes it easier to reuse the layer metadata.
+
+.. note::
+
+   By convention, layer names start with the string "meta-".
+
+Follow these steps to add a hardware layer:
+
+#. **Find a Layer:** Lots of hardware layers exist. The Yocto Project
+   :yocto_git:`Source Repositories <>` has many hardware layers.
+   This example adds the
+   `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer.
+
+#. **Clone the Layer:** Use Git to make a local copy of the layer on your
+   machine. You can put the copy in the top level of the copy of the
+   Poky repository created earlier:
+
+   .. code-block:: shell
+
+      $ cd ~/poky
+      $ git clone https://github.com/kraj/meta-altera.git
+      Cloning into 'meta-altera'...
+      remote: Counting objects: 25170, done.
+      remote: Compressing objects: 100% (350/350), done.
+      remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219
+      Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done.
+      Resolving deltas: 100% (13385/13385), done.
+      Checking connectivity... done.
+
+   The hardware layer now exists
+   with other layers inside the Poky reference repository on your build
+   host as ``meta-altera`` and contains all the metadata needed to
+   support hardware from Altera, which is owned by Intel.
+
+   .. note::
+
+      It is recommended for layers to have a branch per Yocto Project release.
+      Please make sure to checkout the layer branch supporting the Yocto Project
+      release you're using.
+
+#. **Change the Configuration to Build for a Specific Machine:** The
+   :term:`MACHINE` variable in the
+   ``local.conf`` file specifies the machine for the build. For this
+   example, set the ``MACHINE`` variable to ``cyclone5``. These
+   configurations are used:
+   https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf.
+
+   .. note::
+
+      See the "Examine Your Local Configuration File" step earlier for more
+      information on configuring the build.
+
+#. **Add Your Layer to the Layer Configuration File:** Before you can use
+   a layer during a build, you must add it to your ``bblayers.conf``
+   file, which is found in the
+   :term:`Build Directory` ``conf``
+   directory.
+
+   Use the ``bitbake-layers add-layer`` command to add the layer to the
+   configuration file:
+
+   .. code-block:: shell
+
+      $ cd ~/poky/build
+      $ bitbake-layers add-layer ../meta-altera
+      NOTE: Starting bitbake server...
+      Parsing recipes: 100% |##################################################################| Time: 0:00:32
+      Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets,
+      123 skipped, 0 masked, 0 errors.
+
+   You can find
+   more information on adding layers in the
+   :ref:`dev-manual/dev-manual-common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`
+   section.
+
+Completing these steps has added the ``meta-altera`` layer to your Yocto
+Project development environment and configured it to build for the
+``cyclone5`` machine.
+
+.. note::
+
+   The previous steps are for demonstration purposes only. If you were
+   to attempt to build an image for the ``cyclone5`` machine, you should
+   read the Altera ``README``.
+
+Creating Your Own General Layer
+===============================
+
+Maybe you have an application or specific set of behaviors you need to
+isolate. You can create your own general layer using the
+``bitbake-layers create-layer`` command. The tool automates layer
+creation by setting up a subdirectory with a ``layer.conf``
+configuration file, a ``recipes-example`` subdirectory that contains an
+``example.bb`` recipe, a licensing file, and a ``README``.
+
+The following commands run the tool to create a layer named
+``meta-mylayer`` in the ``poky`` directory:
+
+.. code-block:: shell
+
+   $ cd ~/poky
+   $ bitbake-layers create-layer meta-mylayer
+   NOTE: Starting bitbake server...
+   Add your new layer with 'bitbake-layers add-layer meta-mylayer'
+
+For more information
+on layers and how to create them, see the
+:ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`
+section in the Yocto Project Development Tasks Manual.
+
+Where To Go Next
+================
+
+Now that you have experienced using the Yocto Project, you might be
+asking yourself "What now?". The Yocto Project has many sources of
+information including the website, wiki pages, and user manuals:
+
+-  **Website:** The :yocto_home:`Yocto Project Website <>` provides
+   background information, the latest builds, breaking news, full
+   development documentation, and access to a rich Yocto Project
+   Development Community into which you can tap.
+
+-  **Developer Screencast:** The `Getting Started with the Yocto Project -
+   New Developer Screencast Tutorial <http://vimeo.com/36450321>`__
+   provides a 30-minute video created for users unfamiliar with the
+   Yocto Project but familiar with Linux build hosts. While this
+   screencast is somewhat dated, the introductory and fundamental
+   concepts are useful for the beginner.
+
+-  **Yocto Project Overview and Concepts Manual:** The
+   :doc:`../overview-manual/overview-manual` is a great
+   place to start to learn about the Yocto Project. This manual
+   introduces you to the Yocto Project and its development environment.
+   The manual also provides conceptual information for various aspects
+   of the Yocto Project.
+
+-  **Yocto Project Wiki:** The :yocto_wiki:`Yocto Project Wiki <>`
+   provides additional information on where to go next when ramping up
+   with the Yocto Project, release information, project planning, and QA
+   information.
+
+-  **Yocto Project Mailing Lists:** Related mailing lists provide a forum
+   for discussion, patch submission and announcements. Several mailing
+   lists exist and are grouped according to areas of concern. See the
+   :ref:`ref-manual/resources:mailing lists`
+   section in the Yocto Project Reference Manual for a complete list of
+   Yocto Project mailing lists.
+
+-  **Comprehensive List of Links and Other Documentation:** The
+   :ref:`ref-manual/resources:links and related documentation`
+   section in the Yocto Project Reference Manual provides a
+   comprehensive list of all related links and other user documentation.
+
+.. include:: /boilerplate.rst

documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml

@@ -1,576 +0,0 @@
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<article id='brief-yocto-project-qs-intro'>
-    <articleinfo>
-        <title>Yocto Project Quick Build</title>
-
-        <copyright>
-            <year>&COPYRIGHT_YEAR;</year>
-            <holder>Linux Foundation</holder>
-        </copyright>
-
-        <legalnotice>
-            <para>
-                Permission is granted to copy, distribute and/or modify this document under
-                the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
-            </para>
-        </legalnotice>
-
-
-        <abstract>
-            <imagedata fileref="figures/yocto-project-transp.png"
-                        width="6in" depth="1in"
-                        align="right" scale="25" />
-        </abstract>
-    </articleinfo>
-
-    <section id='brief-welcome'>
-        <title>Welcome!</title>
-
-        <para>
-            Welcome!
-            This short document steps you through the process for a typical
-            image build using the Yocto Project.
-            The document also introduces how to configure a build for specific
-            hardware.
-            You will use Yocto Project to build a reference embedded OS
-            called Poky.
-            <note><title>Notes</title>
-                <itemizedlist>
-                    <listitem><para>
-                        The examples in this paper assume you are using a
-                        native Linux system running a recent Ubuntu Linux
-                        distribution.
-                        If the machine you want to use Yocto Project on to
-                        build an image
-                        (<ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>)
-                        is not a native Linux system, you can
-                        still perform these steps by using CROss PlatformS
-                        (CROPS) and setting up a Poky container.
-                        See the
-                        <ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
-                        section in the Yocto Project Development Tasks Manual for more
-                        information.
-                        </para></listitem>
-                    <listitem><para>
-                        You may use Windows Subsystem For Linux v2 to set up a build
-                        host using Windows 10.
-                        <note>
-                          The Yocto Project is not compatible with WSLv1, it is
-                          compatible but not officially supported nor validated
-                          with WSLv2, if you still decide to use WSL please upgrade
-                          to WSLv2.
-                        </note>
-                        See the
-                        <ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-wsl'>Setting Up to Use Windows Subsystem For Linux</ulink>"
-                        section in the Yocto Project Development Tasks Manual for more
-                        information.
-                        </para></listitem>
-                </itemizedlist>
-            </note>
-        </para>
-
-        <para>
-            If you want more conceptual or background information on the
-            Yocto Project, see the
-            <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
-        </para>
-    </section>
-
-    <section id='brief-compatible-distro'>
-        <title>Compatible Linux Distribution</title>
-
-        <para>
-            Make sure your
-            <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
-            meets the following requirements:
-            <itemizedlist>
-                <listitem><para>
-                    50 Gbytes of free disk space
-                    </para></listitem>
-                <listitem><para>
-                    Runs a supported Linux distribution (i.e. recent releases of
-                    Fedora, openSUSE, CentOS, Debian, or Ubuntu). For a list of
-                    Linux distributions that support the Yocto Project, see the
-                    "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
-                    section in the Yocto Project Reference Manual.
-                    For detailed information on preparing your build host, see
-                    the
-                    "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
-                    section in the Yocto Project Development Tasks Manual.
-                    </para></listitem>
-                <listitem><para>
-                    <itemizedlist>
-                        <listitem><para>
-                            Git 1.8.3.1 or greater
-                            </para></listitem>
-                        <listitem><para>
-                            tar 1.28 or greater
-                            </para></listitem>
-                        <listitem><para>
-                            Python 3.5.0 or greater.
-                        </para></listitem>
-                        <listitem><para>
-                            gcc 5.0 or greater.
-                        </para></listitem>
-                    </itemizedlist>
-                    If your build host does not meet any of these three listed
-                    version requirements, you can take steps to prepare the
-                    system so that you can still use the Yocto Project.
-                    See the
-                    "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</ulink>"
-                    section in the Yocto Project Reference Manual for information.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-
-    <section id='brief-build-system-packages'>
-        <title>Build Host Packages</title>
-
-        <para>
-            You must install essential host packages on your
-            build host.
-            The following command installs the host packages based on an
-            Ubuntu distribution:
-            <note>
-                For host package requirements on all supported Linux
-                distributions, see the
-                "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host'>Required Packages for the Build Host</ulink>"
-                section in the Yocto Project Reference Manual.
-            </note>
-            <literallayout class='monospaced'>
-     $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
-            </literallayout>
-        </para>
-    </section>
-
-    <section id='brief-use-git-to-clone-poky'>
-        <title>Use Git to Clone Poky</title>
-
-        <para>
-            Once you complete the setup instructions for your machine,
-            you need to get a copy of the Poky repository on your build
-            host.
-            Use the following commands to clone the Poky
-            repository.
-            <literallayout class='monospaced'>
-     $ git clone git://git.yoctoproject.org/poky
-     Cloning into 'poky'...
-     remote: Counting objects: 432160, done.
-     remote: Compressing objects: 100% (102056/102056), done.
-     remote: Total 432160 (delta 323116), reused 432037 (delta 323000)
-     Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
-     Resolving deltas: 100% (323116/323116), done.
-     Checking connectivity... done.
-            </literallayout>
-            Move to the <filename>poky</filename> directory and take a look
-            at the tags:
-            <literallayout class='monospaced'>
-     $ cd poky
-     $ git fetch --tags
-     $ git tag
-     1.1_M1.final
-     1.1_M1.rc1
-     1.1_M1.rc2
-     1.1_M2.final
-     1.1_M2.rc1
-        .
-        .
-        .
-     yocto-2.5
-     yocto-2.5.1
-     yocto-2.5.2
-     yocto-2.6
-     yocto-2.6.1
-     yocto-2.6.2
-     yocto-2.7
-     yocto_1.5_M5.rc8
-            </literallayout>
-            For this example, check out the branch based on the
-            &DISTRO_REL_TAG; release:
-            <literallayout class='monospaced'>
-     $ git checkout tags/&DISTRO_REL_TAG; -b my-&DISTRO_REL_TAG;
-     Switched to a new branch 'my-&DISTRO_REL_TAG;'
-            </literallayout>
-            The previous Git checkout command creates a local branch
-            named my-&DISTRO_REL_TAG;. The files available to you in that
-            branch exactly match the repository's files in the
-            "&DISTRO_NAME_NO_CAP;" development branch at the time of the
-            Yocto Project &DISTRO_REL_TAG; release.
-        </para>
-
-        <para>
-            For more options and information about accessing Yocto
-            Project related repositories, see the
-            "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
-            section in the Yocto Project Development Tasks Manual.
-        </para>
-    </section>
-
-    <section id='brief-building-your-image'>
-        <title>Building Your Image</title>
-
-        <para>
-            Use the following steps to build your image.
-            The build process creates an entire Linux distribution, including
-            the toolchain, from source.
-            <note>
-                <itemizedlist>
-                    <listitem><para>
-                        If you are working behind a firewall and your build
-                        host is not set up for proxies, you could encounter
-                        problems with the build process when fetching source
-                        code (e.g. fetcher failures or Git failures).
-                        </para></listitem>
-                    <listitem><para>
-                        If you do not know your proxy settings, consult your
-                        local network infrastructure resources and get that
-                        information.
-                        A good starting point could also be to check your
-                        web browser settings.
-                        Finally, you can find more information on the
-                        "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
-                        page of the Yocto Project Wiki.
-                        </para></listitem>
-                </itemizedlist>
-            </note>
-        </para>
-
-        <para>
-            <orderedlist>
-                <listitem><para>
-                    <emphasis>Initialize the Build Environment:</emphasis>
-                    From within the <filename>poky</filename> directory, run the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
-                    environment setup script to define Yocto Project's
-                    build environment on your build host.
-                    <literallayout class='monospaced'>
-     $ cd ~/poky
-     $ source &OE_INIT_FILE;
-     You had no conf/local.conf file. This configuration file has therefore been
-     created for you with some default values. You may wish to edit it to, for
-     example, select a different MACHINE (target hardware). See conf/local.conf
-     for more information as common configuration options are commented.
-
-     You had no conf/bblayers.conf file. This configuration file has therefore been
-     created for you with some default values. To add additional metadata layers
-     into your configuration please add entries to conf/bblayers.conf.
-
-     The Yocto Project has extensive documentation about OE including a reference
-     manual which can be found at:
-         http://yoctoproject.org/documentation
-
-     For more information about OpenEmbedded see their website:
-         http://www.openembedded.org/
-
-
-     ### Shell environment set up for builds. ###
-
-     You can now run 'bitbake &lt;target&gt;'
-
-     Common targets are:
-         core-image-minimal
-         core-image-sato
-         meta-toolchain
-         meta-ide-support
-
-     You can also run generated qemu images with a command like 'runqemu qemux86-64'
-                    </literallayout>
-                    Among other things, the script creates the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
-                    which is <filename>build</filename> in this case
-                    and is located in the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
-                    After the script runs, your current working directory
-                    is set to the Build Directory.
-                    Later, when the build completes, the Build Directory
-                    contains all the files created during the build.
-                    </para></listitem>
-                <listitem><para id='conf-file-step'>
-                    <emphasis>Examine Your Local Configuration File:</emphasis>
-                    When you set up the build environment, a local
-                    configuration file named
-                    <filename>local.conf</filename> becomes available in
-                    a <filename>conf</filename> subdirectory of the
-                    Build Directory.
-                    For this example, the defaults are set to build
-                    for a <filename>qemux86</filename> target, which is
-                    suitable for emulation.
-                    The package manager used is set to the RPM package
-                    manager.
-                    <tip>
-                        You can significantly speed up your build and guard
-                        against fetcher failures by using mirrors.
-                        To use mirrors, add these lines to your
-                        <filename>local.conf</filename> file in the Build
-                        directory:
-                        <literallayout class='monospaced'>
-     SSTATE_MIRRORS = "\
-     file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \
-     file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \
-     file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \
-     "
-                        </literallayout>
-                        The previous examples showed how to add sstate
-                        paths for Yocto Project &YOCTO_DOC_VERSION_MINUS_ONE;,
-                        &YOCTO_DOC_VERSION;, and a development area.
-                        For a complete index of sstate locations, see
-                        <ulink url='http://sstate.yoctoproject.org/'></ulink>.
-                    </tip>
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Start the Build:</emphasis>
-                    Continue with the following command to build an OS image
-                    for the target, which is
-                    <filename>core-image-sato</filename> in this example:
-                    <literallayout class='monospaced'>
-     $ bitbake core-image-sato
-                    </literallayout>
-                    For information on using the
-                    <filename>bitbake</filename> command, see the
-                    "<ulink url='&YOCTO_DOCS_OM_URL;#usingpoky-components-bitbake'>BitBake</ulink>"
-                    section in the Yocto Project Overview and Concepts Manual,
-                    or see the
-                    "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>"
-                    section in the BitBake User Manual.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Simulate Your Image Using QEMU:</emphasis>
-                    Once this particular image is built, you can start
-                    QEMU, which is a Quick EMUlator that ships with
-                    the Yocto Project:
-                    <literallayout class='monospaced'>
-     $ runqemu qemux86-64
-                    </literallayout>
-                    If you want to learn more about running QEMU, see the
-                    "<ulink url="&YOCTO_DOCS_DEV_URL;#dev-manual-qemu">Using the Quick EMUlator (QEMU)</ulink>"
-                    chapter in the Yocto Project Development Tasks Manual.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Exit QEMU:</emphasis>
-                    Exit QEMU by either clicking on the shutdown icon or by
-                    typing <filename>Ctrl-C</filename> in the QEMU
-                    transcript window from which you evoked QEMU.
-                    </para></listitem>
-            </orderedlist>
-        </para>
-    </section>
-
-    <section id='customizing-your-build-for-specific-hardware'>
-        <title>Customizing Your Build for Specific Hardware</title>
-
-        <para>
-            So far, all you have done is quickly built an image suitable
-            for emulation only.
-            This section shows you how to customize your build for specific
-            hardware by adding a hardware layer into the Yocto Project
-            development environment.
-        </para>
-
-        <para>
-            In general, layers are repositories that contain related sets of
-            instructions and configurations that tell the Yocto Project what
-            to do.
-            Isolating related metadata into functionally specific layers
-            facilitates modular development and makes it easier to reuse the
-            layer metadata.
-            <note>
-                By convention, layer names start with the string "meta-".
-            </note>
-        </para>
-
-        <para>
-            Follow these steps to add a hardware layer:
-            <orderedlist>
-                <listitem><para>
-                    <emphasis>Find a Layer:</emphasis>
-                    Lots of hardware layers exist.
-                    The Yocto Project
-                    <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
-                    has many hardware layers.
-                    This example adds the
-                    <ulink url='https://github.com/kraj/meta-altera'>meta-altera</ulink>
-                    hardware layer.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Clone the Layer</emphasis>
-                    Use Git to make a local copy of the layer on your machine.
-                    You can put the copy in the top level of the copy of the
-                    Poky repository created earlier:
-                    <literallayout class='monospaced'>
-     $ cd ~/poky
-     $ git clone https://github.com/kraj/meta-altera.git
-     Cloning into 'meta-altera'...
-     remote: Counting objects: 25170, done.
-     remote: Compressing objects: 100% (350/350), done.
-     remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219
-     Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done.
-     Resolving deltas: 100% (13385/13385), done.
-     Checking connectivity... done.
-                    </literallayout>
-                    The hardware layer now exists with other layers inside
-                    the Poky reference repository on your build host as
-                    <filename>meta-altera</filename> and contains all the
-                    metadata needed to support hardware from Altera, which
-                    is owned by Intel.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Change the Configuration to Build for a Specific Machine:</emphasis>
-                    The
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
-                    variable in the <filename>local.conf</filename> file
-                    specifies the machine for the build.
-                    For this example, set the <filename>MACHINE</filename>
-                    variable to "cyclone5".
-                    These configurations are used:
-                    <ulink url='https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf'></ulink>.
-                    <note>
-                        See the
-                        "<link linkend='conf-file-step'>Examine Your Local Configuration File</link>"
-                        step earlier for more information on configuring the
-                        build.
-                    </note>
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Add Your Layer to the Layer Configuration File:</emphasis>
-                    Before you can use a layer during a build, you must add it
-                    to your <filename>bblayers.conf</filename> file, which
-                    is found in the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink>
-                    <filename>conf</filename> directory.</para>
-
-                    <para>Use the <filename>bitbake-layers add-layer</filename>
-                    command to add the layer to the configuration file:
-                    <literallayout class='monospaced'>
-     $ cd ~/poky/build
-     $ bitbake-layers add-layer ../meta-altera
-     NOTE: Starting bitbake server...
-     Parsing recipes: 100% |##################################################################| Time: 0:00:32
-     Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets, 123 skipped, 0 masked, 0 errors.
-                    </literallayout>
-                    You can find more information on adding layers in the
-                    "<ulink url='&YOCTO_DOCS_DEV_URL;#adding-a-layer-using-the-bitbake-layers-script'>Adding a Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
-                    section.
-                    </para></listitem>
-            </orderedlist>
-            Completing these steps has added the
-            <filename>meta-altera</filename> layer to your Yocto Project
-            development environment and configured it to build for the
-            "cyclone5" machine.
-            <note>
-                The previous steps are for demonstration purposes only.
-                If you were to attempt to build an image for the
-                "cyclone5" build, you should read the Altera
-                <filename>README</filename>.
-            </note>
-        </para>
-    </section>
-
-    <section id='creating-your-own-general-layer'>
-        <title>Creating Your Own General Layer</title>
-
-        <para>
-            Maybe you have an application or specific set of behaviors you
-            need to isolate.
-            You can create your own general layer using the
-            <filename>bitbake-layers create-layer</filename> command.
-            The tool automates layer creation by setting up a
-            subdirectory with a <filename>layer.conf</filename>
-            configuration file, a <filename>recipes-example</filename>
-            subdirectory that contains an <filename>example.bb</filename>
-            recipe, a licensing file, and a <filename>README</filename>.
-        </para>
-
-        <para>
-            The following commands run the tool to create a layer named
-            <filename>meta-mylayer</filename> in the
-            <filename>poky</filename> directory:
-            <literallayout class='monospaced'>
-     $ cd ~/poky
-     $ bitbake-layers create-layer meta-mylayer
-     NOTE: Starting bitbake server...
-     Add your new layer with 'bitbake-layers add-layer meta-mylayer'
-            </literallayout>
-            For more information on layers and how to create them, see the
-            "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
-            section in the Yocto Project Development Tasks Manual.
-        </para>
-    </section>
-
-    <section id='brief-where-to-go-next'>
-        <title>Where To Go Next</title>
-
-        <para>
-            Now that you have experienced using the Yocto Project, you might
-            be asking yourself "What now?"
-            The Yocto Project has many sources of information including
-            the website, wiki pages, and user manuals:
-            <itemizedlist>
-                <listitem><para>
-                    <emphasis>Website:</emphasis>
-                    The
-                    <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
-                    provides background information, the latest builds,
-                    breaking news, full development documentation, and
-                    access to a rich Yocto Project Development Community
-                    into which you can tap.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Developer Screencast:</emphasis>
-                    The
-                    <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New Developer Screencast Tutorial</ulink>
-                    provides a 30-minute video created for users unfamiliar
-                    with the Yocto Project but familiar with Linux build
-                    hosts.
-                    While this screencast is somewhat dated, the
-                    introductory and fundamental concepts are useful for
-                    the beginner.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Yocto Project Overview and Concepts Manual:</emphasis>
-                    The
-                    <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>
-                    is a great place to start to learn about the
-                    Yocto Project.
-                    This manual introduces you to the Yocto Project and its
-                    development environment.
-                    The manual also provides conceptual information for
-                    various aspects of the Yocto Project.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Yocto Project Wiki:</emphasis>
-                    The
-                    <ulink url='&YOCTO_WIKI_URL;'>Yocto Project Wiki</ulink>
-                    provides additional information on where to go next
-                    when ramping up with the Yocto Project, release
-                    information, project planning, and QA information.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Yocto Project Mailing Lists:</emphasis>
-                    Related mailing lists provide a forum for discussion,
-                    patch submission and announcements.
-                    Several mailing lists exist and are grouped according
-                    to areas of concern.
-                    See the
-                    "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
-                    section in the Yocto Project Reference Manual for a
-                    complete list of Yocto Project mailing lists.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Comprehensive List of Links and Other Documentation:</emphasis>
-                    The
-                    "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"
-                    section in the Yocto Project Reference Manual provides a
-                    comprehensive list of all related links and other
-                    user documentation.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-</article>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/bsp-guide/bsp-guide-customization.xsl

@@ -1,27 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
-
-  <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-<!--
-
-  <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-  <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
-
--->
-
-  <xsl:include href="../template/permalinks.xsl"/>
-  <xsl:include href="../template/section.title.xsl"/>
-  <xsl:include href="../template/component.title.xsl"/>
-  <xsl:include href="../template/division.title.xsl"/>
-  <xsl:include href="../template/formal.object.heading.xsl"/>
-
-  <xsl:param name="html.stylesheet" select="'bsp-style.css'" />
-  <xsl:param name="chapter.autolabel" select="1" />
-  <xsl:param name="appendix.autolabel" select="A" />
-  <xsl:param name="section.autolabel" select="1" />
-  <xsl:param name="section.label.includes.component.label" select="1" />
-  <xsl:param name="generate.id.attributes" select="1" />
-
-</xsl:stylesheet>

documentation/bsp-guide/bsp-guide.rst

@@ -0,0 +1,16 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+=====================================================
+Yocto Project Board Support Package Developer's Guide
+=====================================================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   bsp
+   history
+
+.. include:: /boilerplate.rst

documentation/bsp-guide/bsp-guide.xml

@@ -1,216 +0,0 @@
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<book id='bsp-guide' lang='en'
-      xmlns:xi="http://www.w3.org/2003/XInclude"
-      xmlns="http://docbook.org/ns/docbook"
-      >
-    <bookinfo>
-
-        <mediaobject>
-            <imageobject>
-                <imagedata fileref='figures/bsp-title.png'
-                    format='SVG'
-                    align='center' scalefit='1' width='100%'/>
-            </imageobject>
-        </mediaobject>
-
-        <title>
-            Yocto Project Board Support Package Developer's Guide
-        </title>
-
-        <authorgroup>
-            <author>
-                <affiliation>
-                    <orgname>&ORGNAME;</orgname>
-                </affiliation>
-                <email>&ORGEMAIL;</email>
-            </author>
-        </authorgroup>
-
-        <revhistory>
-            <revision>
-                <revnumber>0.9</revnumber>
-                <date>November 2010</date>
-                <revremark>The initial document released with the Yocto Project 0.9 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.0</revnumber>
-                <date>April 2011</date>
-                <revremark>Released with the Yocto Project 1.0 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.1</revnumber>
-                <date>October 2011</date>
-                <revremark>Released with the Yocto Project 1.1 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.2</revnumber>
-                <date>April 2012</date>
-                <revremark>Released with the Yocto Project 1.2 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.3</revnumber>
-                <date>October 2012</date>
-                <revremark>Released with the Yocto Project 1.3 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.4</revnumber>
-                <date>April 2013</date>
-                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.5</revnumber>
-                <date>October 2013</date>
-                <revremark>Released with the Yocto Project 1.5 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.6</revnumber>
-                <date>April 2014</date>
-                <revremark>Released with the Yocto Project 1.6 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.7</revnumber>
-                <date>October 2014</date>
-                <revremark>Released with the Yocto Project 1.7 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.8</revnumber>
-                <date>April 2015</date>
-                <revremark>Released with the Yocto Project 1.8 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.0</revnumber>
-                <date>October 2015</date>
-                <revremark>Released with the Yocto Project 2.0 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.1</revnumber>
-                <date>April 2016</date>
-                <revremark>Released with the Yocto Project 2.1 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.2</revnumber>
-                <date>October 2016</date>
-                <revremark>Released with the Yocto Project 2.2 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.3</revnumber>
-                <date>May 2017</date>
-                <revremark>Released with the Yocto Project 2.3 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.4</revnumber>
-                <date>October 2017</date>
-                <revremark>Released with the Yocto Project 2.4 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.5</revnumber>
-                <date>May 2018</date>
-                <revremark>Released with the Yocto Project 2.5 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.6</revnumber>
-                <date>November 2018</date>
-                <revremark>Released with the Yocto Project 2.6 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.7</revnumber>
-                <date>May 2019</date>
-                <revremark>Released with the Yocto Project 2.7 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>3.0</revnumber>
-                <date>October 2019</date>
-                <revremark>Released with the Yocto Project 3.0 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>3.1</revnumber>
-                <date>April 2020</date>
-                <revremark>Released with the Yocto Project 3.1 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>3.1.1</revnumber>
-                <date>June 2020</date>
-                <revremark>Released with the Yocto Project 3.1.1 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>3.1.2</revnumber>
-                <date>August 2020</date>
-                <revremark>Released with the Yocto Project 3.1.2 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>3.1.3</revnumber>
-                <date>&REL_MONTH_YEAR;</date>
-                <revremark>Released with the Yocto Project 3.1.3 Release.</revremark>
-            </revision>
-        </revhistory>
-
-    <copyright>
-      <year>&COPYRIGHT_YEAR;</year>
-      <holder>Linux Foundation</holder>
-    </copyright>
-
-    <legalnotice>
-      <para>
-        Permission is granted to copy, distribute and/or modify this document under
-        the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
-      </para>
-           <note><title>Manual Notes</title>
-               <itemizedlist>
-                   <listitem><para>
-                       This version of the
-                       <emphasis>Yocto Project Board Support Package (BSP) Developer's Guide</emphasis>
-                       is for the &YOCTO_DOC_VERSION; release of the
-                       Yocto Project.
-                       To be sure you have the latest version of the manual
-                       for this release, go to the
-                       <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
-                       and select the manual from that site.
-                       Manuals from the site are more up-to-date than manuals
-                       derived from the Yocto Project released TAR files.
-                       </para></listitem>
-                   <listitem><para>
-                       If you located this manual through a web search, the
-                       version of the manual might not be the one you want
-                       (e.g. the search might have returned a manual much
-                       older than the Yocto Project version with which you
-                       are working).
-                       You can see all Yocto Project major releases by
-                       visiting the
-                       <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
-                       page.
-                       If you need a version of this manual for a different
-                       Yocto Project release, visit the
-                       <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
-                       and select the manual set by using the
-                       "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
-                       pull-down menus.
-                       </para></listitem>
-                   <listitem>
-                       <para>
-                       To report any inaccuracies or problems with this
-                       (or any other Yocto Project) manual, send an email to
-                       the Yocto Project documentation mailing list at
-                       <filename>docs@lists.yoctoproject.org</filename> or
-                       log into the freenode <filename>#yocto</filename> channel.
-                       </para>
-                   </listitem>
-               </itemizedlist>
-           </note>
-    </legalnotice>
-
-    </bookinfo>
-
-    <xi:include href="bsp.xml"/>
-
-<!--    <index id='index'>
-      <title>Index</title>
-    </index>
--->
-
-</book>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/bsp-guide/bsp-style.css

@@ -1,987 +0,0 @@
-/*
-   Generic XHTML / DocBook XHTML CSS Stylesheet.
-
-   Browser wrangling and typographic design by
-      Oyvind Kolas / pippin@gimp.org
-
-   Customised for Poky by
-      Matthew Allum / mallum@o-hand.com
-
-   Thanks to:
-     Liam R. E. Quin
-     William Skaggs
-     Jakub Steiner
-
-   Structure
-   ---------
-
-   The stylesheet is divided into the following sections:
-
-       Positioning
-          Margins, paddings, width, font-size, clearing.
-       Decorations
-          Borders, style
-       Colors
-          Colors
-       Graphics
-          Graphical backgrounds
-       Nasty IE tweaks
-          Workarounds needed to make it work in internet explorer,
-          currently makes the stylesheet non validating, but up until
-          this point it is validating.
-       Mozilla extensions
-          Transparency for footer
-	  Rounded corners on boxes
-
-*/
-
-
-  /*************** /
- /  Positioning   /
-/ ***************/
-
-body {
-  font-family: Verdana, Sans, sans-serif;
-
-  min-width: 640px;
-  width: 80%;
-  margin:  0em auto;
-  padding: 2em 5em 5em 5em;
-  color: #333;
-}
-
-h1,h2,h3,h4,h5,h6,h7 {
-  font-family: Arial, Sans;
-  color: #00557D;
-  clear: both;
-}
-
-h1 {
-  font-size: 2em;
-  text-align: left;
-  padding: 0em 0em 0em 0em;
-  margin: 2em 0em 0em 0em;
-}
-
-h2.subtitle {
-  margin: 0.10em 0em 3.0em 0em;
-  padding: 0em 0em 0em 0em;
-  font-size: 1.8em;
-  padding-left: 20%;
-  font-weight: normal;
-  font-style: italic;
-}
-
-h2 {
-  margin: 2em 0em 0.66em 0em;
-  padding: 0.5em 0em 0em 0em;
-  font-size: 1.5em;
-  font-weight: bold;
-}
-
-h3.subtitle {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-  font-size: 142.14%;
-  text-align: right;
-}
-
-h3 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 140%;
-  font-weight: bold;
-}
-
-h4 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 120%;
-  font-weight: bold;
-}
-
-h5 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 110%;
-  font-weight: bold;
-}
-
-h6 {
-  margin: 1em 0em 0em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 110%;
-  font-weight: bold;
-}
-
-.authorgroup {
-  background-color: transparent;
-  background-repeat: no-repeat;
-  padding-top: 256px;
-  background-image: url("figures/bsp-title.png");
-  background-position: left top;
-  margin-top: -256px;
-  padding-right: 50px;
-  margin-left: 0px;
-  text-align: right;
-  width: 740px;
-}
-
-h3.author {
-  margin: 0em 0me 0em 0em;
-  padding: 0em 0em 0em 0em;
-  font-weight: normal;
-  font-size: 100%;
-  color: #333;
-  clear: both;
-}
-
-.author tt.email {
-  font-size: 66%;
-}
-
-.titlepage hr {
-  width: 0em;
-  clear: both;
-}
-
-.revhistory {
-  padding-top: 2em;
-  clear: both;
-}
-
-.toc,
-.list-of-tables,
-.list-of-examples,
-.list-of-figures {
-  padding: 1.33em 0em 2.5em 0em;
-  color: #00557D;
-}
-
-.toc p,
-.list-of-tables p,
-.list-of-figures p,
-.list-of-examples p {
-  padding: 0em 0em 0em 0em;
-  padding: 0em 0em 0.3em;
-  margin: 1.5em 0em 0em 0em;
-}
-
-.toc p b,
-.list-of-tables p b,
-.list-of-figures p b,
-.list-of-examples p b{
-  font-size: 100.0%;
-  font-weight: bold;
-}
-
-.toc dl,
-.list-of-tables dl,
-.list-of-figures dl,
-.list-of-examples dl {
-  margin: 0em 0em 0.5em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.toc dt {
-  margin: 0em 0em 0em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.toc dd {
-  margin: 0em 0em 0em 2.6em;
-  padding: 0em 0em 0em 0em;
-}
-
-div.glossary dl,
-div.variablelist dl {
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
-  font-weight: normal;
-  width: 20em;
-  text-align: right;
-}
-
-.variablelist dl dt {
-  margin-top: 0.5em;
-}
-
-.glossary dl dd,
-.variablelist dl dd {
-  margin-top: -1em;
-  margin-left: 25.5em;
-}
-
-.glossary dd p,
-.variablelist dd p {
-  margin-top: 0em;
-  margin-bottom: 1em;
-}
-
-
-div.calloutlist table td {
-  padding: 0em 0em 0em 0em;
-  margin: 0em 0em 0em 0em;
-}
-
-div.calloutlist table td p {
-  margin-top: 0em;
-  margin-bottom: 1em;
-}
-
-div p.copyright {
-  text-align: left;
-}
-
-div.legalnotice p.legalnotice-title {
-  margin-bottom: 0em;
-}
-
-p {
-  line-height: 1.5em;
-  margin-top: 0em;
-
-}
-
-dl {
-  padding-top: 0em;
-}
-
-hr {
-  border: solid 1px;
-}
-
-
-.mediaobject,
-.mediaobjectco {
-  text-align: center;
-}
-
-img {
-  border: none;
-}
-
-ul {
-  padding: 0em 0em 0em 1.5em;
-}
-
-ul li {
-  padding: 0em 0em 0em 0em;
-}
-
-ul li p {
-  text-align: left;
-}
-
-table {
-  width :100%;
-}
-
-th {
-  padding: 0.25em;
-  text-align: left;
-  font-weight: normal;
-  vertical-align: top;
-}
-
-td {
-  padding: 0.25em;
-  vertical-align: top;
-}
-
-p a[id] {
-  margin: 0px;
-  padding: 0px;
-  display: inline;
-  background-image: none;
-}
-
-a {
-  text-decoration: underline;
-  color: #444;
-}
-
-pre {
-    overflow: auto;
-}
-
-a:hover {
-  text-decoration: underline;
-  /*font-weight: bold;*/
-}
-
-/* This style defines how the permalink character
-   appears by itself and when hovered over with
-   the mouse. */
-
-[alt='Permalink'] { color: #eee; }
-[alt='Permalink']:hover { color: black; }
-
-
-div.informalfigure,
-div.informalexample,
-div.informaltable,
-div.figure,
-div.table,
-div.example {
-  margin: 1em 0em;
-  padding: 1em;
-  page-break-inside: avoid;
-}
-
-
-div.informalfigure p.title b,
-div.informalexample p.title b,
-div.informaltable p.title b,
-div.figure p.title b,
-div.example p.title b,
-div.table p.title b{
-    padding-top: 0em;
-    margin-top: 0em;
-    font-size: 100%;
-    font-weight: normal;
-}
-
-.mediaobject .caption,
-.mediaobject .caption p  {
-  text-align: center;
-  font-size: 80%;
-  padding-top: 0.5em;
-  padding-bottom: 0.5em;
-}
-
-.epigraph {
-  padding-left: 55%;
-  margin-bottom: 1em;
-}
-
-.epigraph p {
-  text-align: left;
-}
-
-.epigraph .quote {
-  font-style: italic;
-}
-.epigraph .attribution {
-  font-style: normal;
-  text-align: right;
-}
-
-span.application {
-  font-style: italic;
-}
-
-.programlisting {
-  font-family: monospace;
-  font-size: 80%;
-  white-space: pre;
-  margin: 1.33em 0em;
-  padding: 1.33em;
-}
-
-.tip,
-.warning,
-.caution,
-.note {
-  margin-top: 1em;
-  margin-bottom: 1em;
-
-}
-
-/* force full width of table within div */
-.tip table,
-.warning table,
-.caution table,
-.note table {
-  border: none;
-  width: 100%;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  padding: 0.8em 0.0em 0.0em 0.0em;
-  margin : 0em 0em 0em 0em;
-}
-
-.tip p,
-.warning p,
-.caution p,
-.note p {
-  margin-top: 0.5em;
-  margin-bottom: 0.5em;
-  padding-right: 1em;
-  text-align: left;
-}
-
-.acronym {
-  text-transform: uppercase;
-}
-
-b.keycap,
-.keycap {
-  padding: 0.09em 0.3em;
-  margin: 0em;
-}
-
-.itemizedlist li {
-  clear: none;
-}
-
-.filename {
-  font-size: medium;
-  font-family: Courier, monospace;
-}
-
-
-div.navheader, div.heading{
-  position: absolute;
-  left: 0em;
-  top: 0em;
-  width: 100%;
-  background-color: #cdf;
-  width: 100%;
-}
-
-div.navfooter, div.footing{
-  position: fixed;
-  left: 0em;
-  bottom: 0em;
-  background-color: #eee;
-  width: 100%;
-}
-
-
-div.navheader td,
-div.navfooter td {
-  font-size: 66%;
-}
-
-div.navheader table th {
-  /*font-family: Georgia, Times, serif;*/
-  /*font-size: x-large;*/
-  font-size: 80%;
-}
-
-div.navheader table {
-  border-left: 0em;
-  border-right: 0em;
-  border-top: 0em;
-  width: 100%;
-}
-
-div.navfooter table {
-  border-left: 0em;
-  border-right: 0em;
-  border-bottom: 0em;
-  width: 100%;
-}
-
-div.navheader table td a,
-div.navfooter table td a {
-  color: #777;
-  text-decoration: none;
-}
-
-/* normal text in the footer */
-div.navfooter table td {
-  color: black;
-}
-
-div.navheader table td a:visited,
-div.navfooter table td a:visited {
-  color: #444;
-}
-
-
-/* links in header and footer */
-div.navheader table td a:hover,
-div.navfooter table td a:hover {
-  text-decoration: underline;
-  background-color: transparent;
-  color: #33a;
-}
-
-div.navheader hr,
-div.navfooter hr {
-  display: none;
-}
-
-
-.qandaset tr.question td p {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.qandaset tr.answer td p {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-}
-.answer td {
-  padding-bottom: 1.5em;
-}
-
-.emphasis {
-  font-weight: bold;
-}
-
-
-  /************* /
- / decorations  /
-/ *************/
-
-.titlepage {
-}
-
-.part .title {
-}
-
-.subtitle {
-    border: none;
-}
-
-/*
-h1 {
-  border: none;
-}
-
-h2 {
-  border-top: solid 0.2em;
-  border-bottom: solid 0.06em;
-}
-
-h3 {
-  border-top: 0em;
-  border-bottom: solid 0.06em;
-}
-
-h4 {
-  border: 0em;
-  border-bottom: solid 0.06em;
-}
-
-h5 {
-  border: 0em;
-}
-*/
-
-.programlisting {
-  border: solid 1px;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example {
-  border: 1px solid;
-}
-
-
-
-.tip,
-.warning,
-.caution,
-.note {
-  border: 1px solid;
-}
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  border-bottom: 1px solid;
-}
-
-.question td {
-  border-top: 1px solid black;
-}
-
-.answer {
-}
-
-
-b.keycap,
-.keycap {
-  border: 1px solid;
-}
-
-
-div.navheader, div.heading{
-  border-bottom: 1px solid;
-}
-
-
-div.navfooter, div.footing{
-  border-top: 1px solid;
-}
-
-  /********* /
- /  colors  /
-/ *********/
-
-body {
-  color: #333;
-  background: white;
-}
-
-a {
-  background: transparent;
-}
-
-a:hover {
-  background-color: #dedede;
-}
-
-
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7,
-h8 {
-  background-color: transparent;
-}
-
-hr {
-  border-color: #aaa;
-}
-
-
-.tip, .warning, .caution, .note {
-  border-color: #fff;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  border-bottom-color: #fff;
-}
-
-
-.warning {
-  background-color: #f0f0f2;
-}
-
-.caution {
-  background-color: #f0f0f2;
-}
-
-.tip {
-  background-color: #f0f0f2;
-}
-
-.note {
-  background-color: #f0f0f2;
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
-  color: #044;
-}
-
-div.figure,
-div.table,
-div.example,
-div.informalfigure,
-div.informaltable,
-div.informalexample {
-  border-color: #aaa;
-}
-
-pre.programlisting {
-  color: black;
-  background-color: #fff;
-  border-color: #aaa;
-  border-width: 2px;
-}
-
-.guimenu,
-.guilabel,
-.guimenuitem {
-  background-color: #eee;
-}
-
-
-b.keycap,
-.keycap {
-  background-color: #eee;
-  border-color: #999;
-}
-
-
-div.navheader {
-  border-color: black;
-}
-
-
-div.navfooter {
-  border-color: black;
-}
-
-.writernotes {
-  color: red;
-}
-
-  /*********** /
- /  graphics  /
-/ ***********/
-
-/*
-body {
-  background-image: url("images/body_bg.jpg");
-  background-attachment: fixed;
-}
-
-.navheader,
-.note,
-.tip {
-  background-image: url("images/note_bg.jpg");
-  background-attachment: fixed;
-}
-
-.warning,
-.caution {
-  background-image: url("images/warning_bg.jpg");
-  background-attachment: fixed;
-}
-
-.figure,
-.informalfigure,
-.example,
-.informalexample,
-.table,
-.informaltable {
-  background-image: url("images/figure_bg.jpg");
-  background-attachment: fixed;
-}
-
-*/
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7{
-}
-
-/*
-Example of how to stick an image as part of the title.
-
-div.article .titlepage .title
-{
-  background-image: url("figures/white-on-black.png");
-  background-position: center;
-  background-repeat: repeat-x;
-}
-*/
-
-div.preface .titlepage .title,
-div.colophon .title,
-div.chapter .titlepage .title {
-  background-position: bottom;
-  background-repeat: repeat-x;
-}
-
-div.section div.section .titlepage .title,
-div.sect2 .titlepage .title {
-    background: none;
-}
-
-
-h1.title {
-  background-color: transparent;
-  background-repeat: no-repeat;
-  height: 256px;
-  text-indent: -9000px;
-  overflow:hidden;
-}
-
-h2.subtitle {
-  background-color: transparent;
-  text-indent: -9000px;
-  overflow:hidden;
-  width: 0px;
-  display: none;
-}
-
-  /*************************************** /
- /  pippin.gimp.org specific alterations  /
-/ ***************************************/
-
-/*
-div.heading, div.navheader {
-  color: #777;
-  font-size: 80%;
-  padding: 0;
-  margin: 0;
-  text-align: left;
-  position: absolute;
-  top: 0px;
-  left: 0px;
-  width: 100%;
-  height: 50px;
-  background: url('/gfx/heading_bg.png') transparent;
-  background-repeat: repeat-x;
-  background-attachment: fixed;
-  border: none;
-}
-
-div.heading a {
-  color: #444;
-}
-
-div.footing, div.navfooter {
-  border: none;
-  color: #ddd;
-  font-size: 80%;
-  text-align:right;
-
-  width: 100%;
-  padding-top: 10px;
-  position: absolute;
-  bottom: 0px;
-  left: 0px;
-
-  background: url('/gfx/footing_bg.png') transparent;
-}
-*/
-
-
-
-  /****************** /
- /  nasty ie tweaks  /
-/ ******************/
-
-/*
-div.heading, div.navheader {
-  width:expression(document.body.clientWidth + "px");
-}
-
-div.footing, div.navfooter {
-  width:expression(document.body.clientWidth + "px");
-  margin-left:expression("-5em");
-}
-body {
-  padding:expression("4em 5em 0em 5em");
-}
-*/
-
-  /**************************************** /
- / mozilla vendor specific css extensions  /
-/ ****************************************/
-/*
-div.navfooter, div.footing{
-  -moz-opacity: 0.8em;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example,
-.tip,
-.warning,
-.caution,
-.note {
-  -moz-border-radius: 0.5em;
-}
-
-b.keycap,
-.keycap {
-  -moz-border-radius: 0.3em;
-}
-*/
-
-table tr td table tr td {
-  display: none;
-}
-
-
-hr {
-  display: none;
-}
-
-table {
-  border: 0em;
-}
-
- .photo {
-  float: right;
-  margin-left:   1.5em;
-  margin-bottom: 1.5em;
-  margin-top: 0em;
-  max-width:      17em;
-  border:     1px solid gray;
-  padding:    3px;
-  background: white;
-}
- .seperator {
-   padding-top: 2em;
-   clear: both;
-  }
-
-  #validators {
-      margin-top: 5em;
-      text-align: right;
-      color: #777;
-  }
-  @media print {
-      body {
-          font-size: 8pt;
-      }
-      .noprint {
-          display: none;
-      }
-  }
-
-
-.tip,
-.note {
-   background: #f0f0f2;
-   color: #333;
-   padding: 20px;
-   margin: 20px;
-}
-
-.tip h3,
-.note h3 {
-   padding: 0em;
-   margin: 0em;
-   font-size: 2em;
-   font-weight: bold;
-   color: #333;
-}
-
-.tip a,
-.note a {
-   color: #333;
-   text-decoration: underline;
-}
-
-.footnote {
-   font-size: small;
-   color: #333;
-}
-
-/* Changes the announcement text */
-.tip h3,
-.warning h3,
-.caution h3,
-.note h3 {
-   font-size:large;
-   color: #00557D;
-}

documentation/bsp-guide/history.rst

@@ -0,0 +1,85 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+***********************
+Manual Revision History
+***********************
+
+.. list-table::
+   :widths: 10 15 40
+   :header-rows: 1
+
+   * - Revision
+     - Date
+     - Note
+   * - 0.9
+     - November 2010
+     - The initial document released with the Yocto Project 0.9 Release
+   * - 1.0
+     - April 2011
+     - Released with the Yocto Project 1.0 Release.
+   * - 1.1
+     - October 2011
+     - Released with the Yocto Project 1.1 Release.
+   * - 1.2
+     - April 2012
+     - Released with the Yocto Project 1.2 Release.
+   * - 1.3
+     - October 2012
+     - Released with the Yocto Project 1.3 Release.
+   * - 1.4
+     - April 2013
+     - Released with the Yocto Project 1.4 Release.
+   * - 1.5
+     - October 2013
+     - Released with the Yocto Project 1.5 Release.
+   * - 1.6
+     - April 2014
+     - Released with the Yocto Project 1.6 Release.
+   * - 1.7
+     - October 2014
+     - Released with the Yocto Project 1.7 Release.
+   * - 1.8
+     - April 2015
+     - Released with the Yocto Project 1.8 Release.
+   * - 2.0
+     - October 2015
+     - Released with the Yocto Project 2.0 Release.
+   * - 2.1
+     - April 2016
+     - Released with the Yocto Project 2.1 Release.
+   * - 2.2
+     - October 2016
+     - Released with the Yocto Project 2.2 Release.
+   * - 2.3
+     - May 2017
+     - Released with the Yocto Project 2.3 Release.
+   * - 2.4
+     - October 2017
+     - Released with the Yocto Project 2.4 Release.
+   * - 2.5
+     - May 2018
+     - Released with the Yocto Project 2.5 Release.
+   * - 2.6
+     - November 2018
+     - Released with the Yocto Project 2.6 Release.
+   * - 2.7
+     - May 2019
+     - Released with the Yocto Project 2.7 Release.
+   * - 3.0
+     - October 2019
+     - Released with the Yocto Project 3.0 Release.
+   * - 3.1
+     - April 2020
+     - Released with the Yocto Project 3.1 Release.
+   * - 3.1.1
+     - June 2020
+     - Released with the Yocto Project 3.1.1 Release.
+   * - 3.1.2
+     - August 2020
+     - Released with the Yocto Project 3.1.2 Release.
+   * - 3.1.3
+     - September 2020
+     - Released with the Yocto Project 3.1.3 Release.
+   * - 3.1.4
+     - November 2020
+     - Released with the Yocto Project 3.1.4 Release.

documentation/conf.py

@@ -0,0 +1,131 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# SPDX-License-Identifier: CC-BY-SA-2.0-UK
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+import datetime
+
+current_version = "3.1.5"
+
+# String used in sidebar
+version = 'Version: ' + current_version
+if current_version == 'dev':
+    version = 'Version: Current Development'
+# Version seen in documentation_options.js and hence in js switchers code
+release = current_version
+
+
+# -- Project information -----------------------------------------------------
+project = 'The Yocto Project \xae'
+copyright = '2010-%s, The Linux Foundation' % datetime.datetime.now().year
+author = 'The Linux Foundation'
+
+# -- General configuration ---------------------------------------------------
+
+# to load local extension from the folder 'sphinx'
+sys.path.insert(0, os.path.abspath('sphinx'))
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.intersphinx',
+    'yocto-vars'
+]
+autosectionlabel_prefix_document = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'boilerplate.rst']
+
+# master document name. The default changed from contents to index. so better
+# set it ourselves.
+master_doc = 'index'
+
+# create substitution for project configuration variables
+rst_prolog = """
+.. |project_name| replace:: %s
+.. |copyright| replace:: %s
+.. |author| replace:: %s
+""" % (project, copyright, author)
+
+# external links and substitutions
+extlinks = {
+    'yocto_home': ('https://yoctoproject.org%s', None),
+    'yocto_wiki': ('https://wiki.yoctoproject.org%s', None),
+    'yocto_dl': ('https://downloads.yoctoproject.org%s', None),
+    'yocto_lists': ('https://lists.yoctoproject.org%s', None),
+    'yocto_bugs': ('https://bugzilla.yoctoproject.org%s', None),
+    'yocto_ab': ('https://autobuilder.yoctoproject.org%s', None),
+    'yocto_docs': ('https://docs.yoctoproject.org%s', None),
+    'yocto_git': ('https://git.yoctoproject.org%s', None),
+    'oe_home': ('https://www.openembedded.org%s', None),
+    'oe_lists': ('https://lists.openembedded.org%s', None),
+}
+
+# Intersphinx config to use cross reference with Bitbake user manual
+intersphinx_mapping = {
+    'bitbake': ('https://docs.yoctoproject.org/bitbake/1.46', None)
+}
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+try:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_options = {
+        'sticky_navigation': False,
+    }
+except ImportError:
+    sys.stderr.write("The Sphinx sphinx_rtd_theme HTML theme was not found.\
+    \nPlease make sure to install the sphinx_rtd_theme python package.\n")
+    sys.exit(1)
+
+html_logo = 'sphinx-static/YoctoProject_Logo_RGB.jpg'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['sphinx-static']
+
+html_context = {
+    'current_version': current_version,
+}
+
+# Add customm CSS and JS files
+html_css_files = ['theme_overrides.css']
+html_js_files = ['switchers.js']
+
+# Hide 'Created using Sphinx' text
+html_show_sphinx = False
+
+# Add 'Last updated' on each page
+html_last_updated_fmt = '%b %d, %Y'
+
+# Remove the trailing 'dot' in section numbers
+html_secnumber_suffix = " "
+
+latex_elements = {
+    'passoptionstopackages': '\PassOptionsToPackage{bookmarksdepth=5}{hyperref}',
+    'preamble': '\setcounter{tocdepth}{2}',
+}

documentation/dev-manual/dev-manual-customization.xsl

@@ -1,27 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
-
-  <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-<!--
-
-  <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-  <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
-
--->
-
-  <xsl:include href="../template/permalinks.xsl"/>
-  <xsl:include href="../template/section.title.xsl"/>
-  <xsl:include href="../template/component.title.xsl"/>
-  <xsl:include href="../template/division.title.xsl"/>
-  <xsl:include href="../template/formal.object.heading.xsl"/>
-
-  <xsl:param name="html.stylesheet" select="'dev-style.css'" />
-  <xsl:param name="chapter.autolabel" select="1" />
-  <xsl:param name="appendix.autolabel" select="A" />
-  <xsl:param name="section.autolabel" select="1" />
-  <xsl:param name="section.label.includes.component.label" select="1" />
-  <xsl:param name="generate.id.attributes" select="1" />
-
-</xsl:stylesheet>

documentation/dev-manual/dev-manual-intro.rst

@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+******************************************
+The Yocto Project Development Tasks Manual
+******************************************
+
+.. _dev-welcome:
+
+Welcome
+=======
+
+Welcome to the Yocto Project Development Tasks Manual! This manual
+provides relevant procedures necessary for developing in the Yocto
+Project environment (i.e. developing embedded Linux images and
+user-space applications that run on targeted devices). The manual groups
+related procedures into higher-level sections. Procedures can consist of
+high-level steps or low-level steps depending on the topic.
+
+This manual provides the following:
+
+-  Procedures that help you get going with the Yocto Project. For
+   example, procedures that show you how to set up a build host and work
+   with the Yocto Project source repositories.
+
+-  Procedures that show you how to submit changes to the Yocto Project.
+   Changes can be improvements, new features, or bug fixes.
+
+-  Procedures related to "everyday" tasks you perform while developing
+   images and applications using the Yocto Project. For example,
+   procedures to create a layer, customize an image, write a new recipe,
+   and so forth.
+
+This manual does not provide the following:
+
+-  Redundant Step-by-step Instructions: For example, the
+   :doc:`../sdk-manual/sdk-manual` manual contains detailed
+   instructions on how to install an SDK, which is used to develop
+   applications for target hardware.
+
+-  Reference or Conceptual Material: This type of material resides in an
+   appropriate reference manual. For example, system variables are
+   documented in the :doc:`../ref-manual/ref-manual`.
+
+-  Detailed Public Information Not Specific to the Yocto Project: For
+   example, exhaustive information on how to use the Source Control
+   Manager Git is better covered with Internet searches and official Git
+   Documentation than through the Yocto Project documentation.
+
+Other Information
+=================
+
+Because this manual presents information for many different topics,
+supplemental information is recommended for full comprehension. For
+introductory information on the Yocto Project, see the
+:yocto_home:`Yocto Project Website <>`. If you want to build an image with no
+knowledge of Yocto Project as a way of quickly testing it out, see the
+:doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document.
+
+For a comprehensive list of links and other documentation, see the
+":ref:`ref-manual/resources:links and related documentation`"
+section in the Yocto Project Reference Manual.

documentation/dev-manual/dev-manual-intro.xml

@@ -1,103 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='dev-manual-intro'>
-
-<title>The Yocto Project Development Tasks Manual</title>
-    <section id='dev-welcome'>
-        <title>Welcome</title>
-
-        <para>
-            Welcome to the Yocto Project Development Tasks Manual!
-            This manual provides relevant procedures necessary for developing
-            in the Yocto Project environment (i.e. developing embedded Linux
-            images and user-space applications that run on targeted devices).
-            The manual groups related procedures into higher-level sections.
-            Procedures can consist of high-level steps or low-level steps
-            depending on the topic.
-        </para>
-
-        <para>
-            This manual provides the following:
-            <itemizedlist>
-                <listitem><para>
-                    Procedures that help you get going with the Yocto Project.
-                    For example, procedures that show you how to set up
-                    a build host and work with the Yocto Project
-                    source repositories.
-                    </para></listitem>
-                <listitem><para>
-                    Procedures that show you how to submit changes to the
-                    Yocto Project.
-                    Changes can be improvements, new features, or bug
-                    fixes.
-                    </para></listitem>
-                <listitem><para>
-                    Procedures related to "everyday" tasks you perform while
-                    developing images and applications using the Yocto
-                    Project.
-                    For example, procedures to create a layer, customize an
-                    image, write a new recipe, and so forth.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-
-        <para>
-            This manual does not provide the following:
-            <itemizedlist>
-                <listitem><para>
-                    Redundant Step-by-step Instructions:
-                    For example, the
-                    <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
-                    manual contains detailed instructions on how to install an
-                    SDK, which is used to develop applications for target
-                    hardware.
-                    </para></listitem>
-                <listitem><para>
-                    Reference or Conceptual Material:
-                    This type of material resides in an appropriate reference
-                    manual.
-                    For example, system variables are documented in the
-                    <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.
-                    </para></listitem>
-                <listitem><para>
-                    Detailed Public Information Not Specific to the
-                    Yocto Project:
-                    For example, exhaustive information on how to use the
-                    Source Control Manager Git is better covered with Internet
-                    searches and official Git Documentation than through the
-                    Yocto Project documentation.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-
-    <section id='other-information'>
-        <title>Other Information</title>
-
-        <para>
-            Because this manual presents information for many different
-            topics, supplemental information is recommended for full
-            comprehension.
-            For introductory information on the Yocto Project, see the
-            <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>.
-            If you want to build an image with no knowledge of Yocto Project
-            as a way of quickly testing it out, see the
-            <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
-            document.
-        </para>
-
-        <para>
-            For a comprehensive list of links and other documentation, see the
-            "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"
-            section in the Yocto Project Reference Manual.
-        </para>
-
-        <para>
-        </para>
-    </section>
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/dev-manual/dev-manual-qemu.rst

@@ -0,0 +1,477 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+*******************************
+Using the Quick EMUlator (QEMU)
+*******************************
+
+The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
+Open Source project as part of the Yocto Project development "tool set".
+This chapter provides both procedures that show you how to use the Quick
+EMUlator (QEMU) and other QEMU information helpful for development
+purposes.
+
+.. _qemu-dev-overview:
+
+Overview
+========
+
+Within the context of the Yocto Project, QEMU is an emulator and
+virtualization machine that allows you to run a complete image you have
+built using the Yocto Project as just another task on your build system.
+QEMU is useful for running and testing images and applications on
+supported Yocto Project architectures without having actual hardware.
+Among other things, the Yocto Project uses QEMU to run automated Quality
+Assurance (QA) tests on final images shipped with each release.
+
+.. note::
+
+   This implementation is not the same as QEMU in general.
+
+This section provides a brief reference for the Yocto Project
+implementation of QEMU.
+
+For official information and documentation on QEMU in general, see the
+following references:
+
+-  `QEMU Website <https://wiki.qemu.org/Main_Page>`__\ *:* The official
+   website for the QEMU Open Source project.
+
+-  `Documentation <https://wiki.qemu.org/Manual>`__\ *:* The QEMU user
+   manual.
+
+.. _qemu-running-qemu:
+
+Running QEMU
+============
+
+To use QEMU, you need to have QEMU installed and initialized as well as
+have the proper artifacts (i.e. image files and root filesystems)
+available. Follow these general steps to run QEMU:
+
+1. *Install QEMU:* QEMU is made available with the Yocto Project a
+   number of ways. One method is to install a Software Development Kit
+   (SDK). See ":ref:`sdk-manual/sdk-intro:the qemu emulator`" section in the
+   Yocto Project Application Development and the Extensible Software
+   Development Kit (eSDK) manual for information on how to install QEMU.
+
+2. *Setting Up the Environment:* How you set up the QEMU environment
+   depends on how you installed QEMU:
+
+   -  If you cloned the ``poky`` repository or you downloaded and
+      unpacked a Yocto Project release tarball, you can source the build
+      environment script (i.e. :ref:`structure-core-script`):
+      ::
+
+         $ cd ~/poky
+         $ source oe-init-build-env
+
+   -  If you installed a cross-toolchain, you can run the script that
+      initializes the toolchain. For example, the following commands run
+      the initialization script from the default ``poky_sdk`` directory:
+      ::
+
+         . ~/poky_sdk/environment-setup-core2-64-poky-linux
+
+3. *Ensure the Artifacts are in Place:* You need to be sure you have a
+   pre-built kernel that will boot in QEMU. You also need the target
+   root filesystem for your target machine's architecture:
+
+   -  If you have previously built an image for QEMU (e.g. ``qemux86``,
+      ``qemuarm``, and so forth), then the artifacts are in place in
+      your :term:`Build Directory`.
+
+   -  If you have not built an image, you can go to the
+      :yocto_dl:`machines/qemu </releases/yocto/yocto-3.1.2/machines/qemu/>` area and download a
+      pre-built image that matches your architecture and can be run on
+      QEMU.
+
+   See the ":ref:`sdk-manual/sdk-appendix-obtain:extracting the root filesystem`"
+   section in the Yocto Project Application Development and the
+   Extensible Software Development Kit (eSDK) manual for information on
+   how to extract a root filesystem.
+
+4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows:
+   ::
+
+      $ runqemu [option ] [...]
+
+   Based on what you provide on the command
+   line, ``runqemu`` does a good job of figuring out what you are trying
+   to do. For example, by default, QEMU looks for the most recently
+   built image according to the timestamp when it needs to look for an
+   image. Minimally, through the use of options, you must provide either
+   a machine name, a virtual machine image (``*wic.vmdk``), or a kernel
+   image (``*.bin``).
+
+   Here are some additional examples to help illustrate further QEMU:
+
+   -  This example starts QEMU with MACHINE set to "qemux86-64".
+      Assuming a standard
+      :term:`Build Directory`, ``runqemu``
+      automatically finds the ``bzImage-qemux86-64.bin`` image file and
+      the ``core-image-minimal-qemux86-64-20200218002850.rootfs.ext4``
+      (assuming the current build created a ``core-image-minimal``
+      image).
+
+      .. note::
+
+         When more than one image with the same name exists, QEMU finds
+         and uses the most recently built image according to the
+         timestamp.
+
+      ::
+
+        $ runqemu qemux86-64
+
+   -  This example produces the exact same results as the previous
+      example. This command, however, specifically provides the image
+      and root filesystem type.
+      ::
+
+         $ runqemu qemux86-64 core-image-minimal ext4
+
+   -  This example specifies to boot an initial RAM disk image and to
+      enable audio in QEMU. For this case, ``runqemu`` set the internal
+      variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled,
+      an appropriate driver must be installed (see the previous
+      description for the ``audio`` option for more information).
+      ::
+
+         $ runqemu qemux86-64 ramfs audio
+
+   -  This example does not provide enough information for QEMU to
+      launch. While the command does provide a root filesystem type, it
+      must also minimally provide a `MACHINE`, `KERNEL`, or `VM` option.
+      ::
+
+         $ runqemu ext4
+
+   -  This example specifies to boot a virtual machine image
+      (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu``
+      determines the QEMU architecture (`MACHINE`) to be "qemux86-64" and
+      the root filesystem type to be "vmdk".
+      ::
+
+         $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
+
+Switching Between Consoles
+==========================
+
+When booting or running QEMU, you can switch between supported consoles
+by using Ctrl+Alt+number. For example, Ctrl+Alt+3 switches you to the
+serial console as long as that console is enabled. Being able to switch
+consoles is helpful, for example, if the main QEMU console breaks for
+some reason.
+
+.. note::
+
+   Usually, "2" gets you to the main console and "3" gets you to the
+   serial console.
+
+Removing the Splash Screen
+==========================
+
+You can remove the splash screen when QEMU is booting by using Alt+left.
+Removing the splash screen allows you to see what is happening in the
+background.
+
+Disabling the Cursor Grab
+=========================
+
+The default QEMU integration captures the cursor within the main window.
+It does this since standard mouse devices only provide relative input
+and not absolute coordinates. You then have to break out of the grab
+using the "Ctrl+Alt" key combination. However, the Yocto Project's
+integration of QEMU enables the wacom USB touch pad driver by default to
+allow input of absolute coordinates. This default means that the mouse
+can enter and leave the main window without the grab taking effect
+leading to a better user experience.
+
+.. _qemu-running-under-a-network-file-system-nfs-server:
+
+Running Under a Network File System (NFS) Server
+================================================
+
+One method for running QEMU is to run it on an NFS server. This is
+useful when you need to access the same file system from both the build
+and the emulated system at the same time. It is also worth noting that
+the system does not need root privileges to run. It uses a user space
+NFS server to avoid that. Follow these steps to set up for running QEMU
+using an NFS server.
+
+1. *Extract a Root Filesystem:* Once you are able to run QEMU in your
+   environment, you can use the ``runqemu-extract-sdk`` script, which is
+   located in the ``scripts`` directory along with the ``runqemu``
+   script.
+
+   The ``runqemu-extract-sdk`` takes a root filesystem tarball and
+   extracts it into a location that you specify. Here is an example that
+   takes a file system and extracts it to a directory named
+   ``test-nfs``:
+
+   .. code-block:: none
+
+      runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs
+
+2. *Start QEMU:* Once you have extracted the file system, you can run
+   ``runqemu`` normally with the additional location of the file system.
+   You can then also make changes to the files within ``./test-nfs`` and
+   see those changes appear in the image in real time. Here is an
+   example using the ``qemux86`` image:
+
+   .. code-block:: none
+
+      runqemu qemux86-64 ./test-nfs
+
+.. note::
+
+   Should you need to start, stop, or restart the NFS share, you can use
+   the following commands:
+
+   -  The following command starts the NFS share:
+      ::
+
+         runqemu-export-rootfs start file-system-location
+
+   -  The following command stops the NFS share:
+      ::
+
+         runqemu-export-rootfs stop file-system-location
+
+   -  The following command restarts the NFS share:
+      ::
+
+         runqemu-export-rootfs restart file-system-location
+
+.. _qemu-kvm-cpu-compatibility:
+
+QEMU CPU Compatibility Under KVM
+================================
+
+By default, the QEMU build compiles for and targets 64-bit and x86 Intel
+Core2 Duo processors and 32-bit x86 Intel Pentium II processors. QEMU
+builds for and targets these CPU types because they display a broad
+range of CPU feature compatibility with many commonly used CPUs.
+
+Despite this broad range of compatibility, the CPUs could support a
+feature that your host CPU does not support. Although this situation is
+not a problem when QEMU uses software emulation of the feature, it can
+be a problem when QEMU is running with KVM enabled. Specifically,
+software compiled with a certain CPU feature crashes when run on a CPU
+under KVM that does not support that feature. To work around this
+problem, you can override QEMU's runtime CPU setting by changing the
+``QB_CPU_KVM`` variable in ``qemuboot.conf`` in the
+:term:`Build Directory` ``deploy/image``
+directory. This setting specifies a ``-cpu`` option passed into QEMU in
+the ``runqemu`` script. Running ``qemu -cpu help`` returns a list of
+available supported CPU types.
+
+.. _qemu-dev-performance:
+
+QEMU Performance
+================
+
+Using QEMU to emulate your hardware can result in speed issues depending
+on the target and host architecture mix. For example, using the
+``qemux86`` image in the emulator on an Intel-based 32-bit (x86) host
+machine is fast because the target and host architectures match. On the
+other hand, using the ``qemuarm`` image on the same Intel-based host can
+be slower. But, you still achieve faithful emulation of ARM-specific
+issues.
+
+To speed things up, the QEMU images support using ``distcc`` to call a
+cross-compiler outside the emulated system. If you used ``runqemu`` to
+start QEMU, and the ``distccd`` application is present on the host
+system, any BitBake cross-compiling toolchain available from the build
+system is automatically used from within QEMU simply by calling
+``distcc``. You can accomplish this by defining the cross-compiler
+variable (e.g. ``export CC="distcc"``). Alternatively, if you are using
+a suitable SDK image or the appropriate stand-alone toolchain is
+present, the toolchain is also automatically used.
+
+.. note::
+
+   Several mechanisms exist that let you connect to the system running
+   on the QEMU emulator:
+
+   -  QEMU provides a framebuffer interface that makes standard consoles
+      available.
+
+   -  Generally, headless embedded devices have a serial port. If so,
+      you can configure the operating system of the running image to use
+      that port to run a console. The connection uses standard IP
+      networking.
+
+   -  SSH servers exist in some QEMU images. The ``core-image-sato``
+      QEMU image has a Dropbear secure shell (SSH) server that runs with
+      the root password disabled. The ``core-image-full-cmdline`` and
+      ``core-image-lsb`` QEMU images have OpenSSH instead of Dropbear.
+      Including these SSH servers allow you to use standard ``ssh`` and
+      ``scp`` commands. The ``core-image-minimal`` QEMU image, however,
+      contains no SSH server.
+
+   -  You can use a provided, user-space NFS server to boot the QEMU
+      session using a local copy of the root filesystem on the host. In
+      order to make this connection, you must extract a root filesystem
+      tarball by using the ``runqemu-extract-sdk`` command. After
+      running the command, you must then point the ``runqemu`` script to
+      the extracted directory instead of a root filesystem image file.
+      See the "`Running Under a Network File System (NFS)
+      Server <#qemu-running-under-a-network-file-system-nfs-server>`__"
+      section for more information.
+
+.. _qemu-dev-command-line-syntax:
+
+QEMU Command-Line Syntax
+========================
+
+The basic ``runqemu`` command syntax is as follows:
+::
+
+   $ runqemu [option ] [...]
+
+Based on what you provide on the command line, ``runqemu`` does a
+good job of figuring out what you are trying to do. For example, by
+default, QEMU looks for the most recently built image according to the
+timestamp when it needs to look for an image. Minimally, through the use
+of options, you must provide either a machine name, a virtual machine
+image (``*wic.vmdk``), or a kernel image (``*.bin``).
+
+Following is the command-line help output for the ``runqemu`` command:
+::
+
+   $ runqemu --help
+
+   Usage: you can run this script with any valid combination
+   of the following environment variables (in any order):
+     KERNEL - the kernel image file to use
+     ROOTFS - the rootfs image file or nfsroot directory to use
+     MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
+     Simplified QEMU command-line options can be passed with:
+       nographic - disable video console
+       serial - enable a serial console on /dev/ttyS0
+       slirp - enable user networking, no root privileges is required
+       kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
+       kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
+       publicvnc - enable a VNC server open to all hosts
+       audio - enable audio
+       [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
+     tcpserial=<port> - specify tcp serial port number
+     biosdir=<dir> - specify custom bios dir
+     biosfilename=<filename> - specify bios filename
+     qemuparams=<xyz> - specify custom parameters to QEMU
+     bootparams=<xyz> - specify custom kernel parameters during boot
+     help, -h, --help: print this text
+
+   Examples:
+     runqemu
+     runqemu qemuarm
+     runqemu tmp/deploy/images/qemuarm
+     runqemu tmp/deploy/images/qemux86/<qemuboot.conf>
+     runqemu qemux86-64 core-image-sato ext4
+     runqemu qemux86-64 wic-image-minimal wic
+     runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
+     runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
+     runqemu qemux86 qemuparams="-m 256"
+     runqemu qemux86 bootparams="psplash=false"
+     runqemu path/to/<image>-<machine>.wic
+     runqemu path/to/<image>-<machine>.wic.vmdk
+
+.. _qemu-dev-runqemu-command-line-options:
+
+``runqemu`` Command-Line Options
+================================
+
+Following is a description of ``runqemu`` options you can provide on the
+command line:
+
+.. note::
+
+   If you do provide some "illegal" option combination or perhaps you do
+   not provide enough in the way of options, ``runqemu``
+   provides appropriate error messaging to help you correct the problem.
+
+-  `QEMUARCH`: The QEMU machine architecture, which must be "qemuarm",
+   "qemuarm64", "qemumips", "qemumips64", "qemuppc", "qemux86", or
+   "qemux86-64".
+
+-  `VM`: The virtual machine image, which must be a ``.wic.vmdk``
+   file. Use this option when you want to boot a ``.wic.vmdk`` image.
+   The image filename you provide must contain one of the following
+   strings: "qemux86-64", "qemux86", "qemuarm", "qemumips64",
+   "qemumips", "qemuppc", or "qemush4".
+
+-  `ROOTFS`: A root filesystem that has one of the following filetype
+   extensions: "ext2", "ext3", "ext4", "jffs2", "nfs", or "btrfs". If
+   the filename you provide for this option uses "nfs", it must provide
+   an explicit root filesystem path.
+
+-  `KERNEL`: A kernel image, which is a ``.bin`` file. When you provide a
+   ``.bin`` file, ``runqemu`` detects it and assumes the file is a
+   kernel image.
+
+-  `MACHINE`: The architecture of the QEMU machine, which must be one of
+   the following: "qemux86", "qemux86-64", "qemuarm", "qemuarm64",
+   "qemumips", "qemumips64", or "qemuppc". The MACHINE and QEMUARCH
+   options are basically identical. If you do not provide a MACHINE
+   option, ``runqemu`` tries to determine it based on other options.
+
+-  ``ramfs``: Indicates you are booting an initial RAM disk (initramfs)
+   image, which means the ``FSTYPE`` is ``cpio.gz``.
+
+-  ``iso``: Indicates you are booting an ISO image, which means the
+   ``FSTYPE`` is ``.iso``.
+
+-  ``nographic``: Disables the video console, which sets the console to
+   "ttys0". This option is useful when you have logged into a server and
+   you do not want to disable forwarding from the X Window System (X11)
+   to your workstation or laptop.
+
+-  ``serial``: Enables a serial console on ``/dev/ttyS0``.
+
+-  ``biosdir``: Establishes a custom directory for BIOS, VGA BIOS and
+   keymaps.
+
+-  ``biosfilename``: Establishes a custom BIOS name.
+
+-  ``qemuparams=\"xyz\"``: Specifies custom QEMU parameters. Use this
+   option to pass options other than the simple "kvm" and "serial"
+   options.
+
+-  ``bootparams=\"xyz\"``: Specifies custom boot parameters for the
+   kernel.
+
+-  ``audio``: Enables audio in QEMU. The MACHINE option must be either
+   "qemux86" or "qemux86-64" in order for audio to be enabled.
+   Additionally, the ``snd_intel8x0`` or ``snd_ens1370`` driver must be
+   installed in linux guest.
+
+-  ``slirp``: Enables "slirp" networking, which is a different way of
+   networking that does not need root access but also is not as easy to
+   use or comprehensive as the default.
+
+-  ``kvm``: Enables KVM when running "qemux86" or "qemux86-64" QEMU
+   architectures. For KVM to work, all the following conditions must be
+   met:
+
+   -  Your MACHINE must be either qemux86" or "qemux86-64".
+
+   -  Your build host has to have the KVM modules installed, which are
+      ``/dev/kvm``.
+
+   -  The build host ``/dev/kvm`` directory has to be both writable and
+      readable.
+
+-  ``kvm-vhost``: Enables KVM with VHOST support when running "qemux86"
+   or "qemux86-64" QEMU architectures. For KVM with VHOST to work, the
+   following conditions must be met:
+
+   -  `kvm <#kvm-cond>`__ option conditions must be met.
+
+   -  Your build host has to have virtio net device, which are
+      ``/dev/vhost-net``.
+
+   -  The build host ``/dev/vhost-net`` directory has to be either
+      readable or writable and "slirp-enabled".
+
+-  ``publicvnc``: Enables a VNC server open to all hosts.

documentation/dev-manual/dev-manual-qemu.xml

@@ -1,690 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<chapter id='dev-manual-qemu'>
-
-<title>Using the Quick EMUlator (QEMU)</title>
-
-    <para>
-        The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
-        Open Source project as part of the Yocto Project development "tool
-        set".
-        This chapter provides both procedures that show you how to use the
-        Quick EMUlator (QEMU) and other QEMU information helpful for
-        development purposes.
-    </para>
-
-    <section id='qemu-dev-overview'>
-        <title>Overview</title>
-
-        <para>
-            Within the context of the Yocto Project, QEMU is an
-            emulator and virtualization machine that allows you to run a
-            complete image you have built using the Yocto Project as just
-            another task on your build system.
-            QEMU is useful for running and testing images and applications on
-            supported Yocto Project architectures without having actual
-            hardware.
-            Among other things, the Yocto Project uses QEMU to run automated
-            Quality Assurance (QA) tests on final images shipped with each
-            release.
-            <note>
-                This implementation is not the same as QEMU in general.
-            </note>
-            This section provides a brief reference for the Yocto Project
-            implementation of QEMU.
-        </para>
-
-        <para>
-            For official information and documentation on QEMU in general, see
-            the following references:
-            <itemizedlist>
-                <listitem><para>
-                    <emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
-                    The official website for the QEMU Open Source project.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
-                    The QEMU user manual.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-
-    <section id='qemu-running-qemu'>
-        <title>Running QEMU</title>
-
-        <para>
-            To use QEMU, you need to have QEMU installed and initialized as
-            well as have the proper artifacts (i.e. image files and root
-            filesystems) available.
-            Follow these general steps to run QEMU:
-            <orderedlist>
-                <listitem><para>
-                    <emphasis>Install QEMU:</emphasis>
-                    QEMU is made available with the Yocto Project a number of
-                    ways.
-                    One method is to install a Software Development Kit (SDK).
-                    See
-                    "<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
-                    section in the Yocto Project Application Development and
-                    the Extensible Software Development Kit (eSDK) manual
-                    for information on how to install QEMU.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Setting Up the Environment:</emphasis>
-                    How you set up the QEMU environment depends on how you
-                    installed QEMU:
-                    <itemizedlist>
-                        <listitem><para>
-                            If you cloned the <filename>poky</filename>
-                            repository or you downloaded and unpacked a
-                            Yocto Project release tarball, you can source
-                            the build environment script (i.e.
-                            <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>):
-                            <literallayout class='monospaced'>
-     $ cd ~/poky
-     $ source oe-init-build-env
-                            </literallayout>
-                            </para></listitem>
-                        <listitem><para>
-                            If you installed a cross-toolchain, you can
-                            run the script that initializes the toolchain.
-                            For example, the following commands run the
-                            initialization script from the default
-                            <filename>poky_sdk</filename> directory:
-                            <literallayout class='monospaced'>
-     . ~/poky_sdk/environment-setup-core2-64-poky-linux
-                            </literallayout>
-                            </para></listitem>
-                    </itemizedlist>
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Ensure the Artifacts are in Place:</emphasis>
-                    You need to be sure you have a pre-built kernel that
-                    will boot in QEMU.
-                    You also need the target root filesystem for your target
-                    machine’s architecture:
-                    <itemizedlist>
-                        <listitem><para>
-                            If you have previously built an image for QEMU
-                            (e.g. <filename>qemux86</filename>,
-                            <filename>qemuarm</filename>, and so forth),
-                            then the artifacts are in place in your
-                            <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
-                            </para></listitem>
-                        <listitem><para>
-                            If you have not built an image, you can go to the
-                            <ulink url='&YOCTO_MACHINES_DL_URL;'>machines/qemu</ulink>
-                            area and download a pre-built image that matches
-                            your architecture and can be run on QEMU.
-                            </para></listitem>
-                    </itemizedlist></para>
-
-                    <para>See the
-                    "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>"
-                    section in the Yocto Project Application Development and
-                    the Extensible Software Development Kit (eSDK) manual
-                    for information on how to extract a root filesystem.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Run QEMU:</emphasis>
-                    The basic <filename>runqemu</filename> command syntax is as
-                    follows:
-                    <literallayout class='monospaced'>
-     $ runqemu [<replaceable>option</replaceable> ]  [...]
-                    </literallayout>
-                    Based on what you provide on the command line,
-                    <filename>runqemu</filename> does a good job of figuring
-                    out what you are trying to do.
-                    For example, by default, QEMU looks for the most recently
-                    built image according to the timestamp when it needs to
-                    look for an image.
-                    Minimally, through the use of options, you must provide
-                    either a machine name, a virtual machine image
-                    (<filename>*wic.vmdk</filename>), or a kernel image
-                    (<filename>*.bin</filename>).</para>
-
-                    <para>Here are some additional examples to help illustrate
-                    further QEMU:
-                    <itemizedlist>
-                        <listitem><para>
-                            This example starts QEMU with
-                            <replaceable>MACHINE</replaceable> set to "qemux86-64".
-                            Assuming a standard
-                            <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
-                            <filename>runqemu</filename> automatically finds the
-                            <filename>bzImage-qemux86-64.bin</filename> image file and
-                            the
-                            <filename>core-image-minimal-qemux86-64-20200218002850.rootfs.ext4</filename>
-                            (assuming the current build created a
-                            <filename>core-image-minimal</filename> image).
-                            <note>
-                            When more than one image with the same name exists, QEMU finds
-                            and uses the most recently built image according to the
-                            timestamp.
-                            </note>
-                            <literallayout class='monospaced'>
-     $ runqemu qemux86-64
-                            </literallayout>
-                            </para></listitem>
-                        <listitem><para>
-                            This example produces the exact same results as the
-                            previous example.
-                            This command, however, specifically provides the image
-                            and root filesystem type.
-                            <literallayout class='monospaced'>
-     $ runqemu qemux86-64 core-image-minimal ext4
-                            </literallayout>
-                            </para></listitem>
-                        <listitem><para>
-                            This example specifies to boot an initial RAM disk image
-                            and to enable audio in QEMU.
-                            For this case, <filename>runqemu</filename> set the
-                            internal variable <filename>FSTYPE</filename> to
-                            "cpio.gz".
-                            Also, for audio to be enabled, an appropriate driver must
-                            be installed (see the previous description for the
-                            <filename>audio</filename> option for more information).
-                            <literallayout class='monospaced'>
-     $ runqemu qemux86-64 ramfs audio
-                            </literallayout>
-                            </para></listitem>
-                        <listitem><para>
-                            This example does not provide enough information for
-                            QEMU to launch.
-                            While the command does provide a root filesystem type, it
-                            must also minimally provide a
-                            <replaceable>MACHINE</replaceable>,
-                            <replaceable>KERNEL</replaceable>, or
-                            <replaceable>VM</replaceable> option.
-                            <literallayout class='monospaced'>
-     $ runqemu ext4
-                            </literallayout>
-                            </para></listitem>
-                        <listitem><para>
-                            This example specifies to boot a virtual machine
-                            image (<filename>.wic.vmdk</filename> file).
-                            From the <filename>.wic.vmdk</filename>,
-                            <filename>runqemu</filename> determines the QEMU
-                            architecture (<replaceable>MACHINE</replaceable>) to be
-                            "qemux86-64" and the root filesystem type to be "vmdk".
-                            <literallayout class='monospaced'>
-     $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
-                            </literallayout>
-                            </para></listitem>
-                    </itemizedlist>
-                    </para></listitem>
-            </orderedlist>
-        </para>
-    </section>
-
-    <section id='switching-between-consoles'>
-        <title>Switching Between Consoles</title>
-
-        <para>
-            When booting or running QEMU, you can switch between
-            supported consoles by using
-            Ctrl+Alt+<replaceable>number</replaceable>.
-            For example, Ctrl+Alt+3 switches you to the serial console
-            as long as that console is enabled.
-            Being able to switch consoles is helpful, for example, if
-            the main QEMU console breaks for some reason.
-            <note>
-                Usually, "2" gets you to the main console and "3"
-                gets you to the serial console.
-            </note>
-        </para>
-    </section>
-
-    <section id='removing-the-splash-screen'>
-        <title>Removing the Splash Screen</title>
-
-        <para>
-            You can remove the splash screen when QEMU is booting by
-            using Alt+left.
-            Removing the splash screen allows you to see what is
-            happening in the background.
-        </para>
-    </section>
-
-    <section id='disabling-the-cursor-grab'>
-        <title>Disabling the Cursor Grab</title>
-
-        <para>
-            The default QEMU integration captures the cursor within the
-            main window.
-            It does this since standard mouse devices only provide
-            relative input and not absolute coordinates.
-            You then have to break out of the grab using the "Ctrl+Alt"
-            key combination.
-            However, the Yocto Project's integration of QEMU enables
-            the wacom USB touch pad driver by default to allow input
-            of absolute coordinates.
-            This default means that the mouse can enter and leave the
-            main window without the grab taking effect leading to a
-            better user experience.
-        </para>
-    </section>
-
-    <section id='qemu-running-under-a-network-file-system-nfs-server'>
-        <title>Running Under a Network File System (NFS) Server</title>
-
-        <para>
-            One method for running QEMU is to run it on an NFS server.
-            This is useful when you need to access the same file system
-            from both the build and the emulated system at the same time.
-            It is also worth noting that the system does not need root
-            privileges to run.
-            It uses a user space NFS server to avoid that.
-            Follow these steps to set up for running QEMU using an NFS
-            server.
-            <orderedlist>
-                <listitem><para>
-                    <emphasis>Extract a Root Filesystem:</emphasis>
-                    Once you are able to run QEMU in your environment, you can
-                    use the <filename>runqemu-extract-sdk</filename> script,
-                    which is located in the <filename>scripts</filename>
-                    directory along with the <filename>runqemu</filename>
-                    script.</para>
-
-                    <para>The <filename>runqemu-extract-sdk</filename> takes a
-                    root filesystem tarball and extracts it into a location
-                    that you specify.
-                    Here is an example that takes a file system and
-                    extracts it to a directory named
-                    <filename>test-nfs</filename>:
-                    <literallayout class='monospaced'>
-     runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs
-                    </literallayout>
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Start QEMU:</emphasis>
-                    Once you have extracted the file system, you can run
-                    <filename>runqemu</filename> normally with the additional
-                    location of the file system.
-                    You can then also make changes to the files within
-                    <filename>./test-nfs</filename> and see those changes
-                    appear in the image in real time.
-                    Here is an example using the <filename>qemux86</filename>
-                    image:
-                    <literallayout class='monospaced'>
-     runqemu qemux86-64 ./test-nfs
-                    </literallayout>
-                    </para></listitem>
-            </orderedlist>
-            <note>
-                <para>
-                    Should you need to start, stop, or restart the NFS share,
-                    you can use the following commands:
-                    <itemizedlist>
-                        <listitem><para>
-                            The following command starts the NFS share:
-                            <literallayout class='monospaced'>
-     runqemu-export-rootfs start <replaceable>file-system-location</replaceable>
-                            </literallayout>
-                            </para></listitem>
-                        <listitem><para>
-                            The following command stops the NFS share:
-                            <literallayout class='monospaced'>
-         runqemu-export-rootfs stop <replaceable>file-system-location</replaceable>
-                            </literallayout>
-                            </para></listitem>
-                        <listitem><para>
-                            The following command restarts the NFS share:
-                            <literallayout class='monospaced'>
-     runqemu-export-rootfs restart <replaceable>file-system-location</replaceable>
-                            </literallayout>
-                            </para></listitem>
-                    </itemizedlist>
-                </para>
-            </note>
-        </para>
-    </section>
-
-    <section id='qemu-kvm-cpu-compatibility'>
-        <title>QEMU CPU Compatibility Under KVM</title>
-
-        <para>
-            By default, the QEMU build compiles for and targets 64-bit and x86
-            <trademark class='registered'>Intel</trademark> <trademark class='trademark'>Core</trademark>2
-            Duo processors and 32-bit x86
-            <trademark class='registered'>Intel</trademark> <trademark class='registered'>Pentium</trademark>
-            II processors.
-            QEMU builds for and targets these CPU types because they display
-            a broad range of CPU feature compatibility with many commonly
-            used CPUs.
-        </para>
-
-        <para>
-            Despite this broad range of compatibility, the CPUs could support
-            a feature that your host CPU does not support.
-            Although this situation is not a problem when QEMU uses software
-            emulation of the feature, it can be a problem when QEMU is
-            running with KVM enabled.
-            Specifically, software compiled with a certain CPU feature crashes
-            when run on a CPU under KVM that does not support that feature.
-            To work around this problem, you can override QEMU's runtime CPU
-            setting by changing the <filename>QB_CPU_KVM</filename>
-            variable in <filename>qemuboot.conf</filename> in the
-            <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink>
-            <filename>deploy/image</filename> directory.
-            This setting specifies a <filename>-cpu</filename> option
-            passed into QEMU in the <filename>runqemu</filename> script.
-            Running <filename>qemu -cpu help</filename> returns a list of
-            available supported CPU types.
-        </para>
-    </section>
-
-    <section id='qemu-dev-performance'>
-        <title>QEMU Performance</title>
-
-        <para>
-            Using QEMU to emulate your hardware can result in speed issues
-            depending on the target and host architecture mix.
-            For example, using the <filename>qemux86</filename> image in the
-            emulator on an Intel-based 32-bit (x86) host machine is fast
-            because the target and host architectures match.
-            On the other hand, using the <filename>qemuarm</filename> image
-            on the same Intel-based host can be slower.
-            But, you still achieve faithful emulation of ARM-specific issues.
-        </para>
-
-        <para>
-            To speed things up, the QEMU images support using
-            <filename>distcc</filename> to call a cross-compiler outside the
-            emulated system.
-            If you used <filename>runqemu</filename> to start QEMU, and the
-            <filename>distccd</filename> application is present on the host
-            system, any BitBake cross-compiling toolchain available from the
-            build system is automatically used from within QEMU simply by
-            calling <filename>distcc</filename>.
-            You can accomplish this by defining the cross-compiler variable
-            (e.g. <filename>export CC="distcc"</filename>).
-            Alternatively, if you are using a suitable SDK image or the
-            appropriate stand-alone toolchain is present, the toolchain is
-            also automatically used.
-            <note>
-                Several mechanisms exist that let you connect to the system
-                running on the QEMU emulator:
-                <itemizedlist>
-                    <listitem><para>
-                        QEMU provides a framebuffer interface that makes
-                        standard consoles available.
-                        </para></listitem>
-                    <listitem><para>
-                        Generally, headless embedded devices have a serial port.
-                        If so, you can configure the operating system of the
-                        running image to use that port to run a console.
-                        The connection uses standard IP networking.
-                        </para></listitem>
-                    <listitem><para>
-                        SSH servers exist in some QEMU images.
-                        The <filename>core-image-sato</filename> QEMU image
-                        has a Dropbear secure shell (SSH) server that runs
-                        with the root password disabled.
-                        The <filename>core-image-full-cmdline</filename> and
-                        <filename>core-image-lsb</filename> QEMU images
-                        have OpenSSH instead of Dropbear.
-                        Including these SSH servers allow you to use standard
-                        <filename>ssh</filename> and <filename>scp</filename>
-                        commands.
-                        The <filename>core-image-minimal</filename> QEMU image,
-                        however, contains no SSH server.
-                        </para></listitem>
-                    <listitem><para>
-                        You can use a provided, user-space NFS server to boot
-                        the QEMU session using a local copy of the root
-                        filesystem on the host.
-                        In order to make this connection, you must extract a
-                        root filesystem tarball by using the
-                        <filename>runqemu-extract-sdk</filename> command.
-                        After running the command, you must then point the
-                        <filename>runqemu</filename>
-                        script to the extracted directory instead of a root
-                        filesystem image file.
-                        See the
-                        "<link linkend='qemu-running-under-a-network-file-system-nfs-server'>Running Under a Network File System (NFS) Server</link>"
-                        section for more information.
-                        </para></listitem>
-                </itemizedlist>
-            </note>
-        </para>
-    </section>
-
-    <section id='qemu-dev-command-line-syntax'>
-        <title>QEMU Command-Line Syntax</title>
-
-        <para>
-            The basic <filename>runqemu</filename> command syntax is as
-            follows:
-            <literallayout class='monospaced'>
-     $ runqemu [<replaceable>option</replaceable> ]  [...]
-            </literallayout>
-            Based on what you provide on the command line,
-            <filename>runqemu</filename> does a good job of figuring out what
-            you are trying to do.
-            For example, by default, QEMU looks for the most recently built
-            image according to the timestamp when it needs to look for an
-            image.
-            Minimally, through the use of options, you must provide either
-            a machine name, a virtual machine image
-            (<filename>*wic.vmdk</filename>), or a kernel image
-            (<filename>*.bin</filename>).
-        </para>
-
-        <para>
-            Following is the command-line help output for the
-            <filename>runqemu</filename> command:
-            <literallayout class='monospaced'>
-     $ runqemu --help
-
-     Usage: you can run this script with any valid combination
-     of the following environment variables (in any order):
-       KERNEL - the kernel image file to use
-       ROOTFS - the rootfs image file or nfsroot directory to use
-       MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
-       Simplified QEMU command-line options can be passed with:
-         nographic - disable video console
-         serial - enable a serial console on /dev/ttyS0
-         slirp - enable user networking, no root privileges is required
-         kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
-         kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
-         publicvnc - enable a VNC server open to all hosts
-         audio - enable audio
-         [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
-       tcpserial=&lt;port&gt; - specify tcp serial port number
-       biosdir=&lt;dir&gt; - specify custom bios dir
-       biosfilename=&lt;filename&gt; - specify bios filename
-       qemuparams=&lt;xyz&gt; - specify custom parameters to QEMU
-       bootparams=&lt;xyz&gt; - specify custom kernel parameters during boot
-       help, -h, --help: print this text
-
-     Examples:
-       runqemu
-       runqemu qemuarm
-       runqemu tmp/deploy/images/qemuarm
-       runqemu tmp/deploy/images/qemux86/&lt;qemuboot.conf&gt;
-       runqemu qemux86-64 core-image-sato ext4
-       runqemu qemux86-64 wic-image-minimal wic
-       runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
-       runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
-       runqemu qemux86 qemuparams="-m 256"
-       runqemu qemux86 bootparams="psplash=false"
-       runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic
-       runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic.vmdk
-            </literallayout>
-        </para>
-    </section>
-
-    <section id='qemu-dev-runqemu-command-line-options'>
-        <title><filename>runqemu</filename> Command-Line Options</title>
-
-        <para>
-            Following is a description of <filename>runqemu</filename>
-            options you can provide on the command line:
-            <note><title>Tip</title>
-                If you do provide some "illegal" option combination or perhaps
-                you do not provide enough in the way of options,
-                <filename>runqemu</filename> provides appropriate error
-                messaging to help you correct the problem.
-            </note>
-            <itemizedlist>
-                <listitem><para>
-                    <replaceable>QEMUARCH</replaceable>:
-                    The QEMU machine architecture, which must be "qemuarm",
-                    "qemuarm64", "qemumips", "qemumips64", "qemuppc",
-                    "qemux86", or "qemux86-64".
-                    </para></listitem>
-                <listitem><para>
-                    <filename><replaceable>VM</replaceable></filename>:
-                    The virtual machine image, which must be a
-                    <filename>.wic.vmdk</filename> file.
-                    Use this option when you want to boot a
-                    <filename>.wic.vmdk</filename> image.
-                    The image filename you provide must contain one of the
-                    following strings: "qemux86-64", "qemux86", "qemuarm",
-                    "qemumips64", "qemumips", "qemuppc", or "qemush4".
-                    </para></listitem>
-                <listitem><para>
-                    <replaceable>ROOTFS</replaceable>:
-                    A root filesystem that has one of the following
-                    filetype extensions: "ext2", "ext3", "ext4", "jffs2",
-                    "nfs", or "btrfs".
-                    If the filename you provide for this option uses “nfs”, it
-                    must provide an explicit root filesystem path.
-                    </para></listitem>
-                <listitem><para>
-                    <replaceable>KERNEL</replaceable>:
-                    A kernel image, which is a <filename>.bin</filename> file.
-                    When you provide a <filename>.bin</filename> file,
-                    <filename>runqemu</filename> detects it and assumes the
-                    file is a kernel image.
-                    </para></listitem>
-                <listitem><para>
-                    <replaceable>MACHINE</replaceable>:
-                    The architecture of the QEMU machine, which must be one
-                    of the following: "qemux86", "qemux86-64", "qemuarm",
-                    "qemuarm64", "qemumips", “qemumips64", or "qemuppc".
-                    The <replaceable>MACHINE</replaceable> and
-                    <replaceable>QEMUARCH</replaceable> options are basically
-                    identical.
-                    If you do not provide a <replaceable>MACHINE</replaceable>
-                    option, <filename>runqemu</filename> tries to determine
-                    it based on other options.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>ramfs</filename>:
-                    Indicates you are booting an initial RAM disk (initramfs)
-                    image, which means the <filename>FSTYPE</filename> is
-                    <filename>cpio.gz</filename>.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>iso</filename>:
-                    Indicates you are booting an ISO image, which means the
-                    <filename>FSTYPE</filename> is
-                    <filename>.iso</filename>.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>nographic</filename>:
-                    Disables the video console, which sets the console to
-                    "ttys0".
-                    This option is useful when you have logged into a server
-                    and you do not want to disable forwarding from the
-                    X Window System (X11) to your workstation or laptop.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>serial</filename>:
-                    Enables a serial console on
-                    <filename>/dev/ttyS0</filename>.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>biosdir</filename>:
-                    Establishes a custom directory for BIOS, VGA BIOS and
-                    keymaps.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>biosfilename</filename>:
-                    Establishes a custom BIOS name.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
-                    Specifies custom QEMU parameters.
-                    Use this option to pass options other than the simple
-                    "kvm" and "serial" options.
-                    </para></listitem>
-                <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
-                    Specifies custom boot parameters for the kernel.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>audio</filename>:
-                    Enables audio in QEMU.
-                    The <replaceable>MACHINE</replaceable> option must be
-                    either "qemux86" or "qemux86-64" in order for audio to be
-                    enabled.
-                    Additionally, the <filename>snd_intel8x0</filename>
-                    or <filename>snd_ens1370</filename> driver must be
-                    installed in linux guest.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>slirp</filename>:
-                    Enables "slirp" networking, which is a different way
-                    of networking that does not need root access
-                    but also is not as easy to use or comprehensive
-                    as the default.
-                    </para></listitem>
-                <listitem><para id='kvm-cond'>
-                    <filename>kvm</filename>:
-                    Enables KVM when running "qemux86" or "qemux86-64"
-                    QEMU architectures.
-                    For KVM to work, all the following conditions must be met:
-                    <itemizedlist>
-                        <listitem><para>
-                            Your <replaceable>MACHINE</replaceable> must be either
-qemux86" or "qemux86-64".
-                            </para></listitem>
-                        <listitem><para>
-                            Your build host has to have the KVM modules
-                            installed, which are
-                            <filename>/dev/kvm</filename>.
-                            </para></listitem>
-                        <listitem><para>
-                            The  build host <filename>/dev/kvm</filename>
-                            directory has to be both writable and readable.
-                            </para></listitem>
-                    </itemizedlist>
-                    </para></listitem>
-                <listitem><para>
-                    <filename>kvm-vhost</filename>:
-                    Enables KVM with VHOST support when running "qemux86"
-                    or "qemux86-64" QEMU architectures.
-                    For KVM with VHOST to work, the following conditions must
-                    be met:
-                    <itemizedlist>
-                        <listitem><para>
-                            <link linkend='kvm-cond'>kvm</link> option
-                            conditions must be met.
-                            </para></listitem>
-                        <listitem><para>
-                            Your build host has to have virtio net device, which
-                            are <filename>/dev/vhost-net</filename>.
-                            </para></listitem>
-                        <listitem><para>
-                            The build host <filename>/dev/vhost-net</filename>
-                            directory has to be either readable or writable
-                            and “slirp-enabled”.
-                            </para></listitem>
-                    </itemizedlist>
-                    </para></listitem>
-                <listitem><para>
-                    <filename>publicvnc</filename>:
-                    Enables a VNC server open to all hosts.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/dev-manual/dev-manual-start.rst

@@ -0,0 +1,925 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+***********************************
+Setting Up to Use the Yocto Project
+***********************************
+
+This chapter provides guidance on how to prepare to use the Yocto
+Project. You can learn about creating a team environment to develop
+using the Yocto Project, how to set up a :ref:`build
+host <dev-manual/dev-manual-start:preparing the build host>`, how to locate
+Yocto Project source repositories, and how to create local Git
+repositories.
+
+.. _usingpoky-changes-collaborate:
+
+Creating a Team Development Environment
+=======================================
+
+It might not be immediately clear how you can use the Yocto Project in a
+team development environment, or how to scale it for a large team of
+developers. You can adapt the Yocto Project to many different use cases
+and scenarios; however, this flexibility could cause difficulties if you
+are trying to create a working setup that scales effectively.
+
+To help you understand how to set up this type of environment, this
+section presents a procedure that gives you information that can help
+you get the results you want. The procedure is high-level and presents
+some of the project's most successful experiences, practices, solutions,
+and available technologies that have proved to work well in the past;
+however, keep in mind, the procedure here is simply a starting point.
+You can build off these steps and customize the procedure to fit any
+particular working environment and set of practices.
+
+1.  *Determine Who is Going to be Developing:* You first need to
+    understand who is going to be doing anything related to the Yocto
+    Project and determine their roles. Making this determination is
+    essential to completing subsequent steps, which are to get your
+    equipment together and set up your development environment's
+    hardware topology.
+
+    The following roles exist:
+
+    -  *Application Developer:* This type of developer does application
+       level work on top of an existing software stack.
+
+    -  *Core System Developer:* This type of developer works on the
+       contents of the operating system image itself.
+
+    -  *Build Engineer:* This type of developer manages Autobuilders and
+       releases. Depending on the specifics of the environment, not all
+       situations might need a Build Engineer.
+
+    -  *Test Engineer:* This type of developer creates and manages
+       automated tests that are used to ensure all application and core
+       system development meets desired quality standards.
+
+2.  *Gather the Hardware:* Based on the size and make-up of the team,
+    get the hardware together. Ideally, any development, build, or test
+    engineer uses a system that runs a supported Linux distribution.
+    These systems, in general, should be high performance (e.g. dual,
+    six-core Xeons with 24 Gbytes of RAM and plenty of disk space). You
+    can help ensure efficiency by having any machines used for testing
+    or that run Autobuilders be as high performance as possible.
+
+    .. note::
+
+       Given sufficient processing power, you might also consider
+       building Yocto Project development containers to be run under
+       Docker, which is described later.
+
+3.  *Understand the Hardware Topology of the Environment:* Once you
+    understand the hardware involved and the make-up of the team, you
+    can understand the hardware topology of the development environment.
+    You can get a visual idea of the machines and their roles across the
+    development environment.
+
+4.  *Use Git as Your Source Control Manager (SCM):* Keeping your
+    :term:`Metadata` (i.e. recipes,
+    configuration files, classes, and so forth) and any software you are
+    developing under the control of an SCM system that is compatible
+    with the OpenEmbedded build system is advisable. Of all of the SCMs
+    supported by BitBake, the Yocto Project team strongly recommends using
+    :ref:`overview-manual/overview-manual-development-environment:git`.
+    Git is a distributed system
+    that is easy to back up, allows you to work remotely, and then
+    connects back to the infrastructure.
+
+    .. note::
+
+       For information about BitBake, see the
+       :doc:`bitbake:index`.
+
+    It is relatively easy to set up Git services and create
+    infrastructure like :yocto_git:`/`, which is based on
+    server software called ``gitolite`` with ``cgit`` being used to
+    generate the web interface that lets you view the repositories. The
+    ``gitolite`` software identifies users using SSH keys and allows
+    branch-based access controls to repositories that you can control as
+    little or as much as necessary.
+
+    .. note::
+
+       The setup of these services is beyond the scope of this manual.
+       However, sites such as the following exist that describe how to
+       perform setup:
+
+       -  `Gitolite <https://gitolite.com>`__: Information for
+          ``gitolite``.
+
+       -  `Interfaces, frontends, and
+          tools <https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools>`__:
+          Documentation on how to create interfaces and frontends for
+          Git.
+
+5.  *Set up the Application Development Machines:* As mentioned earlier,
+    application developers are creating applications on top of existing
+    software stacks. Following are some best practices for setting up
+    machines used for application development:
+
+    -  Use a pre-built toolchain that contains the software stack
+       itself. Then, develop the application code on top of the stack.
+       This method works well for small numbers of relatively isolated
+       applications.
+
+    -  Keep your cross-development toolchains updated. You can do this
+       through provisioning either as new toolchain downloads or as
+       updates through a package update mechanism using ``opkg`` to
+       provide updates to an existing toolchain. The exact mechanics of
+       how and when to do this depend on local policy.
+
+    -  Use multiple toolchains installed locally into different
+       locations to allow development across versions.
+
+6.  *Set up the Core Development Machines:* As mentioned earlier, core
+    developers work on the contents of the operating system itself.
+    Following are some best practices for setting up machines used for
+    developing images:
+
+    -  Have the :term:`OpenEmbedded Build System` available on
+       the developer workstations so developers can run their own builds
+       and directly rebuild the software stack.
+
+    -  Keep the core system unchanged as much as possible and do your
+       work in layers on top of the core system. Doing so gives you a
+       greater level of portability when upgrading to new versions of
+       the core system or Board Support Packages (BSPs).
+
+    -  Share layers amongst the developers of a particular project and
+       contain the policy configuration that defines the project.
+
+7.  *Set up an Autobuilder:* Autobuilders are often the core of the
+    development environment. It is here that changes from individual
+    developers are brought together and centrally tested. Based on this
+    automated build and test environment, subsequent decisions about
+    releases can be made. Autobuilders also allow for "continuous
+    integration" style testing of software components and regression
+    identification and tracking.
+
+    See ":yocto_ab:`Yocto Project Autobuilder <>`" for more
+    information and links to buildbot. The Yocto Project team has found
+    this implementation works well in this role. A public example of
+    this is the Yocto Project Autobuilders, which the Yocto Project team
+    uses to test the overall health of the project.
+
+    The features of this system are:
+
+    -  Highlights when commits break the build.
+
+    -  Populates an :ref:`sstate
+       cache <overview-manual/overview-manual-concepts:shared state cache>` from which
+       developers can pull rather than requiring local builds.
+
+    -  Allows commit hook triggers, which trigger builds when commits
+       are made.
+
+    -  Allows triggering of automated image booting and testing under
+       the QuickEMUlator (QEMU).
+
+    -  Supports incremental build testing and from-scratch builds.
+
+    -  Shares output that allows developer testing and historical
+       regression investigation.
+
+    -  Creates output that can be used for releases.
+
+    -  Allows scheduling of builds so that resources can be used
+       efficiently.
+
+8.  *Set up Test Machines:* Use a small number of shared, high
+    performance systems for testing purposes. Developers can use these
+    systems for wider, more extensive testing while they continue to
+    develop locally using their primary development system.
+
+9.  *Document Policies and Change Flow:* The Yocto Project uses a
+    hierarchical structure and a pull model. Scripts exist to create and
+    send pull requests (i.e. ``create-pull-request`` and
+    ``send-pull-request``). This model is in line with other open source
+    projects where maintainers are responsible for specific areas of the
+    project and a single maintainer handles the final "top-of-tree"
+    merges.
+
+    .. note::
+
+       You can also use a more collective push model. The ``gitolite``
+       software supports both the push and pull models quite easily.
+
+    As with any development environment, it is important to document the
+    policy used as well as any main project guidelines so they are
+    understood by everyone. It is also a good idea to have
+    well-structured commit messages, which are usually a part of a
+    project's guidelines. Good commit messages are essential when
+    looking back in time and trying to understand why changes were made.
+
+    If you discover that changes are needed to the core layer of the
+    project, it is worth sharing those with the community as soon as
+    possible. Chances are if you have discovered the need for changes,
+    someone else in the community needs them also.
+
+10. *Development Environment Summary:* Aside from the previous steps,
+    some best practices exist within the Yocto Project development
+    environment. Consider the following:
+
+    -  Use :ref:`overview-manual/overview-manual-development-environment:git` as the source control
+       system.
+
+    -  Maintain your Metadata in layers that make sense for your
+       situation. See the ":ref:`overview-manual/overview-manual-yp-intro:the yocto project layer model`"
+       section in the Yocto Project Overview and Concepts Manual and the
+       ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
+       section for more information on layers.
+
+    -  Separate the project's Metadata and code by using separate Git
+       repositories. See the ":ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`"
+       section in the Yocto Project Overview and Concepts Manual for
+       information on these repositories. See the "`Locating Yocto
+       Project Source Files <#locating-yocto-project-source-files>`__"
+       section for information on how to set up local Git repositories
+       for related upstream Yocto Project Git repositories.
+
+    -  Set up the directory for the shared state cache
+       (:term:`SSTATE_DIR`) where
+       it makes sense. For example, set up the sstate cache on a system
+       used by developers in the same organization and share the same
+       source directories on their machines.
+
+    -  Set up an Autobuilder and have it populate the sstate cache and
+       source directories.
+
+    -  The Yocto Project community encourages you to send patches to the
+       project to fix bugs or add features. If you do submit patches,
+       follow the project commit guidelines for writing good commit
+       messages. See the
+       ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
+       section.
+
+    -  Send changes to the core sooner than later as others are likely
+       to run into the same issues. For some guidance on mailing lists
+       to use, see the list in the
+       ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
+       section. For a description
+       of the available mailing lists, see the ":ref:`resources-mailinglist`" section in
+       the Yocto Project Reference Manual.
+
+.. _dev-preparing-the-build-host:
+
+Preparing the Build Host
+========================
+
+This section provides procedures to set up a system to be used as your
+:term:`Build Host` for
+development using the Yocto Project. Your build host can be a native
+Linux machine (recommended), it can be a machine (Linux, Mac, or
+Windows) that uses `CROPS <https://github.com/crops/poky-container>`__,
+which leverages `Docker Containers <https://www.docker.com/>`__ or it
+can be a Windows machine capable of running Windows Subsystem For Linux
+v2 (WSL).
+
+.. note::
+
+   The Yocto Project is not compatible with
+   `Windows Subsystem for Linux v1 <https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux>`__.
+   It is compatible but not officially supported nor validated with
+   WSLv2. If you still decide to use WSL please upgrade to
+   `WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__.
+
+Once your build host is set up to use the Yocto Project, further steps
+are necessary depending on what you want to accomplish. See the
+following references for information on how to prepare for Board Support
+Package (BSP) development and kernel development:
+
+-  *BSP Development:* See the ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`"
+   section in the Yocto Project Board Support Package (BSP) Developer's
+   Guide.
+
+-  *Kernel Development:* See the ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`"
+   section in the Yocto Project Linux Kernel Development Manual.
+
+Setting Up a Native Linux Host
+------------------------------
+
+Follow these steps to prepare a native Linux machine as your Yocto
+Project Build Host:
+
+1. *Use a Supported Linux Distribution:* You should have a reasonably
+   current Linux-based host system. You will have the best results with
+   a recent release of Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS
+   as these releases are frequently tested against the Yocto Project and
+   officially supported. For a list of the distributions under
+   validation and their status, see the ":ref:`Supported Linux
+   Distributions <detailed-supported-distros>`"
+   section in the Yocto Project Reference Manual and the wiki page at
+   :yocto_wiki:`Distribution Support </wiki/Distribution_Support>`.
+
+2. *Have Enough Free Memory:* Your system should have at least 50 Gbytes
+   of free disk space for building images.
+
+3. *Meet Minimal Version Requirements:* The OpenEmbedded build system
+   should be able to run on any modern distribution that has the
+   following versions for Git, tar, Python and gcc.
+
+   -  Git 1.8.3.1 or greater
+
+   -  tar 1.28 or greater
+
+   -  Python 3.5.0 or greater.
+
+   -  gcc 5.0 or greater.
+
+   If your build host does not meet any of these three listed version
+   requirements, you can take steps to prepare the system so that you
+   can still use the Yocto Project. See the
+   ":ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions`"
+   section in the Yocto Project Reference Manual for information.
+
+4. *Install Development Host Packages:* Required development host
+   packages vary depending on your build host and what you want to do
+   with the Yocto Project. Collectively, the number of required packages
+   is large if you want to be able to cover all cases.
+
+   For lists of required packages for all scenarios, see the
+   ":ref:`ref-manual/ref-system-requirements:required packages for the build host`"
+   section in the Yocto Project Reference Manual.
+
+Once you have completed the previous steps, you are ready to continue
+using a given development path on your native Linux machine. If you are
+going to use BitBake, see the
+":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
+section. If you are going
+to use the Extensible SDK, see the ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto
+Project Application Development and the Extensible Software Development
+Kit (eSDK) manual. If you want to work on the kernel, see the :doc:`../kernel-dev/kernel-dev`. If you are going to use
+Toaster, see the ":doc:`../toaster-manual/toaster-manual-setup-and-use`"
+section in the Toaster User Manual.
+
+.. _setting-up-to-use-crops:
+
+Setting Up to Use CROss PlatformS (CROPS)
+-----------------------------------------
+
+With `CROPS <https://github.com/crops/poky-container>`__, which
+leverages `Docker Containers <https://www.docker.com/>`__, you can
+create a Yocto Project development environment that is operating system
+agnostic. You can set up a container in which you can develop using the
+Yocto Project on a Windows, Mac, or Linux machine.
+
+Follow these general steps to prepare a Windows, Mac, or Linux machine
+as your Yocto Project build host:
+
+1. *Determine What Your Build Host Needs:*
+   `Docker <https://www.docker.com/what-docker>`__ is a software
+   container platform that you need to install on the build host.
+   Depending on your build host, you might have to install different
+   software to support Docker containers. Go to the Docker installation
+   page and read about the platform requirements in "`Supported
+   Platforms <https://docs.docker.com/engine/install/#supported-platforms>`__"
+   your build host needs to run containers.
+
+2. *Choose What To Install:* Depending on whether or not your build host
+   meets system requirements, you need to install "Docker CE Stable" or
+   the "Docker Toolbox". Most situations call for Docker CE. However, if
+   you have a build host that does not meet requirements (e.g.
+   Pre-Windows 10 or Windows 10 "Home" version), you must install Docker
+   Toolbox instead.
+
+3. *Go to the Install Site for Your Platform:* Click the link for the
+   Docker edition associated with your build host's native software. For
+   example, if your build host is running Microsoft Windows Version 10
+   and you want the Docker CE Stable edition, click that link under
+   "Supported Platforms".
+
+4. *Install the Software:* Once you have understood all the
+   pre-requisites, you can download and install the appropriate
+   software. Follow the instructions for your specific machine and the
+   type of the software you need to install:
+
+   -  Install `Docker CE for
+      Windows <https://docs.docker.com/docker-for-windows/install/#install-docker-desktop-on-windows>`__
+      for Windows build hosts that meet requirements.
+
+   -  Install `Docker CE for
+      MacOs <https://docs.docker.com/docker-for-mac/install/#install-and-run-docker-desktop-on-mac>`__
+      for Mac build hosts that meet requirements.
+
+   -  Install `Docker Toolbox for
+      Windows <https://docs.docker.com/toolbox/toolbox_install_windows/>`__
+      for Windows build hosts that do not meet Docker requirements.
+
+   -  Install `Docker Toolbox for
+      MacOS <https://docs.docker.com/toolbox/toolbox_install_mac/>`__
+      for Mac build hosts that do not meet Docker requirements.
+
+   -  Install `Docker CE for
+      CentOS <https://docs.docker.com/install/linux/docker-ce/centos/>`__
+      for Linux build hosts running the CentOS distribution.
+
+   -  Install `Docker CE for
+      Debian <https://docs.docker.com/install/linux/docker-ce/debian/>`__
+      for Linux build hosts running the Debian distribution.
+
+   -  Install `Docker CE for
+      Fedora <https://docs.docker.com/install/linux/docker-ce/fedora/>`__
+      for Linux build hosts running the Fedora distribution.
+
+   -  Install `Docker CE for
+      Ubuntu <https://docs.docker.com/install/linux/docker-ce/ubuntu/>`__
+      for Linux build hosts running the Ubuntu distribution.
+
+5. *Optionally Orient Yourself With Docker:* If you are unfamiliar with
+   Docker and the container concept, you can learn more here -
+   https://docs.docker.com/get-started/.
+
+6. *Launch Docker or Docker Toolbox:* You should be able to launch
+   Docker or the Docker Toolbox and have a terminal shell on your
+   development host.
+
+7. *Set Up the Containers to Use the Yocto Project:* Go to
+   https://github.com/crops/docker-win-mac-docs/wiki and follow
+   the directions for your particular build host (i.e. Linux, Mac, or
+   Windows).
+
+   Once you complete the setup instructions for your machine, you have
+   the Poky, Extensible SDK, and Toaster containers available. You can
+   click those links from the page and learn more about using each of
+   those containers.
+
+Once you have a container set up, everything is in place to develop just
+as if you were running on a native Linux machine. If you are going to
+use the Poky container, see the
+":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
+section. If you are going to use the Extensible SDK container, see the
+":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto
+Project Application Development and the Extensible Software Development
+Kit (eSDK) manual. If you are going to use the Toaster container, see
+the ":doc:`../toaster-manual/toaster-manual-setup-and-use`"
+section in the Toaster User Manual.
+
+.. _setting-up-to-use-wsl:
+
+Setting Up to Use Windows Subsystem For Linux (WSLv2)
+-----------------------------------------------------
+
+With `Windows Subsystem for Linux
+(WSLv2) <https://docs.microsoft.com/en-us/windows/wsl/wsl2-about>`__,
+you can create a Yocto Project development environment that allows you
+to build on Windows. You can set up a Linux distribution inside Windows
+in which you can develop using the Yocto Project.
+
+Follow these general steps to prepare a Windows machine using WSLv2 as
+your Yocto Project build host:
+
+1. *Make sure your Windows 10 machine is capable of running WSLv2:*
+   WSLv2 is only available for Windows 10 builds > 18917. To check which
+   build version you are running, you may open a command prompt on
+   Windows and execute the command "ver".
+   ::
+
+      C:\Users\myuser> ver
+
+      Microsoft Windows [Version 10.0.19041.153]
+
+   If your build is capable of running
+   WSLv2 you may continue, for more information on this subject or
+   instructions on how to upgrade to WSLv2 visit `Windows 10
+   WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/wsl2-install>`__
+
+2. *Install the Linux distribution of your choice inside Windows 10:*
+   Once you know your version of Windows 10 supports WSLv2, you can
+   install the distribution of your choice from the Microsoft Store.
+   Open the Microsoft Store and search for Linux. While there are
+   several Linux distributions available, the assumption is that your
+   pick will be one of the distributions supported by the Yocto Project
+   as stated on the instructions for using a native Linux host. After
+   making your selection, simply click "Get" to download and install the
+   distribution.
+
+3. *Check your Linux distribution is using WSLv2:* Open a Windows
+   PowerShell and run:
+   ::
+
+      C:\WINDOWS\system32> wsl -l -v
+      NAME    STATE   VERSION
+      *Ubuntu Running 2
+
+   Note the version column which says the WSL version
+   being used by your distribution, on compatible systems, this can be
+   changed back at any point in time.
+
+4. *Optionally Orient Yourself on WSL:* If you are unfamiliar with WSL,
+   you can learn more here -
+   https://docs.microsoft.com/en-us/windows/wsl/wsl2-about.
+
+5. *Launch your WSL Distibution:* From the Windows start menu simply
+   launch your WSL distribution just like any other application.
+
+6. *Optimize your WSLv2 storage often:* Due to the way storage is
+   handled on WSLv2, the storage space used by the undelying Linux
+   distribution is not reflected immedately, and since bitbake heavily
+   uses storage, after several builds, you may be unaware you are
+   running out of space. WSLv2 uses a VHDX file for storage, this issue
+   can be easily avoided by manually optimizing this file often, this
+   can be done in the following way:
+
+   1. *Find the location of your VHDX file:* First you need to find the
+      distro app package directory, to achieve this open a Windows
+      Powershell as Administrator and run:
+      ::
+
+         C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName
+         PackageFamilyName
+         -----------------
+         CanonicalGroupLimited.UbuntuonWindows_79abcdefgh
+
+
+      You should now
+      replace the PackageFamilyName and your user on the following path
+      to find your VHDX file:
+      ::
+
+          ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
+          Mode                 LastWriteTime         Length Name
+          -a----         3/14/2020   9:52 PM    57418973184 ext4.vhdx
+
+      Your VHDX file path is:
+      ``C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx``
+
+   2. *Optimize your VHDX file:* Open a Windows Powershell as
+      Administrator to optimize your VHDX file, shutting down WSL first:
+      ::
+
+         C:\WINDOWS\system32> wsl --shutdown
+         C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full
+
+      A progress bar should be shown while optimizing the
+      VHDX file, and storage should now be reflected correctly on the
+      Windows Explorer.
+
+.. note::
+
+   The current implementation of WSLv2 does not have out-of-the-box
+   access to external devices such as those connected through a USB
+   port, but it automatically mounts your ``C:`` drive on ``/mnt/c/``
+   (and others), which you can use to share deploy artifacts to be later
+   flashed on hardware through Windows, but your build directory should
+   not reside inside this mountpoint.
+
+Once you have WSLv2 set up, everything is in place to develop just as if
+you were running on a native Linux machine. If you are going to use the
+Extensible SDK container, see the ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto
+Project Application Development and the Extensible Software Development
+Kit (eSDK) manual. If you are going to use the Toaster container, see
+the ":doc:`../toaster-manual/toaster-manual-setup-and-use`"
+section in the Toaster User Manual.
+
+Locating Yocto Project Source Files
+===================================
+
+This section shows you how to locate, fetch and configure the source
+files you'll need to work with the Yocto Project.
+
+.. note::
+
+   -  For concepts and introductory information about Git as it is used
+      in the Yocto Project, see the ":ref:`overview-manual/overview-manual-development-environment:git`"
+      section in the Yocto Project Overview and Concepts Manual.
+
+   -  For concepts on Yocto Project source repositories, see the
+      ":ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`"
+      section in the Yocto Project Overview and Concepts Manual."
+
+Accessing Source Repositories
+-----------------------------
+
+Working from a copy of the upstream :ref:`dev-manual/dev-manual-start:accessing source repositories` is the
+preferred method for obtaining and using a Yocto Project release. You
+can view the Yocto Project Source Repositories at
+:yocto_git:`/`. In particular, you can find the ``poky``
+repository at :yocto_git:`/cgit.cgi/poky`.
+
+Use the following procedure to locate the latest upstream copy of the
+``poky`` Git repository:
+
+1. *Access Repositories:* Open a browser and go to
+   :yocto_git:`/` to access the GUI-based interface into the
+   Yocto Project source repositories.
+
+2. *Select the Repository:* Click on the repository in which you are
+   interested (e.g. ``poky``).
+
+3. *Find the URL Used to Clone the Repository:* At the bottom of the
+   page, note the URL used to clone that repository
+   (e.g. :yocto_git:`/cgit.cgi/poky`).
+
+   .. note::
+
+      For information on cloning a repository, see the
+      ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" section.
+
+Accessing Index of Releases
+---------------------------
+
+Yocto Project maintains an Index of Releases area that contains related
+files that contribute to the Yocto Project. Rather than Git
+repositories, these files are tarballs that represent snapshots in time
+of a given component.
+
+.. note::
+
+   The recommended method for accessing Yocto Project components is to
+   use Git to clone the upstream repository and work from within that
+   locally cloned repository. The procedure in this section exists
+   should you desire a tarball snapshot of any given component.
+
+Follow these steps to locate and download a particular tarball:
+
+1. *Access the Index of Releases:* Open a browser and go to
+   :yocto_dl:`Index of Releases </releases>`. The
+   list represents released components (e.g. ``bitbake``, ``sato``, and
+   so on).
+
+   .. note::
+
+      The ``yocto`` directory contains the full array of released Poky
+      tarballs. The ``poky`` directory in the Index of Releases was
+      historically used for very early releases and exists now only for
+      retroactive completeness.
+
+2. *Select a Component:* Click on any released component in which you
+   are interested (e.g. ``yocto``).
+
+3. *Find the Tarball:* Drill down to find the associated tarball. For
+   example, click on ``yocto-&DISTRO;`` to view files associated with the
+   Yocto Project &DISTRO; release (e.g.
+   ``&YOCTO_POKY;.tar.bz2``, which is the
+   released Poky tarball).
+
+4. *Download the Tarball:* Click the tarball to download and save a
+   snapshot of the given component.
+
+Using the Downloads Page
+------------------------
+
+The :yocto_home:`Yocto Project Website <>` uses a "DOWNLOADS" page
+from which you can locate and download tarballs of any Yocto Project
+release. Rather than Git repositories, these files represent snapshot
+tarballs similar to the tarballs located in the Index of Releases
+described in the "`Accessing Index of
+Releases <#accessing-index-of-releases>`__" section.
+
+.. note::
+
+   The recommended method for accessing Yocto Project components is to
+   use Git to clone a repository and work from within that local
+   repository. The procedure in this section exists should you desire a
+   tarball snapshot of any given component.
+
+1. *Go to the Yocto Project Website:* Open The
+   :yocto_home:`Yocto Project Website <>` in your browser.
+
+2. *Get to the Downloads Area:* Select the "DOWNLOADS" item from the
+   pull-down "SOFTWARE" tab menu near the top of the page.
+
+3. *Select a Yocto Project Release:* Use the menu next to "RELEASE" to
+   display and choose a recent or past supported Yocto Project release
+   (e.g. &DISTRO_NAME_NO_CAP;, &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth).
+
+   .. note::
+
+      For a "map" of Yocto Project releases to version numbers, see the
+      :yocto_wiki:`Releases </wiki/Releases>` wiki page.
+
+   You can use the "RELEASE ARCHIVE" link to reveal a menu of all Yocto
+   Project releases.
+
+4. *Download Tools or Board Support Packages (BSPs):* From the
+   "DOWNLOADS" page, you can download tools or BSPs as well. Just scroll
+   down the page and look for what you need.
+
+Accessing Nightly Builds
+------------------------
+
+Yocto Project maintains an area for nightly builds that contains tarball
+releases at https://autobuilder.yocto.io//pub/nightly/. These builds include Yocto
+Project releases ("poky"), toolchains, and builds for supported
+machines.
+
+Should you ever want to access a nightly build of a particular Yocto
+Project component, use the following procedure:
+
+1. *Locate the Index of Nightly Builds:* Open a browser and go to
+   https://autobuilder.yocto.io//pub/nightly/ to access the Nightly Builds.
+
+2. *Select a Date:* Click on the date in which you are interested. If
+   you want the latest builds, use "CURRENT".
+
+3. *Select a Build:* Choose the area in which you are interested. For
+   example, if you are looking for the most recent toolchains, select
+   the "toolchain" link.
+
+4. *Find the Tarball:* Drill down to find the associated tarball.
+
+5. *Download the Tarball:* Click the tarball to download and save a
+   snapshot of the given component.
+
+Cloning and Checking Out Branches
+=================================
+
+To use the Yocto Project for development, you need a release locally
+installed on your development system. This locally installed set of
+files is referred to as the :term:`Source Directory`
+in the Yocto Project documentation.
+
+The preferred method of creating your Source Directory is by using
+:ref:`overview-manual/overview-manual-development-environment:git` to clone a local copy of the upstream
+``poky`` repository. Working from a cloned copy of the upstream
+repository allows you to contribute back into the Yocto Project or to
+simply work with the latest software on a development branch. Because
+Git maintains and creates an upstream repository with a complete history
+of changes and you are working with a local clone of that repository,
+you have access to all the Yocto Project development branches and tag
+names used in the upstream repository.
+
+Cloning the ``poky`` Repository
+-------------------------------
+
+Follow these steps to create a local version of the upstream
+:term:`Poky` Git repository.
+
+1. *Set Your Directory:* Change your working directory to where you want
+   to create your local copy of ``poky``.
+
+2. *Clone the Repository:* The following example command clones the
+   ``poky`` repository and uses the default name "poky" for your local
+   repository:
+   ::
+
+      $ git clone git://git.yoctoproject.org/poky
+      Cloning into 'poky'...
+      remote: Counting objects: 432160, done.
+      remote: Compressing objects: 100% (102056/102056), done.
+      remote: Total 432160 (delta 323116), reused 432037 (delta 323000)
+      Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
+      Resolving deltas: 100% (323116/323116), done.
+      Checking connectivity... done.
+
+   Unless you
+   specify a specific development branch or tag name, Git clones the
+   "master" branch, which results in a snapshot of the latest
+   development changes for "master". For information on how to check out
+   a specific development branch or on how to check out a local branch
+   based on a tag name, see the "`Checking Out By Branch in
+   Poky <#checking-out-by-branch-in-poky>`__" and `Checking Out By Tag
+   in Poky <#checkout-out-by-tag-in-poky>`__" sections, respectively.
+
+   Once the local repository is created, you can change to that
+   directory and check its status. Here, the single "master" branch
+   exists on your system and by default, it is checked out:
+   ::
+
+      $ cd ~/poky
+      $ git status
+      On branch master
+      Your branch is up-to-date with 'origin/master'.
+      nothing to commit, working directory clean
+      $ git branch
+      * master
+
+   Your local repository of poky is identical to the
+   upstream poky repository at the time from which it was cloned. As you
+   work with the local branch, you can periodically use the
+   ``git pull --rebase`` command to be sure you are up-to-date
+   with the upstream branch.
+
+Checking Out by Branch in Poky
+------------------------------
+
+When you clone the upstream poky repository, you have access to all its
+development branches. Each development branch in a repository is unique
+as it forks off the "master" branch. To see and use the files of a
+particular development branch locally, you need to know the branch name
+and then specifically check out that development branch.
+
+.. note::
+
+   Checking out an active development branch by branch name gives you a
+   snapshot of that particular branch at the time you check it out.
+   Further development on top of the branch that occurs after check it
+   out can occur.
+
+1. *Switch to the Poky Directory:* If you have a local poky Git
+   repository, switch to that directory. If you do not have the local
+   copy of poky, see the
+   ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
+   section.
+
+2. *Determine Existing Branch Names:*
+   ::
+
+      $ git branch -a
+      * master
+      remotes/origin/1.1_M1
+      remotes/origin/1.1_M2
+      remotes/origin/1.1_M3
+      remotes/origin/1.1_M4
+      remotes/origin/1.2_M1
+      remotes/origin/1.2_M2
+      remotes/origin/1.2_M3
+      . . .
+      remotes/origin/thud
+      remotes/origin/thud-next
+      remotes/origin/warrior
+      remotes/origin/warrior-next
+      remotes/origin/zeus
+      remotes/origin/zeus-next
+      ... and so on ...
+
+3. *Check out the Branch:* Check out the development branch in which you
+   want to work. For example, to access the files for the Yocto Project
+   &DISTRO; Release (&DISTRO_NAME;), use the following command:
+   ::
+
+      $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
+      Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin.
+      Switched to a new branch '&DISTRO_NAME_NO_CAP;'
+
+   The previous command checks out the "&DISTRO_NAME_NO_CAP;" development
+   branch and reports that the branch is tracking the upstream
+   "origin/&DISTRO_NAME_NO_CAP;" branch.
+
+   The following command displays the branches that are now part of your
+   local poky repository. The asterisk character indicates the branch
+   that is currently checked out for work:
+   ::
+
+      $ git branch
+        master
+        * &DISTRO_NAME_NO_CAP;
+
+.. _checkout-out-by-tag-in-poky:
+
+Checking Out by Tag in Poky
+---------------------------
+
+Similar to branches, the upstream repository uses tags to mark specific
+commits associated with significant points in a development branch (i.e.
+a release point or stage of a release). You might want to set up a local
+branch based on one of those points in the repository. The process is
+similar to checking out by branch name except you use tag names.
+
+.. note::
+
+   Checking out a branch based on a tag gives you a stable set of files
+   not affected by development on the branch above the tag.
+
+1. *Switch to the Poky Directory:* If you have a local poky Git
+   repository, switch to that directory. If you do not have the local
+   copy of poky, see the
+   ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
+   section.
+
+2. *Fetch the Tag Names:* To checkout the branch based on a tag name,
+   you need to fetch the upstream tags into your local repository:
+   ::
+
+      $ git fetch --tags
+      $
+
+3. *List the Tag Names:* You can list the tag names now:
+   ::
+
+      $ git tag
+      1.1_M1.final
+      1.1_M1.rc1
+      1.1_M1.rc2
+      1.1_M2.final
+      1.1_M2.rc1
+         .
+         .
+         .
+      yocto-2.5
+      yocto-2.5.1
+      yocto-2.5.2
+      yocto-2.5.3
+      yocto-2.6
+      yocto-2.6.1
+      yocto-2.6.2
+      yocto-2.7
+      yocto_1.5_M5.rc8
+
+
+4. *Check out the Branch:*
+   ::
+
+      $ git checkout tags/yocto-&DISTRO; -b my_yocto_&DISTRO;
+      Switched to a new branch 'my_yocto_&DISTRO;'
+      $ git branch
+        master
+      * my_yocto_&DISTRO;
+
+   The previous command creates and
+   checks out a local branch named "my_yocto_&DISTRO;", which is based on
+   the commit in the upstream poky repository that has the same tag. In
+   this example, the files you have available locally as a result of the
+   ``checkout`` command are a snapshot of the "&DISTRO_NAME_NO_CAP;"
+   development branch at the point where Yocto Project &DISTRO; was
+   released.

documentation/dev-manual/dev-manual.rst

@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+======================================
+Yocto Project Development Tasks Manual
+======================================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   dev-manual-intro
+   dev-manual-start
+   dev-manual-common-tasks
+   dev-manual-qemu
+   history
+
+.. include:: /boilerplate.rst

documentation/dev-manual/dev-manual.xml

@@ -1,209 +0,0 @@
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<book id='dev-manual' lang='en'
-      xmlns:xi="http://www.w3.org/2003/XInclude"
-      xmlns="http://docbook.org/ns/docbook"
-      >
-    <bookinfo>
-
-        <mediaobject>
-            <imageobject>
-                <imagedata fileref='figures/dev-title.png'
-                    format='SVG'
-                    align='left' scalefit='1' width='100%'/>
-            </imageobject>
-        </mediaobject>
-
-        <title>
-            Yocto Project Development Tasks Manual
-        </title>
-
-        <authorgroup>
-            <author>
-                <affiliation>
-                    <orgname>&ORGNAME;</orgname>
-                </affiliation>
-                <email>&ORGEMAIL;</email>
-            </author>
-        </authorgroup>
-
-        <revhistory>
-            <revision>
-                <revnumber>1.1</revnumber>
-                <date>October 2011</date>
-                <revremark>The initial document released with the Yocto Project 1.1 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.2</revnumber>
-                <date>April 2012</date>
-                <revremark>Released with the Yocto Project 1.2 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.3</revnumber>
-                <date>October 2012</date>
-                <revremark>Released with the Yocto Project 1.3 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.4</revnumber>
-                <date>April 2013</date>
-                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.5</revnumber>
-                <date>October 2013</date>
-                <revremark>Released with the Yocto Project 1.5 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.6</revnumber>
-                <date>April 2014</date>
-                <revremark>Released with the Yocto Project 1.6 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.7</revnumber>
-                <date>October 2014</date>
-                <revremark>Released with the Yocto Project 1.7 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>1.8</revnumber>
-                <date>April 2015</date>
-                <revremark>Released with the Yocto Project 1.8 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.0</revnumber>
-                <date>October 2015</date>
-                <revremark>Released with the Yocto Project 2.0 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.1</revnumber>
-                <date>April 2016</date>
-                <revremark>Released with the Yocto Project 2.1 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.2</revnumber>
-                <date>October 2016</date>
-                <revremark>Released with the Yocto Project 2.2 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.3</revnumber>
-                <date>May 2017</date>
-                <revremark>Released with the Yocto Project 2.3 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.4</revnumber>
-                <date>October 2017</date>
-                <revremark>Released with the Yocto Project 2.4 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.5</revnumber>
-                <date>May 2018</date>
-                <revremark>Released with the Yocto Project 2.5 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.6</revnumber>
-                <date>November 2018</date>
-                <revremark>Released with the Yocto Project 2.6 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>2.7</revnumber>
-                <date>May 2019</date>
-                <revremark>Released with the Yocto Project 2.7 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>3.0</revnumber>
-                <date>October 2019</date>
-                <revremark>Released with the Yocto Project 3.0 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>3.1</revnumber>
-                <date>April 2020</date>
-                <revremark>Released with the Yocto Project 3.1 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>3.1.1</revnumber>
-                <date>June 2020</date>
-                <revremark>Released with the Yocto Project 3.1.1 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>3.1.2</revnumber>
-                <date>August 2020</date>
-                <revremark>Released with the Yocto Project 3.1.2 Release.</revremark>
-            </revision>
-            <revision>
-                <revnumber>3.1.3</revnumber>
-                <date>&REL_MONTH_YEAR;</date>
-                <revremark>Released with the Yocto Project 3.1.3 Release.</revremark>
-            </revision>
-        </revhistory>
-
-    <copyright>
-     <year>&COPYRIGHT_YEAR;</year>
-      <holder>Linux Foundation</holder>
-    </copyright>
-
-    <legalnotice>
-      <para>
-          Permission is granted to copy, distribute and/or modify this document under
-          the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">
-          Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by
-          Creative Commons.
-      </para>
-           <note><title>Manual Notes</title>
-               <itemizedlist>
-                   <listitem><para>
-                       This version of the
-                       <emphasis>Yocto Project Development Tasks Manual</emphasis>
-                       is for the &YOCTO_DOC_VERSION; release of the
-                       Yocto Project.
-                       To be sure you have the latest version of the manual
-                       for this release, go to the
-                       <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
-                       and select the manual from that site.
-                       Manuals from the site are more up-to-date than manuals
-                       derived from the Yocto Project released TAR files.
-                       </para></listitem>
-                   <listitem><para>
-                       If you located this manual through a web search, the
-                       version of the manual might not be the one you want
-                       (e.g. the search might have returned a manual much
-                       older than the Yocto Project version with which you
-                       are working).
-                       You can see all Yocto Project major releases by
-                       visiting the
-                       <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
-                       page.
-                       If you need a version of this manual for a different
-                       Yocto Project release, visit the
-                       <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
-                       and select the manual set by using the
-                       "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
-                       pull-down menus.
-                       </para></listitem>
-                   <listitem>
-                       <para>
-                       To report any inaccuracies or problems with this
-                       (or any other Yocto Project) manual, send an email to
-                       the Yocto Project documentation mailing list at
-                       <filename>docs@lists.yoctoproject.org</filename> or
-                       log into the freenode <filename>#yocto</filename> channel.
-                       </para>
-                   </listitem>
-               </itemizedlist>
-           </note>
-    </legalnotice>
-
-    </bookinfo>
-
-    <xi:include href="dev-manual-intro.xml"/>
-
-    <xi:include href="dev-manual-start.xml"/>
-
-    <xi:include href="dev-manual-common-tasks.xml"/>
-
-    <xi:include href="dev-manual-qemu.xml"/>
-
-</book>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/dev-manual/dev-style.css

@@ -1,988 +0,0 @@
-/*
-   Generic XHTML / DocBook XHTML CSS Stylesheet.
-
-   Browser wrangling and typographic design by
-      Oyvind Kolas / pippin@gimp.org
-
-   Customised for Poky by
-      Matthew Allum / mallum@o-hand.com
-
-   Thanks to:
-     Liam R. E. Quin
-     William Skaggs
-     Jakub Steiner
-
-   Structure
-   ---------
-
-   The stylesheet is divided into the following sections:
-
-       Positioning
-          Margins, paddings, width, font-size, clearing.
-       Decorations
-          Borders, style
-       Colors
-          Colors
-       Graphics
-          Graphical backgrounds
-       Nasty IE tweaks
-          Workarounds needed to make it work in internet explorer,
-          currently makes the stylesheet non validating, but up until
-          this point it is validating.
-       Mozilla extensions
-          Transparency for footer
-	  Rounded corners on boxes
-
-*/
-
-
-  /*************** /
- /  Positioning   /
-/ ***************/
-
-body {
-  font-family: Verdana, Sans, sans-serif;
-
-  min-width: 640px;
-  width: 80%;
-  margin:  0em auto;
-  padding: 2em 5em 5em 5em;
-  color: #333;
-}
-
-h1,h2,h3,h4,h5,h6,h7 {
-  font-family: Arial, Sans;
-  color: #00557D;
-  clear: both;
-}
-
-h1 {
-  font-size: 2em;
-  text-align: left;
-  padding: 0em 0em 0em 0em;
-  margin: 2em 0em 0em 0em;
-}
-
-h2.subtitle {
-  margin: 0.10em 0em 3.0em 0em;
-  padding: 0em 0em 0em 0em;
-  font-size: 1.8em;
-  padding-left: 20%;
-  font-weight: normal;
-  font-style: italic;
-}
-
-h2 {
-  margin: 2em 0em 0.66em 0em;
-  padding: 0.5em 0em 0em 0em;
-  font-size: 1.5em;
-  font-weight: bold;
-}
-
-h3.subtitle {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-  font-size: 142.14%;
-  text-align: right;
-}
-
-h3 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 140%;
-  font-weight: bold;
-}
-
-h4 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 120%;
-  font-weight: bold;
-}
-
-h5 {
-  margin: 1em 0em 0.5em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 110%;
-  font-weight: bold;
-}
-
-h6 {
-  margin: 1em 0em 0em 0em;
-  padding: 1em 0em 0em 0em;
-  font-size: 110%;
-  font-weight: bold;
-}
-
-.authorgroup {
-  background-color: transparent;
-  background-repeat: no-repeat;
-  padding-top: 256px;
-  background-image: url("figures/dev-title.png");
-  background-position: left top;
-  margin-top: -256px;
-  padding-right: 50px;
-  margin-left: 0px;
-  text-align: right;
-  width: 740px;
-}
-
-h3.author {
-  margin: 0em 0me 0em 0em;
-  padding: 0em 0em 0em 0em;
-  font-weight: normal;
-  font-size: 100%;
-  color: #333;
-  clear: both;
-}
-
-.author tt.email {
-  font-size: 66%;
-}
-
-.titlepage hr {
-  width: 0em;
-  clear: both;
-}
-
-.revhistory {
-  padding-top: 2em;
-  clear: both;
-}
-
-.toc,
-.list-of-tables,
-.list-of-examples,
-.list-of-figures {
-  padding: 1.33em 0em 2.5em 0em;
-  color: #00557D;
-}
-
-.toc p,
-.list-of-tables p,
-.list-of-figures p,
-.list-of-examples p {
-  padding: 0em 0em 0em 0em;
-  padding: 0em 0em 0.3em;
-  margin: 1.5em 0em 0em 0em;
-}
-
-.toc p b,
-.list-of-tables p b,
-.list-of-figures p b,
-.list-of-examples p b{
-  font-size: 100.0%;
-  font-weight: bold;
-}
-
-.toc dl,
-.list-of-tables dl,
-.list-of-figures dl,
-.list-of-examples dl {
-  margin: 0em 0em 0.5em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.toc dt {
-  margin: 0em 0em 0em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.toc dd {
-  margin: 0em 0em 0em 2.6em;
-  padding: 0em 0em 0em 0em;
-}
-
-div.glossary dl,
-div.variablelist dl {
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
-  font-weight: normal;
-  width: 20em;
-  text-align: right;
-}
-
-.variablelist dl dt {
-  margin-top: 0.5em;
-}
-
-.glossary dl dd,
-.variablelist dl dd {
-  margin-top: -1em;
-  margin-left: 25.5em;
-}
-
-.glossary dd p,
-.variablelist dd p {
-  margin-top: 0em;
-  margin-bottom: 1em;
-}
-
-
-div.calloutlist table td {
-  padding: 0em 0em 0em 0em;
-  margin: 0em 0em 0em 0em;
-}
-
-div.calloutlist table td p {
-  margin-top: 0em;
-  margin-bottom: 1em;
-}
-
-div p.copyright {
-  text-align: left;
-}
-
-div.legalnotice p.legalnotice-title {
-  margin-bottom: 0em;
-}
-
-p {
-  line-height: 1.5em;
-  margin-top: 0em;
-
-}
-
-dl {
-  padding-top: 0em;
-}
-
-hr {
-  border: solid 1px;
-}
-
-
-.mediaobject,
-.mediaobjectco {
-  text-align: center;
-}
-
-img {
-  border: none;
-}
-
-ul {
-  padding: 0em 0em 0em 1.5em;
-}
-
-ul li {
-  padding: 0em 0em 0em 0em;
-}
-
-ul li p {
-  text-align: left;
-}
-
-table {
-  width :100%;
-}
-
-th {
-  padding: 0.25em;
-  text-align: left;
-  font-weight: normal;
-  vertical-align: top;
-}
-
-td {
-  padding: 0.25em;
-  vertical-align: top;
-}
-
-p a[id] {
-  margin: 0px;
-  padding: 0px;
-  display: inline;
-  background-image: none;
-}
-
-a {
-  text-decoration: underline;
-  color: #444;
-}
-
-pre {
-    overflow: auto;
-}
-
-a:hover {
-  text-decoration: underline;
-  /*font-weight: bold;*/
-}
-
-/* This style defines how the permalink character
-   appears by itself and when hovered over with
-   the mouse. */
-
-[alt='Permalink'] { color: #eee; }
-[alt='Permalink']:hover { color: black; }
-
-
-div.informalfigure,
-div.informalexample,
-div.informaltable,
-div.figure,
-div.table,
-div.example {
-  margin: 1em 0em;
-  padding: 1em;
-  page-break-inside: avoid;
-}
-
-
-div.informalfigure p.title b,
-div.informalexample p.title b,
-div.informaltable p.title b,
-div.figure p.title b,
-div.example p.title b,
-div.table p.title b{
-    padding-top: 0em;
-    margin-top: 0em;
-    font-size: 100%;
-    font-weight: normal;
-}
-
-.mediaobject .caption,
-.mediaobject .caption p  {
-  text-align: center;
-  font-size: 80%;
-  padding-top: 0.5em;
-  padding-bottom: 0.5em;
-}
-
-.epigraph {
-  padding-left: 55%;
-  margin-bottom: 1em;
-}
-
-.epigraph p {
-  text-align: left;
-}
-
-.epigraph .quote {
-  font-style: italic;
-}
-.epigraph .attribution {
-  font-style: normal;
-  text-align: right;
-}
-
-span.application {
-  font-style: italic;
-}
-
-.programlisting {
-  font-family: monospace;
-  font-size: 80%;
-  white-space: pre;
-  margin: 1.33em 0em;
-  padding: 1.33em;
-}
-
-.tip,
-.warning,
-.caution,
-.note {
-  margin-top: 1em;
-  margin-bottom: 1em;
-
-}
-
-/* force full width of table within div */
-.tip table,
-.warning table,
-.caution table,
-.note table {
-  border: none;
-  width: 100%;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  padding: 0.8em 0.0em 0.0em 0.0em;
-  margin : 0em 0em 0em 0em;
-}
-
-.tip p,
-.warning p,
-.caution p,
-.note p {
-  margin-top: 0.5em;
-  margin-bottom: 0.5em;
-  padding-right: 1em;
-  text-align: left;
-}
-
-.acronym {
-  text-transform: uppercase;
-}
-
-b.keycap,
-.keycap {
-  padding: 0.09em 0.3em;
-  margin: 0em;
-}
-
-.itemizedlist li {
-  clear: none;
-}
-
-.filename {
-  font-size: medium;
-  font-family: Courier, monospace;
-}
-
-
-div.navheader, div.heading{
-  position: absolute;
-  left: 0em;
-  top: 0em;
-  width: 100%;
-  background-color: #cdf;
-  width: 100%;
-}
-
-div.navfooter, div.footing{
-  position: fixed;
-  left: 0em;
-  bottom: 0em;
-  background-color: #eee;
-  width: 100%;
-}
-
-
-div.navheader td,
-div.navfooter td {
-  font-size: 66%;
-}
-
-div.navheader table th {
-  /*font-family: Georgia, Times, serif;*/
-  /*font-size: x-large;*/
-  font-size: 80%;
-}
-
-div.navheader table {
-  border-left: 0em;
-  border-right: 0em;
-  border-top: 0em;
-  width: 100%;
-}
-
-div.navfooter table {
-  border-left: 0em;
-  border-right: 0em;
-  border-bottom: 0em;
-  width: 100%;
-}
-
-div.navheader table td a,
-div.navfooter table td a {
-  color: #777;
-  text-decoration: none;
-}
-
-/* normal text in the footer */
-div.navfooter table td {
-  color: black;
-}
-
-div.navheader table td a:visited,
-div.navfooter table td a:visited {
-  color: #444;
-}
-
-
-/* links in header and footer */
-div.navheader table td a:hover,
-div.navfooter table td a:hover {
-  text-decoration: underline;
-  background-color: transparent;
-  color: #33a;
-}
-
-div.navheader hr,
-div.navfooter hr {
-  display: none;
-}
-
-
-.qandaset tr.question td p {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-}
-
-.qandaset tr.answer td p {
-  margin: 0em 0em 1em 0em;
-  padding: 0em 0em 0em 0em;
-}
-.answer td {
-  padding-bottom: 1.5em;
-}
-
-.emphasis {
-  font-weight: bold;
-}
-
-
-  /************* /
- / decorations  /
-/ *************/
-
-.titlepage {
-}
-
-.part .title {
-}
-
-.subtitle {
-    border: none;
-}
-
-/*
-h1 {
-  border: none;
-}
-
-h2 {
-  border-top: solid 0.2em;
-  border-bottom: solid 0.06em;
-}
-
-h3 {
-  border-top: 0em;
-  border-bottom: solid 0.06em;
-}
-
-h4 {
-  border: 0em;
-  border-bottom: solid 0.06em;
-}
-
-h5 {
-  border: 0em;
-}
-*/
-
-.programlisting {
-  border: solid 1px;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example {
-  border: 1px solid;
-}
-
-
-
-.tip,
-.warning,
-.caution,
-.note {
-  border: 1px solid;
-}
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  border-bottom: 1px solid;
-}
-
-.question td {
-  border-top: 1px solid black;
-}
-
-.answer {
-}
-
-
-b.keycap,
-.keycap {
-  border: 1px solid;
-}
-
-
-div.navheader, div.heading{
-  border-bottom: 1px solid;
-}
-
-
-div.navfooter, div.footing{
-  border-top: 1px solid;
-}
-
-  /********* /
- /  colors  /
-/ *********/
-
-body {
-  color: #333;
-  background: white;
-}
-
-a {
-  background: transparent;
-}
-
-a:hover {
-  background-color: #dedede;
-}
-
-
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7,
-h8 {
-  background-color: transparent;
-}
-
-hr {
-  border-color: #aaa;
-}
-
-
-.tip, .warning, .caution, .note {
-  border-color: #fff;
-}
-
-
-.tip table th,
-.warning table th,
-.caution table th,
-.note table th {
-  border-bottom-color: #fff;
-}
-
-
-.warning {
-  background-color: #f0f0f2;
-}
-
-.caution {
-  background-color: #f0f0f2;
-}
-
-.tip {
-  background-color: #f0f0f2;
-}
-
-.note {
-  background-color: #f0f0f2;
-}
-
-.glossary dl dt,
-.variablelist dl dt,
-.variablelist dl dt span.term {
-  color: #044;
-}
-
-div.figure,
-div.table,
-div.example,
-div.informalfigure,
-div.informaltable,
-div.informalexample {
-  border-color: #aaa;
-}
-
-pre.programlisting {
-  color: black;
-  background-color: #fff;
-  border-color: #aaa;
-  border-width: 2px;
-}
-
-.guimenu,
-.guilabel,
-.guimenuitem {
-  background-color: #eee;
-}
-
-
-b.keycap,
-.keycap {
-  background-color: #eee;
-  border-color: #999;
-}
-
-
-div.navheader {
-  border-color: black;
-}
-
-
-div.navfooter {
-  border-color: black;
-}
-
-.writernotes {
-  color: red;
-}
-
-
-  /*********** /
- /  graphics  /
-/ ***********/
-
-/*
-body {
-  background-image: url("images/body_bg.jpg");
-  background-attachment: fixed;
-}
-
-.navheader,
-.note,
-.tip {
-  background-image: url("images/note_bg.jpg");
-  background-attachment: fixed;
-}
-
-.warning,
-.caution {
-  background-image: url("images/warning_bg.jpg");
-  background-attachment: fixed;
-}
-
-.figure,
-.informalfigure,
-.example,
-.informalexample,
-.table,
-.informaltable {
-  background-image: url("images/figure_bg.jpg");
-  background-attachment: fixed;
-}
-
-*/
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-h7{
-}
-
-/*
-Example of how to stick an image as part of the title.
-
-div.article .titlepage .title
-{
-  background-image: url("figures/white-on-black.png");
-  background-position: center;
-  background-repeat: repeat-x;
-}
-*/
-
-div.preface .titlepage .title,
-div.colophon .title,
-div.chapter .titlepage .title,
-div.article .titlepage .title
-{
-}
-
-div.section div.section .titlepage .title,
-div.sect2 .titlepage .title {
-    background: none;
-}
-
-
-h1.title {
-  background-color: transparent;
-  background-repeat: no-repeat;
-  height: 256px;
-  text-indent: -9000px;
-  overflow:hidden;
-}
-
-h2.subtitle {
-  background-color: transparent;
-  text-indent: -9000px;
-  overflow:hidden;
-  width: 0px;
-  display: none;
-}
-
-  /*************************************** /
- /  pippin.gimp.org specific alterations  /
-/ ***************************************/
-
-/*
-div.heading, div.navheader {
-  color: #777;
-  font-size: 80%;
-  padding: 0;
-  margin: 0;
-  text-align: left;
-  position: absolute;
-  top: 0px;
-  left: 0px;
-  width: 100%;
-  height: 50px;
-  background: url('/gfx/heading_bg.png') transparent;
-  background-repeat: repeat-x;
-  background-attachment: fixed;
-  border: none;
-}
-
-div.heading a {
-  color: #444;
-}
-
-div.footing, div.navfooter {
-  border: none;
-  color: #ddd;
-  font-size: 80%;
-  text-align:right;
-
-  width: 100%;
-  padding-top: 10px;
-  position: absolute;
-  bottom: 0px;
-  left: 0px;
-
-  background: url('/gfx/footing_bg.png') transparent;
-}
-*/
-
-
-
-  /****************** /
- /  nasty ie tweaks  /
-/ ******************/
-
-/*
-div.heading, div.navheader {
-  width:expression(document.body.clientWidth + "px");
-}
-
-div.footing, div.navfooter {
-  width:expression(document.body.clientWidth + "px");
-  margin-left:expression("-5em");
-}
-body {
-  padding:expression("4em 5em 0em 5em");
-}
-*/
-
-  /**************************************** /
- / mozilla vendor specific css extensions  /
-/ ****************************************/
-/*
-div.navfooter, div.footing{
-  -moz-opacity: 0.8em;
-}
-
-div.figure,
-div.table,
-div.informalfigure,
-div.informaltable,
-div.informalexample,
-div.example,
-.tip,
-.warning,
-.caution,
-.note {
-  -moz-border-radius: 0.5em;
-}
-
-b.keycap,
-.keycap {
-  -moz-border-radius: 0.3em;
-}
-*/
-
-table tr td table tr td {
-  display: none;
-}
-
-
-hr {
-  display: none;
-}
-
-table {
-  border: 0em;
-}
-
- .photo {
-  float: right;
-  margin-left:   1.5em;
-  margin-bottom: 1.5em;
-  margin-top: 0em;
-  max-width:      17em;
-  border:     1px solid gray;
-  padding:    3px;
-  background: white;
-}
- .seperator {
-   padding-top: 2em;
-   clear: both;
-  }
-
-  #validators {
-      margin-top: 5em;
-      text-align: right;
-      color: #777;
-  }
-  @media print {
-      body {
-          font-size: 8pt;
-      }
-      .noprint {
-          display: none;
-      }
-  }
-
-
-.tip,
-.note {
-   background: #f0f0f2;
-   color: #333;
-   padding: 20px;
-   margin: 20px;
-}
-
-.tip h3,
-.note h3 {
-   padding: 0em;
-   margin: 0em;
-   font-size: 2em;
-   font-weight: bold;
-   color: #333;
-}
-
-.tip a,
-.note a {
-   color: #333;
-   text-decoration: underline;
-}
-
-.footnote {
-   font-size: small;
-   color: #333;
-}
-
-/* Changes the announcement text */
-.tip h3,
-.warning h3,
-.caution h3,
-.note h3 {
-   font-size:large;
-   color: #00557D;
-}

documentation/dev-manual/history.rst

@@ -0,0 +1,79 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+***********************
+Manual Revision History
+***********************
+
+.. list-table::
+   :widths: 10 15 40
+   :header-rows: 1
+
+   * - Revision
+     - Date
+     - Note
+   * - 1.1
+     - October 2011
+     - The initial document released with the Yocto Project 1.1 Release
+   * - 1.2
+     - April 2012
+     - Released with the Yocto Project 1.2 Release.
+   * - 1.3
+     - October 2012
+     - Released with the Yocto Project 1.3 Release.
+   * - 1.4
+     - April 2013
+     - Released with the Yocto Project 1.4 Release.
+   * - 1.5
+     - October 2013
+     - Released with the Yocto Project 1.5 Release.
+   * - 1.6
+     - April 2014
+     - Released with the Yocto Project 1.6 Release.
+   * - 1.7
+     - October 2014
+     - Released with the Yocto Project 1.7 Release.
+   * - 1.8
+     - April 2015
+     - Released with the Yocto Project 1.8 Release.
+   * - 2.0
+     - October 2015
+     - Released with the Yocto Project 2.0 Release.
+   * - 2.1
+     - April 2016
+     - Released with the Yocto Project 2.1 Release.
+   * - 2.2
+     - October 2016
+     - Released with the Yocto Project 2.2 Release.
+   * - 2.3
+     - May 2017
+     - Released with the Yocto Project 2.3 Release.
+   * - 2.4
+     - October 2017
+     - Released with the Yocto Project 2.4 Release.
+   * - 2.5
+     - May 2018
+     - Released with the Yocto Project 2.5 Release.
+   * - 2.6
+     - November 2018
+     - Released with the Yocto Project 2.6 Release.
+   * - 2.7
+     - May 2019
+     - Released with the Yocto Project 2.7 Release.
+   * - 3.0
+     - October 2019
+     - Released with the Yocto Project 3.0 Release.
+   * - 3.1
+     - April 2020
+     - Released with the Yocto Project 3.1 Release.
+   * - 3.1.1
+     - June 2020
+     - Released with the Yocto Project 3.1.1 Release.
+   * - 3.1.2
+     - August 2020
+     - Released with the Yocto Project 3.1.2 Release.
+   * - 3.1.3
+     - September 2020
+     - Released with the Yocto Project 3.1.3 Release.
+   * - 3.1.4
+     - November 2020
+     - Released with the Yocto Project 3.1.4 Release.

documentation/genindex.rst

@@ -0,0 +1,3 @@
+=====
+Index
+=====

documentation/index.rst

@@ -0,0 +1,52 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+.. The Yocto Project documentation master file, created by
+   sphinx-quickstart on Mon Apr 13 09:38:33 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to the Yocto Project Documentation
+==========================================
+
+|
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Introduction and Overview
+
+   Quick Build <brief-yoctoprojectqs/brief-yoctoprojectqs>
+   what-i-wish-id-known
+   transitioning-to-a-custom-environment
+   Yocto Project Software Overview <https://www.yoctoproject.org/software-overview/>
+   Tips and Tricks Wiki <https://wiki.yoctoproject.org/wiki/TipsAndTricks>
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Manuals
+
+   Overview and Concepts Manual <overview-manual/overview-manual>
+   Reference Manual <ref-manual/ref-manual>
+   Board Support Package (BSP) Developer's guide <bsp-guide/bsp-guide>
+   Development Tasks Manual <dev-manual/dev-manual>
+   Linux Kernel Development Manual <kernel-dev/kernel-dev>
+   Profile and Tracing Manual <profile-manual/profile-manual>
+   Application Development and the Extensible SDK (eSDK) <sdk-manual/sdk-manual>
+   Toaster Manual <toaster-manual/toaster-manual>
+   Bitbake User Manual <https://docs.yoctoproject.org/bitbake/1.46>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 'Mega' Manual
+
+   All-in-one 'Mega' Manual <https://docs.yoctoproject.org/singleindex.html>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Manuals/Variable Index
+
+   genindex
+   Current/Previous Version Specific Manuals <releases>
+
+
+

documentation/kernel-dev/history.rst

@@ -0,0 +1,70 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+***********************
+Manual Revision History
+***********************
+
+.. list-table::
+   :widths: 10 15 40
+   :header-rows: 1
+
+   * - Revision
+     - Date
+     - Note
+   * - 1.4
+     - April 2013
+     - The initial document released with the Yocto Project 1.4 Release
+   * - 1.5
+     - October 2013
+     - Released with the Yocto Project 1.5 Release.
+   * - 1.6
+     - April 2014
+     - Released with the Yocto Project 1.6 Release.
+   * - 1.7
+     - October 2014
+     - Released with the Yocto Project 1.7 Release.
+   * - 1.8
+     - April 2015
+     - Released with the Yocto Project 1.8 Release.
+   * - 2.0
+     - October 2015
+     - Released with the Yocto Project 2.0 Release.
+   * - 2.1
+     - April 2016
+     - Released with the Yocto Project 2.1 Release.
+   * - 2.2
+     - October 2016
+     - Released with the Yocto Project 2.2 Release.
+   * - 2.3
+     - May 2017
+     - Released with the Yocto Project 2.3 Release.
+   * - 2.4
+     - October 2017
+     - Released with the Yocto Project 2.4 Release.
+   * - 2.5
+     - May 2018
+     - Released with the Yocto Project 2.5 Release.
+   * - 2.6
+     - November 2018
+     - Released with the Yocto Project 2.6 Release.
+   * - 2.7
+     - May 2019
+     - Released with the Yocto Project 2.7 Release.
+   * - 3.0
+     - October 2019
+     - Released with the Yocto Project 3.0 Release.
+   * - 3.1
+     - April 2020
+     - Released with the Yocto Project 3.1 Release.
+   * - 3.1.1
+     - June 2020
+     - Released with the Yocto Project 3.1.1 Release.
+   * - 3.1.2
+     - August 2020
+     - Released with the Yocto Project 3.1.2 Release.
+   * - 3.1.3
+     - September 2020
+     - Released with the Yocto Project 3.1.3 Release.
+   * - 3.1.4
+     - November 2020
+     - Released with the Yocto Project 3.1.4 Release.

documentation/kernel-dev/kernel-dev-advanced.rst

@@ -0,0 +1,957 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+*******************************************************
+Working with Advanced Metadata (``yocto-kernel-cache``)
+*******************************************************
+
+.. _kernel-dev-advanced-overview:
+
+Overview
+========
+
+In addition to supporting configuration fragments and patches, the Yocto
+Project kernel tools also support rich
+:term:`Metadata` that you can use to define
+complex policies and Board Support Package (BSP) support. The purpose of
+the Metadata and the tools that manage it is to help you manage the
+complexity of the configuration and sources used to support multiple
+BSPs and Linux kernel types.
+
+Kernel Metadata exists in many places. One area in the
+:ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`
+is the ``yocto-kernel-cache`` Git repository. You can find this repository
+grouped under the "Yocto Linux Kernel" heading in the
+:yocto_git:`Yocto Project Source Repositories <>`.
+
+Kernel development tools ("kern-tools") exist also in the Yocto Project
+Source Repositories under the "Yocto Linux Kernel" heading in the
+``yocto-kernel-tools`` Git repository. The recipe that builds these
+tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in
+the :term:`Source Directory` (e.g.
+``poky``).
+
+Using Kernel Metadata in a Recipe
+=================================
+
+As mentioned in the introduction, the Yocto Project contains kernel
+Metadata, which is located in the ``yocto-kernel-cache`` Git repository.
+This Metadata defines Board Support Packages (BSPs) that correspond to
+definitions in linux-yocto recipes for corresponding BSPs. A BSP
+consists of an aggregation of kernel policy and enabled
+hardware-specific features. The BSP can be influenced from within the
+linux-yocto recipe.
+
+.. note::
+
+   A Linux kernel recipe that contains kernel Metadata (e.g. inherits
+   from the ``linux-yocto.inc`` file) is said to be a "linux-yocto style" recipe.
+
+Every linux-yocto style recipe must define the
+:term:`KMACHINE` variable. This
+variable is typically set to the same value as the ``MACHINE`` variable,
+which is used by :term:`BitBake`.
+However, in some cases, the variable might instead refer to the
+underlying platform of the ``MACHINE``.
+
+Multiple BSPs can reuse the same ``KMACHINE`` name if they are built
+using the same BSP description. Multiple Corei7-based BSPs could share
+the same "intel-corei7-64" value for ``KMACHINE``. It is important to
+realize that ``KMACHINE`` is just for kernel mapping, while ``MACHINE``
+is the machine type within a BSP Layer. Even with this distinction,
+however, these two variables can hold the same value. See the `BSP
+Descriptions <#bsp-descriptions>`__ section for more information.
+
+Every linux-yocto style recipe must also indicate the Linux kernel
+source repository branch used to build the Linux kernel. The
+:term:`KBRANCH` variable must be set
+to indicate the branch.
+
+.. note::
+
+   You can use the ``KBRANCH`` value to define an alternate branch typically
+   with a machine override as shown here from the ``meta-yocto-bsp`` layer:
+   ::
+
+           KBRANCH_edgerouter = "standard/edgerouter"
+
+
+The linux-yocto style recipes can optionally define the following
+variables:
+
+  - :term:`KERNEL_FEATURES`
+
+  - :term:`LINUX_KERNEL_TYPE`
+
+:term:`LINUX_KERNEL_TYPE`
+defines the kernel type to be used in assembling the configuration. If
+you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard".
+Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search
+arguments used by the kernel tools to find the appropriate description
+within the kernel Metadata with which to build out the sources and
+configuration. The linux-yocto recipes define "standard", "tiny", and
+"preempt-rt" kernel types. See the "`Kernel Types <#kernel-types>`__"
+section for more information on kernel types.
+
+During the build, the kern-tools search for the BSP description file
+that most closely matches the ``KMACHINE`` and ``LINUX_KERNEL_TYPE``
+variables passed in from the recipe. The tools use the first BSP
+description they find that matches both variables. If the tools cannot find
+a match, they issue a warning.
+
+The tools first search for the ``KMACHINE`` and then for the
+``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they
+will use the sources from the ``KBRANCH`` and any configuration
+specified in the :term:`SRC_URI`.
+
+You can use the
+:term:`KERNEL_FEATURES`
+variable to include features (configuration fragments, patches, or both)
+that are not already included by the ``KMACHINE`` and
+``LINUX_KERNEL_TYPE`` variable combination. For example, to include a
+feature specified as "features/netfilter/netfilter.scc", specify:
+::
+
+   KERNEL_FEATURES += "features/netfilter/netfilter.scc"
+
+To include a
+feature called "cfg/sound.scc" just for the ``qemux86`` machine,
+specify:
+::
+
+   KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc"
+
+The value of
+the entries in ``KERNEL_FEATURES`` are dependent on their location
+within the kernel Metadata itself. The examples here are taken from the
+``yocto-kernel-cache`` repository. Each branch of this repository
+contains "features" and "cfg" subdirectories at the top-level. For more
+information, see the "`Kernel Metadata
+Syntax <#kernel-metadata-syntax>`__" section.
+
+Kernel Metadata Syntax
+======================
+
+The kernel Metadata consists of three primary types of files: ``scc``
+[1]_ description files, configuration fragments, and patches. The
+``scc`` files define variables and include or otherwise reference any of
+the three file types. The description files are used to aggregate all
+types of kernel Metadata into what ultimately describes the sources and
+the configuration required to build a Linux kernel tailored to a
+specific machine.
+
+The ``scc`` description files are used to define two fundamental types
+of kernel Metadata:
+
+-  Features
+
+-  Board Support Packages (BSPs)
+
+Features aggregate sources in the form of patches and configuration
+fragments into a modular reusable unit. You can use features to
+implement conceptually separate kernel Metadata descriptions such as
+pure configuration fragments, simple patches, complex features, and
+kernel types. `Kernel types <#kernel-types>`__ define general kernel
+features and policy to be reused in the BSPs.
+
+BSPs define hardware-specific features and aggregate them with kernel
+types to form the final description of what will be assembled and built.
+
+While the kernel Metadata syntax does not enforce any logical separation
+of configuration fragments, patches, features or kernel types, best
+practices dictate a logical separation of these types of Metadata. The
+following Metadata file hierarchy is recommended:
+::
+
+   base/
+      bsp/
+      cfg/
+      features/
+      ktypes/
+      patches/
+
+The ``bsp`` directory contains the `BSP
+descriptions <#bsp-descriptions>`__. The remaining directories all
+contain "features". Separating ``bsp`` from the rest of the structure
+aids conceptualizing intended usage.
+
+Use these guidelines to help place your ``scc`` description files within
+the structure:
+
+-  If your file contains only configuration fragments, place the file in
+   the ``cfg`` directory.
+
+-  If your file contains only source-code fixes, place the file in the
+   ``patches`` directory.
+
+-  If your file encapsulates a major feature, often combining sources
+   and configurations, place the file in ``features`` directory.
+
+-  If your file aggregates non-hardware configuration and patches in
+   order to define a base kernel policy or major kernel type to be
+   reused across multiple BSPs, place the file in ``ktypes`` directory.
+
+These distinctions can easily become blurred - especially as out-of-tree
+features slowly merge upstream over time. Also, remember that how the
+description files are placed is a purely logical organization and has no
+impact on the functionality of the kernel Metadata. There is no impact
+because all of ``cfg``, ``features``, ``patches``, and ``ktypes``,
+contain "features" as far as the kernel tools are concerned.
+
+Paths used in kernel Metadata files are relative to base, which is
+either
+:term:`FILESEXTRAPATHS` if
+you are creating Metadata in `recipe-space <#recipe-space-metadata>`__,
+or the top level of
+:yocto_git:`yocto-kernel-cache </cgit/cgit.cgi/yocto-kernel-cache/tree/>`
+if you are creating `Metadata outside of the
+recipe-space <#metadata-outside-the-recipe-space>`__.
+
+.. [1]
+   ``scc`` stands for Series Configuration Control, but the naming has
+   less significance in the current implementation of the tooling than
+   it had in the past. Consider ``scc`` files to be description files.
+
+Configuration
+-------------
+
+The simplest unit of kernel Metadata is the configuration-only feature.
+This feature consists of one or more Linux kernel configuration
+parameters in a configuration fragment file (``.cfg``) and a ``.scc``
+file that describes the fragment.
+
+As an example, consider the Symmetric Multi-Processing (SMP) fragment
+used with the ``linux-yocto-4.12`` kernel as defined outside of the
+recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of
+two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
+``cfg`` directory of the ``yocto-4.12`` branch in the
+``yocto-kernel-cache`` Git repository:
+::
+
+   cfg/smp.scc:
+      define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
+      define KFEATURE_COMPATIBILITY all
+
+      kconf hardware smp.cfg
+
+   cfg/smp.cfg:
+      CONFIG_SMP=y
+      CONFIG_SCHED_SMT=y
+      # Increase default NR_CPUS from 8 to 64 so that platform with
+      # more than 8 processors can be all activated at boot time
+      CONFIG_NR_CPUS=64
+      # The following is needed when setting NR_CPUS to something
+      # greater than 8 on x86 architectures, it should be automatically
+      # disregarded by Kconfig when using a different arch
+      CONFIG_X86_BIGSMP=y
+
+You can find general information on configuration
+fragment files in the ":ref:`creating-config-fragments`" section.
+
+Within the ``smp.scc`` file, the
+:term:`KFEATURE_DESCRIPTION`
+statement provides a short description of the fragment. Higher level
+kernel tools use this description.
+
+Also within the ``smp.scc`` file, the ``kconf`` command includes the
+actual configuration fragment in an ``.scc`` file, and the "hardware"
+keyword identifies the fragment as being hardware enabling, as opposed
+to general policy, which would use the "non-hardware" keyword. The
+distinction is made for the benefit of the configuration validation
+tools, which warn you if a hardware fragment overrides a policy set by a
+non-hardware fragment.
+
+.. note::
+
+   The description file can include multiple ``kconf`` statements, one per
+   fragment.
+
+As described in the
+":ref:`kernel-dev/kernel-dev-common:validating configuration`" section, you can
+use the following BitBake command to audit your configuration:
+::
+
+   $ bitbake linux-yocto -c kernel_configcheck -f
+
+Patches
+-------
+
+Patch descriptions are very similar to configuration fragment
+descriptions, which are described in the previous section. However,
+instead of a ``.cfg`` file, these descriptions work with source patches
+(i.e. ``.patch`` files).
+
+A typical patch includes a description file and the patch itself. As an
+example, consider the build patches used with the ``linux-yocto-4.12``
+kernel as defined outside of the recipe space (i.e.
+``yocto-kernel-cache``). This Metadata consists of several files:
+``build.scc`` and a set of ``*.patch`` files. You can find these files
+in the ``patches/build`` directory of the ``yocto-4.12`` branch in the
+``yocto-kernel-cache`` Git repository.
+
+The following listings show the ``build.scc`` file and part of the
+``modpost-mask-trivial-warnings.patch`` file:
+::
+
+   patches/build/build.scc:
+      patch arm-serialize-build-targets.patch
+      patch powerpc-serialize-image-targets.patch
+      patch kbuild-exclude-meta-directory-from-distclean-processi.patch
+
+      # applied by kgit
+      # patch kbuild-add-meta-files-to-the-ignore-li.patch
+
+      patch modpost-mask-trivial-warnings.patch
+      patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
+
+   patches/build/modpost-mask-trivial-warnings.patch:
+      From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
+      From: Paul Gortmaker <paul.gortmaker@windriver.com>
+      Date: Sun, 25 Jan 2009 17:58:09 -0500
+      Subject: [PATCH] modpost: mask trivial warnings
+
+      Newer HOSTCC will complain about various stdio fcns because
+                        .
+                        .
+                        .
+ 	        char *dump_write = NULL, *files_source = NULL;
+ 	        int opt;
+      --
+      2.10.1
+
+      generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
+
+The description file can
+include multiple patch statements where each statement handles a single
+patch. In the example ``build.scc`` file, five patch statements exist
+for the five patches in the directory.
+
+You can create a typical ``.patch`` file using ``diff -Nurp`` or
+``git format-patch`` commands. For information on how to create patches,
+see the ":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`"
+and ":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`"
+sections.
+
+Features
+--------
+
+Features are complex kernel Metadata types that consist of configuration
+fragments, patches, and possibly other feature description files. As an
+example, consider the following generic listing:
+::
+
+   features/myfeature.scc
+      define KFEATURE_DESCRIPTION "Enable myfeature"
+
+      patch 0001-myfeature-core.patch
+      patch 0002-myfeature-interface.patch
+
+      include cfg/myfeature_dependency.scc
+      kconf non-hardware myfeature.cfg
+
+This example shows how the ``patch`` and ``kconf`` commands are used as well
+as how an additional feature description file is included with the
+``include`` command.
+
+Typically, features are less granular than configuration fragments and
+are more likely than configuration fragments and patches to be the types
+of things you want to specify in the ``KERNEL_FEATURES`` variable of the
+Linux kernel recipe. See the "`Using Kernel Metadata in a
+Recipe <#using-kernel-metadata-in-a-recipe>`__" section earlier in the
+manual.
+
+Kernel Types
+------------
+
+A kernel type defines a high-level kernel policy by aggregating
+non-hardware configuration fragments with patches you want to use when
+building a Linux kernel of a specific type (e.g. a real-time kernel).
+Syntactically, kernel types are no different than features as described
+in the "`Features <#features>`__" section. The
+:term:`LINUX_KERNEL_TYPE`
+variable in the kernel recipe selects the kernel type. For example, in
+the ``linux-yocto_4.12.bb`` kernel recipe found in
+``poky/meta/recipes-kernel/linux``, a
+:ref:`require <bitbake:require-inclusion>` directive
+includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
+which has the following statement that defines the default kernel type:
+::
+
+   LINUX_KERNEL_TYPE ??= "standard"
+
+Another example would be the real-time kernel (i.e.
+``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel
+type as follows:
+::
+
+   LINUX_KERNEL_TYPE = "preempt-rt"
+
+.. note::
+
+   You can find kernel recipes in the ``meta/recipes-kernel/linux`` directory
+   of the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`
+   (e.g. ``poky/meta/recipes-kernel/linux/linux-yocto_4.12.bb``). See the
+   ":ref:`kernel-dev/kernel-dev-advanced:using kernel metadata in a recipe`"
+   section for more information.
+
+Three kernel types ("standard", "tiny", and "preempt-rt") are supported
+for Linux Yocto kernels:
+
+-  "standard": Includes the generic Linux kernel policy of the Yocto
+   Project linux-yocto kernel recipes. This policy includes, among other
+   things, which file systems, networking options, core kernel features,
+   and debugging and tracing options are supported.
+
+-  "preempt-rt": Applies the ``PREEMPT_RT`` patches and the
+   configuration options required to build a real-time Linux kernel.
+   This kernel type inherits from the "standard" kernel type.
+
+-  "tiny": Defines a bare minimum configuration meant to serve as a base
+   for very small Linux kernels. The "tiny" kernel type is independent
+   from the "standard" configuration. Although the "tiny" kernel type
+   does not currently include any source changes, it might in the
+   future.
+
+For any given kernel type, the Metadata is defined by the ``.scc`` (e.g.
+``standard.scc``). Here is a partial listing for the ``standard.scc``
+file, which is found in the ``ktypes/standard`` directory of the
+``yocto-kernel-cache`` Git repository:
+::
+
+   # Include this kernel type fragment to get the standard features and
+   # configuration values.
+
+   # Note: if only the features are desired, but not the configuration
+   #       then this should be included as:
+   #             include ktypes/standard/standard.scc nocfg
+   #       if no chained configuration is desired, include it as:
+   #             include ktypes/standard/standard.scc nocfg inherit
+
+
+
+   include ktypes/base/base.scc
+   branch standard
+
+   kconf non-hardware standard.cfg
+
+   include features/kgdb/kgdb.scc
+              .
+              .
+              .
+
+   include cfg/net/ip6_nf.scc
+   include cfg/net/bridge.scc
+
+   include cfg/systemd.scc
+
+   include features/rfkill/rfkill.scc
+
+As with any ``.scc`` file, a kernel type definition can aggregate other
+``.scc`` files with ``include`` commands. These definitions can also
+directly pull in configuration fragments and patches with the ``kconf``
+and ``patch`` commands, respectively.
+
+.. note::
+
+   It is not strictly necessary to create a kernel type ``.scc``
+   file. The Board Support Package (BSP) file can implicitly define the
+   kernel type using a ``define`` :term:`KTYPE` ``myktype`` line. See the
+   ":ref:`kernel-dev/kernel-dev-advanced:bsp descriptions`" section for more
+   information.
+
+BSP Descriptions
+----------------
+
+BSP descriptions (i.e. ``*.scc`` files) combine kernel types with
+hardware-specific features. The hardware-specific Metadata is typically
+defined independently in the BSP layer, and then aggregated with each
+supported kernel type.
+
+.. note::
+
+   For BSPs supported by the Yocto Project, the BSP description files
+   are located in the ``bsp`` directory of the ``yocto-kernel-cache``
+   repository organized under the "Yocto Linux Kernel" heading in the
+   :yocto_git:`Yocto Project Source Repositories </>`.
+
+This section overviews the BSP description structure, the aggregation
+concepts, and presents a detailed example using a BSP supported by the
+Yocto Project (i.e. BeagleBone Board). For complete information on BSP
+layer file hierarchy, see the :doc:`../bsp-guide/bsp-guide`.
+
+.. _bsp-description-file-overview:
+
+Description Overview
+~~~~~~~~~~~~~~~~~~~~
+
+For simplicity, consider the following root BSP layer description files
+for the BeagleBone board. These files employ both a structure and naming
+convention for consistency. The naming convention for the file is as
+follows:
+::
+
+   bsp_root_name-kernel_type.scc
+
+Here are some example root layer
+BSP filenames for the BeagleBone Board BSP, which is supported by the
+Yocto Project:
+::
+
+   beaglebone-standard.scc
+   beaglebone-preempt-rt.scc
+
+Each file uses the root name (i.e "beaglebone") BSP name followed by the
+kernel type.
+
+Examine the ``beaglebone-standard.scc`` file:
+::
+
+   define KMACHINE beaglebone
+   define KTYPE standard
+   define KARCH arm
+
+   include ktypes/standard/standard.scc
+   branch beaglebone
+
+   include beaglebone.scc
+
+   # default policy for standard kernels
+   include features/latencytop/latencytop.scc
+   include features/profiling/profiling.scc
+
+Every top-level BSP description file
+should define the :term:`KMACHINE`,
+:term:`KTYPE`, and
+:term:`KARCH` variables. These
+variables allow the OpenEmbedded build system to identify the
+description as meeting the criteria set by the recipe being built. This
+example supports the "beaglebone" machine for the "standard" kernel and
+the "arm" architecture.
+
+Be aware that a hard link between the ``KTYPE`` variable and a kernel
+type description file does not exist. Thus, if you do not have the
+kernel type defined in your kernel Metadata as it is here, you only need
+to ensure that the
+:term:`LINUX_KERNEL_TYPE`
+variable in the kernel recipe and the ``KTYPE`` variable in the BSP
+description file match.
+
+To separate your kernel policy from your hardware configuration, you
+include a kernel type (``ktype``), such as "standard". In the previous
+example, this is done using the following:
+::
+
+   include ktypes/standard/standard.scc
+
+This file aggregates all the configuration
+fragments, patches, and features that make up your standard kernel
+policy. See the "`Kernel Types <#kernel-types>`__" section for more
+information.
+
+To aggregate common configurations and features specific to the kernel
+for `mybsp`, use the following:
+::
+
+   include mybsp.scc
+
+You can see that in the BeagleBone example with the following:
+::
+
+   include beaglebone.scc
+
+For information on how to break a complete ``.config`` file into the various
+configuration fragments, see the ":ref:`creating-config-fragments`" section.
+
+Finally, if you have any configurations specific to the hardware that
+are not in a ``*.scc`` file, you can include them as follows:
+::
+
+   kconf hardware mybsp-extra.cfg
+
+The BeagleBone example does not include these
+types of configurations. However, the Malta 32-bit board does
+("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file:
+::
+
+   define KMACHINE mti-malta32-le
+   define KMACHINE qemumipsel
+   define KTYPE standard
+   define KARCH mips
+
+   include ktypes/standard/standard.scc
+   branch mti-malta32
+
+   include mti-malta32.scc
+   kconf hardware mti-malta32-le.cfg
+
+.. _bsp-description-file-example-minnow:
+
+Example
+~~~~~~~
+
+Many real-world examples are more complex. Like any other ``.scc`` file,
+BSP descriptions can aggregate features. Consider the Minnow BSP
+definition given the ``linux-yocto-4.4`` branch of the
+``yocto-kernel-cache`` (i.e.
+``yocto-kernel-cache/bsp/minnow/minnow.scc``):
+
+.. note::
+
+   Although the Minnow Board BSP is unused, the Metadata remains and is
+   being used here just as an example.
+
+::
+
+   include cfg/x86.scc
+   include features/eg20t/eg20t.scc
+   include cfg/dmaengine.scc
+   include features/power/intel.scc
+   include cfg/efi.scc
+   include features/usb/ehci-hcd.scc
+   include features/usb/ohci-hcd.scc
+   include features/usb/usb-gadgets.scc
+   include features/usb/touchscreen-composite.scc
+   include cfg/timer/hpet.scc
+   include features/leds/leds.scc
+   include features/spi/spidev.scc
+   include features/i2c/i2cdev.scc
+   include features/mei/mei-txe.scc
+
+   # Earlyprintk and port debug requires 8250
+   kconf hardware cfg/8250.cfg
+
+   kconf hardware minnow.cfg
+   kconf hardware minnow-dev.cfg
+
+The ``minnow.scc`` description file includes a hardware configuration
+fragment (``minnow.cfg``) specific to the Minnow BSP as well as several
+more general configuration fragments and features enabling hardware
+found on the machine. This ``minnow.scc`` description file is then
+included in each of the three "minnow" description files for the
+supported kernel types (i.e. "standard", "preempt-rt", and "tiny").
+Consider the "minnow" description for the "standard" kernel type (i.e.
+``minnow-standard.scc``):
+::
+
+   define KMACHINE minnow
+   define KTYPE standard
+   define KARCH i386
+
+   include ktypes/standard
+
+   include minnow.scc
+
+   # Extra minnow configs above the minimal defined in minnow.scc
+   include cfg/efi-ext.scc
+   include features/media/media-all.scc
+   include features/sound/snd_hda_intel.scc
+
+   # The following should really be in standard.scc
+   # USB live-image support
+   include cfg/usb-mass-storage.scc
+   include cfg/boot-live.scc
+
+   # Basic profiling
+   include features/latencytop/latencytop.scc
+   include features/profiling/profiling.scc
+
+   # Requested drivers that don't have an existing scc
+   kconf hardware minnow-drivers-extra.cfg
+
+The ``include`` command midway through the file includes the ``minnow.scc`` description
+that defines all enabled hardware for the BSP that is common to all
+kernel types. Using this command significantly reduces duplication.
+
+Now consider the "minnow" description for the "tiny" kernel type (i.e.
+``minnow-tiny.scc``):
+::
+
+   define KMACHINE minnow
+   define KTYPE tiny
+   define KARCH i386
+
+   include ktypes/tiny
+
+   include minnow.scc
+
+As you might expect,
+the "tiny" description includes quite a bit less. In fact, it includes
+only the minimal policy defined by the "tiny" kernel type and the
+hardware-specific configuration required for booting the machine along
+with the most basic functionality of the system as defined in the base
+"minnow" description file.
+
+Notice again the three critical variables:
+:term:`KMACHINE`,
+:term:`KTYPE`, and
+:term:`KARCH`. Of these variables, only
+``KTYPE`` has changed to specify the "tiny" kernel type.
+
+Kernel Metadata Location
+========================
+
+Kernel Metadata always exists outside of the kernel tree either defined
+in a kernel recipe (recipe-space) or outside of the recipe. Where you
+choose to define the Metadata depends on what you want to do and how you
+intend to work. Regardless of where you define the kernel Metadata, the
+syntax used applies equally.
+
+If you are unfamiliar with the Linux kernel and only wish to apply a
+configuration and possibly a couple of patches provided to you by
+others, the recipe-space method is recommended. This method is also a
+good approach if you are working with Linux kernel sources you do not
+control or if you just do not want to maintain a Linux kernel Git
+repository on your own. For partial information on how you can define
+kernel Metadata in the recipe-space, see the
+":ref:`kernel-dev/kernel-dev-common:modifying an existing recipe`" section.
+
+Conversely, if you are actively developing a kernel and are already
+maintaining a Linux kernel Git repository of your own, you might find it
+more convenient to work with kernel Metadata kept outside the
+recipe-space. Working with Metadata in this area can make iterative
+development of the Linux kernel more efficient outside of the BitBake
+environment.
+
+Recipe-Space Metadata
+---------------------
+
+When stored in recipe-space, the kernel Metadata files reside in a
+directory hierarchy below
+:term:`FILESEXTRAPATHS`. For
+a linux-yocto recipe or for a Linux kernel recipe derived by copying and
+modifying
+``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to
+a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to
+``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``.
+See the ":ref:`kernel-dev/kernel-dev-common:modifying an existing recipe`"
+section for more information.
+
+Here is an example that shows a trivial tree of kernel Metadata stored
+in recipe-space within a BSP layer:
+::
+
+   meta-my_bsp_layer/
+   `-- recipes-kernel
+       `-- linux
+           `-- linux-yocto
+               |-- bsp-standard.scc
+               |-- bsp.cfg
+               `-- standard.cfg
+
+When the Metadata is stored in recipe-space, you must take steps to
+ensure BitBake has the necessary information to decide what files to
+fetch and when they need to be fetched again. It is only necessary to
+specify the ``.scc`` files on the
+:term:`SRC_URI`. BitBake parses them
+and fetches any files referenced in the ``.scc`` files by the
+``include``, ``patch``, or ``kconf`` commands. Because of this, it is
+necessary to bump the recipe :term:`PR`
+value when changing the content of files not explicitly listed in the
+``SRC_URI``.
+
+If the BSP description is in recipe space, you cannot simply list the
+``*.scc`` in the ``SRC_URI`` statement. You need to use the following
+form from your kernel append file:
+::
+
+   SRC_URI_append_myplatform = " \
+       file://myplatform;type=kmeta;destsuffix=myplatform \
+       "
+
+Metadata Outside the Recipe-Space
+---------------------------------
+
+When stored outside of the recipe-space, the kernel Metadata files
+reside in a separate repository. The OpenEmbedded build system adds the
+Metadata to the build as a "type=kmeta" repository through the
+:term:`SRC_URI` variable. As an
+example, consider the following ``SRC_URI`` statement from the
+``linux-yocto_4.12.bb`` kernel recipe:
+::
+
+   SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \
+              git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
+
+
+``${KMETA}``, in this context, is simply used to name the directory into
+which the Git fetcher places the Metadata. This behavior is no different
+than any multi-repository ``SRC_URI`` statement used in a recipe (e.g.
+see the previous section).
+
+You can keep kernel Metadata in a "kernel-cache", which is a directory
+containing configuration fragments. As with any Metadata kept outside
+the recipe-space, you simply need to use the ``SRC_URI`` statement with
+the "type=kmeta" attribute. Doing so makes the kernel Metadata available
+during the configuration phase.
+
+If you modify the Metadata, you must not forget to update the ``SRCREV``
+statements in the kernel's recipe. In particular, you need to update the
+``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you
+wish to use. Changing the data in these branches and not updating the
+``SRCREV`` statements to match will cause the build to fetch an older
+commit.
+
+Organizing Your Source
+======================
+
+Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux
+kernel sources that have only a single branch - "master". This type of
+repository structure is fine for linear development supporting a single
+machine and architecture. However, if you work with multiple boards and
+architectures, a kernel source repository with multiple branches is more
+efficient. For example, suppose you need a series of patches for one
+board to boot. Sometimes, these patches are works-in-progress or
+fundamentally wrong, yet they are still necessary for specific boards.
+In these situations, you most likely do not want to include these
+patches in every kernel you build (i.e. have the patches as part of the
+lone "master" branch). It is situations like these that give rise to
+multiple branches used within a Linux kernel sources Git repository.
+
+Repository organization strategies exist that maximize source reuse,
+remove redundancy, and logically order your changes. This section
+presents strategies for the following cases:
+
+-  Encapsulating patches in a feature description and only including the
+   patches in the BSP descriptions of the applicable boards.
+
+-  Creating a machine branch in your kernel source repository and
+   applying the patches on that branch only.
+
+-  Creating a feature branch in your kernel source repository and
+   merging that branch into your BSP when needed.
+
+The approach you take is entirely up to you and depends on what works
+best for your development model.
+
+Encapsulating Patches
+---------------------
+
+If you are reusing patches from an external tree and are not working on
+the patches, you might find the encapsulated feature to be appropriate.
+Given this scenario, you do not need to create any branches in the
+source repository. Rather, you just take the static patches you need and
+encapsulate them within a feature description. Once you have the feature
+description, you simply include that into the BSP description as
+described in the "`BSP Descriptions <#bsp-descriptions>`__" section.
+
+You can find information on how to create patches and BSP descriptions
+in the "`Patches <#patches>`__" and "`BSP
+Descriptions <#bsp-descriptions>`__" sections.
+
+Machine Branches
+----------------
+
+When you have multiple machines and architectures to support, or you are
+actively working on board support, it is more efficient to create
+branches in the repository based on individual machines. Having machine
+branches allows common source to remain in the "master" branch with any
+features specific to a machine stored in the appropriate machine branch.
+This organization method frees you from continually reintegrating your
+patches into a feature.
+
+Once you have a new branch, you can set up your kernel Metadata to use
+the branch a couple different ways. In the recipe, you can specify the
+new branch as the ``KBRANCH`` to use for the board as follows:
+::
+
+   KBRANCH = "mynewbranch"
+
+Another method is to use the ``branch`` command in the BSP
+description:
+::
+
+   mybsp.scc:
+      define KMACHINE mybsp
+      define KTYPE standard
+      define KARCH i386
+      include standard.scc
+
+      branch mynewbranch
+
+      include mybsp-hw.scc
+
+If you find yourself with numerous branches, you might consider using a
+hierarchical branching system similar to what the Yocto Linux Kernel Git
+repositories use:
+::
+
+   common/kernel_type/machine
+
+If you had two kernel types, "standard" and "small" for instance, three
+machines, and common as ``mydir``, the branches in your Git repository
+might look like this:
+::
+
+   mydir/base
+   mydir/standard/base
+   mydir/standard/machine_a
+   mydir/standard/machine_b
+   mydir/standard/machine_c
+   mydir/small/base
+   mydir/small/machine_a
+
+This organization can help clarify the branch relationships. In this
+case, ``mydir/standard/machine_a`` includes everything in ``mydir/base``
+and ``mydir/standard/base``. The "standard" and "small" branches add
+sources specific to those kernel types that for whatever reason are not
+appropriate for the other branches.
+
+.. note::
+
+   The "base" branches are an artifact of the way Git manages its data
+   internally on the filesystem: Git will not allow you to use
+   ``mydir/standard`` and ``mydir/standard/machine_a`` because it would have to
+   create a file and a directory named "standard".
+
+Feature Branches
+----------------
+
+When you are actively developing new features, it can be more efficient
+to work with that feature as a branch, rather than as a set of patches
+that have to be regularly updated. The Yocto Project Linux kernel tools
+provide for this with the ``git merge`` command.
+
+To merge a feature branch into a BSP, insert the ``git merge`` command
+after any ``branch`` commands:
+::
+
+   mybsp.scc:
+      define KMACHINE mybsp
+      define KTYPE standard
+      define KARCH i386
+      include standard.scc
+
+      branch mynewbranch
+      git merge myfeature
+
+      include mybsp-hw.scc
+
+.. _scc-reference:
+
+SCC Description File Reference
+==============================
+
+This section provides a brief reference for the commands you can use
+within an SCC description file (``.scc``):
+
+-  ``branch [ref]``: Creates a new branch relative to the current branch
+   (typically ``${KTYPE}``) using the currently checked-out branch, or
+   "ref" if specified.
+
+-  ``define``: Defines variables, such as
+   :term:`KMACHINE`,
+   :term:`KTYPE`,
+   :term:`KARCH`, and
+   :term:`KFEATURE_DESCRIPTION`.
+
+-  ``include SCC_FILE``: Includes an SCC file in the current file. The
+   file is parsed as if you had inserted it inline.
+
+-  ``kconf [hardware|non-hardware] CFG_FILE``: Queues a configuration
+   fragment for merging into the final Linux ``.config`` file.
+
+-  ``git merge GIT_BRANCH``: Merges the feature branch into the current
+   branch.
+
+-  ``patch PATCH_FILE``: Applies the patch to the current Git branch.
+
+

documentation/kernel-dev/kernel-dev-concepts-appx.rst

@@ -0,0 +1,425 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+************************
+Advanced Kernel Concepts
+************************
+
+.. _kernel-big-picture:
+
+Yocto Project Kernel Development and Maintenance
+================================================
+
+Kernels available through the Yocto Project (Yocto Linux kernels), like
+other kernels, are based off the Linux kernel releases from
+https://www.kernel.org. At the beginning of a major Linux kernel
+development cycle, the Yocto Project team chooses a Linux kernel based
+on factors such as release timing, the anticipated release timing of
+final upstream ``kernel.org`` versions, and Yocto Project feature
+requirements. Typically, the Linux kernel chosen is in the final stages
+of development by the Linux community. In other words, the Linux kernel
+is in the release candidate or "rc" phase and has yet to reach final
+release. But, by being in the final stages of external development, the
+team knows that the ``kernel.org`` final release will clearly be within
+the early stages of the Yocto Project development window.
+
+This balance allows the Yocto Project team to deliver the most
+up-to-date Yocto Linux kernel possible, while still ensuring that the
+team has a stable official release for the baseline Linux kernel
+version.
+
+As implied earlier, the ultimate source for Yocto Linux kernels are
+released kernels from ``kernel.org``. In addition to a foundational
+kernel from ``kernel.org``, the available Yocto Linux kernels contain a
+mix of important new mainline developments, non-mainline developments
+(when no alternative exists), Board Support Package (BSP) developments,
+and custom features. These additions result in a commercially released
+Yocto Project Linux kernel that caters to specific embedded designer
+needs for targeted hardware.
+
+You can find a web interface to the Yocto Linux kernels in the
+:ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`
+at :yocto_git:`/`. If you look at the interface, you will see to
+the left a grouping of Git repositories titled "Yocto Linux Kernel".
+Within this group, you will find several Linux Yocto kernels developed
+and included with Yocto Project releases:
+
+-  *linux-yocto-4.1:* The stable Yocto Project kernel to use with
+   the Yocto Project Release 2.0. This kernel is based on the Linux 4.1
+   released kernel.
+
+-  *linux-yocto-4.4:* The stable Yocto Project kernel to use with
+   the Yocto Project Release 2.1. This kernel is based on the Linux 4.4
+   released kernel.
+
+-  *linux-yocto-4.6:* A temporary kernel that is not tied to any
+   Yocto Project release.
+
+-  *linux-yocto-4.8:* The stable yocto Project kernel to use with
+   the Yocto Project Release 2.2.
+
+-  *linux-yocto-4.9:* The stable Yocto Project kernel to use with
+   the Yocto Project Release 2.3. This kernel is based on the Linux 4.9
+   released kernel.
+
+-  *linux-yocto-4.10:* The default stable Yocto Project kernel to
+   use with the Yocto Project Release 2.3. This kernel is based on the
+   Linux 4.10 released kernel.
+
+-  *linux-yocto-4.12:* The default stable Yocto Project kernel to
+   use with the Yocto Project Release 2.4. This kernel is based on the
+   Linux 4.12 released kernel.
+
+-  *yocto-kernel-cache:* The ``linux-yocto-cache`` contains patches
+   and configurations for the linux-yocto kernel tree. This repository
+   is useful when working on the linux-yocto kernel. For more
+   information on this "Advanced Kernel Metadata", see the
+   ":doc:`kernel-dev-advanced`" Chapter.
+
+-  *linux-yocto-dev:* A development kernel based on the latest
+   upstream release candidate available.
+
+.. note::
+
+   Long Term Support Initiative (LTSI) for Yocto Linux kernels is as
+   follows:
+
+   -  For Yocto Project releases 1.7, 1.8, and 2.0, the LTSI kernel is
+      ``linux-yocto-3.14``.
+
+   -  For Yocto Project releases 2.1, 2.2, and 2.3, the LTSI kernel is
+      ``linux-yocto-4.1``.
+
+   -  For Yocto Project release 2.4, the LTSI kernel is
+      ``linux-yocto-4.9``
+
+   -  ``linux-yocto-4.4`` is an LTS kernel.
+
+Once a Yocto Linux kernel is officially released, the Yocto Project team
+goes into their next development cycle, or upward revision (uprev)
+cycle, while still continuing maintenance on the released kernel. It is
+important to note that the most sustainable and stable way to include
+feature development upstream is through a kernel uprev process.
+Back-porting hundreds of individual fixes and minor features from
+various kernel versions is not sustainable and can easily compromise
+quality.
+
+During the uprev cycle, the Yocto Project team uses an ongoing analysis
+of Linux kernel development, BSP support, and release timing to select
+the best possible ``kernel.org`` Linux kernel version on which to base
+subsequent Yocto Linux kernel development. The team continually monitors
+Linux community kernel development to look for significant features of
+interest. The team does consider back-porting large features if they
+have a significant advantage. User or community demand can also trigger
+a back-port or creation of new functionality in the Yocto Project
+baseline kernel during the uprev cycle.
+
+Generally speaking, every new Linux kernel both adds features and
+introduces new bugs. These consequences are the basic properties of
+upstream Linux kernel development and are managed by the Yocto Project
+team's Yocto Linux kernel development strategy. It is the Yocto Project
+team's policy to not back-port minor features to the released Yocto
+Linux kernel. They only consider back-porting significant technological
+jumps - and, that is done after a complete gap analysis. The reason
+for this policy is that back-porting any small to medium sized change
+from an evolving Linux kernel can easily create mismatches,
+incompatibilities and very subtle errors.
+
+The policies described in this section result in both a stable and a
+cutting edge Yocto Linux kernel that mixes forward ports of existing
+Linux kernel features and significant and critical new functionality.
+Forward porting Linux kernel functionality into the Yocto Linux kernels
+available through the Yocto Project can be thought of as a "micro
+uprev". The many "micro uprevs" produce a Yocto Linux kernel version
+with a mix of important new mainline, non-mainline, BSP developments and
+feature integrations. This Yocto Linux kernel gives insight into new
+features and allows focused amounts of testing to be done on the kernel,
+which prevents surprises when selecting the next major uprev. The
+quality of these cutting edge Yocto Linux kernels is evolving and the
+kernels are used in leading edge feature and BSP development.
+
+Yocto Linux Kernel Architecture and Branching Strategies
+========================================================
+
+As mentioned earlier, a key goal of the Yocto Project is to present the
+developer with a kernel that has a clear and continuous history that is
+visible to the user. The architecture and mechanisms, in particular the
+branching strategies, used achieve that goal in a manner similar to
+upstream Linux kernel development in ``kernel.org``.
+
+You can think of a Yocto Linux kernel as consisting of a baseline Linux
+kernel with added features logically structured on top of the baseline.
+The features are tagged and organized by way of a branching strategy
+implemented by the Yocto Project team using the Source Code Manager
+(SCM) Git.
+
+.. note::
+
+   -  Git is the obvious SCM for meeting the Yocto Linux kernel
+      organizational and structural goals described in this section. Not
+      only is Git the SCM for Linux kernel development in ``kernel.org``
+      but, Git continues to grow in popularity and supports many
+      different work flows, front-ends and management techniques.
+
+   -  You can find documentation on Git at https://git-scm.com/doc. You can
+      also get an introduction to Git as it applies to the Yocto Project in the
+      ":ref:`overview-manual/overview-manual-development-environment:git`" section in the Yocto Project
+      Overview and Concepts Manual. The latter reference provides an
+      overview of Git and presents a minimal set of Git commands that
+      allows you to be functional using Git. You can use as much, or as
+      little, of what Git has to offer to accomplish what you need for
+      your project. You do not have to be a "Git Expert" in order to use
+      it with the Yocto Project.
+
+Using Git's tagging and branching features, the Yocto Project team
+creates kernel branches at points where functionality is no longer
+shared and thus, needs to be isolated. For example, board-specific
+incompatibilities would require different functionality and would
+require a branch to separate the features. Likewise, for specific kernel
+features, the same branching strategy is used.
+
+This "tree-like" architecture results in a structure that has features
+organized to be specific for particular functionality, single kernel
+types, or a subset of kernel types. Thus, the user has the ability to
+see the added features and the commits that make up those features. In
+addition to being able to see added features, the user can also view the
+history of what made up the baseline Linux kernel.
+
+Another consequence of this strategy results in not having to store the
+same feature twice internally in the tree. Rather, the kernel team
+stores the unique differences required to apply the feature onto the
+kernel type in question.
+
+.. note::
+
+   The Yocto Project team strives to place features in the tree such
+   that features can be shared by all boards and kernel types where
+   possible. However, during development cycles or when large features
+   are merged, the team cannot always follow this practice. In those
+   cases, the team uses isolated branches to merge features.
+
+BSP-specific code additions are handled in a similar manner to
+kernel-specific additions. Some BSPs only make sense given certain
+kernel types. So, for these types, the team creates branches off the end
+of that kernel type for all of the BSPs that are supported on that
+kernel type. From the perspective of the tools that create the BSP
+branch, the BSP is really no different than a feature. Consequently, the
+same branching strategy applies to BSPs as it does to kernel features.
+So again, rather than store the BSP twice, the team only stores the
+unique differences for the BSP across the supported multiple kernels.
+
+While this strategy can result in a tree with a significant number of
+branches, it is important to realize that from the developer's point of
+view, there is a linear path that travels from the baseline
+``kernel.org``, through a select group of features and ends with their
+BSP-specific commits. In other words, the divisions of the kernel are
+transparent and are not relevant to the developer on a day-to-day basis.
+From the developer's perspective, this path is the "master" branch in
+Git terms. The developer does not need to be aware of the existence of
+any other branches at all. Of course, value exists in the having these
+branches in the tree, should a person decide to explore them. For
+example, a comparison between two BSPs at either the commit level or at
+the line-by-line code ``diff`` level is now a trivial operation.
+
+The following illustration shows the conceptual Yocto Linux kernel.
+
+.. image:: figures/kernel-architecture-overview.png
+   :align: center
+
+In the illustration, the "Kernel.org Branch Point" marks the specific
+spot (or Linux kernel release) from which the Yocto Linux kernel is
+created. From this point forward in the tree, features and differences
+are organized and tagged.
+
+The "Yocto Project Baseline Kernel" contains functionality that is
+common to every kernel type and BSP that is organized further along in
+the tree. Placing these common features in the tree this way means
+features do not have to be duplicated along individual branches of the
+tree structure.
+
+From the "Yocto Project Baseline Kernel", branch points represent
+specific functionality for individual Board Support Packages (BSPs) as
+well as real-time kernels. The illustration represents this through
+three BSP-specific branches and a real-time kernel branch. Each branch
+represents some unique functionality for the BSP or for a real-time
+Yocto Linux kernel.
+
+In this example structure, the "Real-time (rt) Kernel" branch has common
+features for all real-time Yocto Linux kernels and contains more
+branches for individual BSP-specific real-time kernels. The illustration
+shows three branches as an example. Each branch points the way to
+specific, unique features for a respective real-time kernel as they
+apply to a given BSP.
+
+The resulting tree structure presents a clear path of markers (or
+branches) to the developer that, for all practical purposes, is the
+Yocto Linux kernel needed for any given set of requirements.
+
+.. note::
+
+   Keep in mind the figure does not take into account all the supported
+   Yocto Linux kernels, but rather shows a single generic kernel just
+   for conceptual purposes. Also keep in mind that this structure
+   represents the
+   :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`
+   that are either pulled from during the build or established on the
+   host development system prior to the build by either cloning a
+   particular kernel's Git repository or by downloading and unpacking a
+   tarball.
+
+Working with the kernel as a structured tree follows recognized
+community best practices. In particular, the kernel as shipped with the
+product, should be considered an "upstream source" and viewed as a
+series of historical and documented modifications (commits). These
+modifications represent the development and stabilization done by the
+Yocto Project kernel development team.
+
+Because commits only change at significant release points in the product
+life cycle, developers can work on a branch created from the last
+relevant commit in the shipped Yocto Project Linux kernel. As mentioned
+previously, the structure is transparent to the developer because the
+kernel tree is left in this state after cloning and building the kernel.
+
+Kernel Build File Hierarchy
+===========================
+
+Upstream storage of all the available kernel source code is one thing,
+while representing and using the code on your host development system is
+another. Conceptually, you can think of the kernel source repositories
+as all the source files necessary for all the supported Yocto Linux
+kernels. As a developer, you are just interested in the source files for
+the kernel on which you are working. And, furthermore, you need them
+available on your host system.
+
+Kernel source code is available on your host system several different
+ways:
+
+-  *Files Accessed While using devtool:* ``devtool``, which is
+   available with the Yocto Project, is the preferred method by which to
+   modify the kernel. See the ":ref:`kernel-dev/kernel-dev-intro:kernel modification workflow`" section.
+
+-  *Cloned Repository:* If you are working in the kernel all the time,
+   you probably would want to set up your own local Git repository of
+   the Yocto Linux kernel tree. For information on how to clone a Yocto
+   Linux kernel Git repository, see the
+   ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`"
+   section.
+
+-  *Temporary Source Files from a Build:* If you just need to make some
+   patches to the kernel using a traditional BitBake workflow (i.e. not
+   using the ``devtool``), you can access temporary kernel source files
+   that were extracted and used during a kernel build.
+
+The temporary kernel source files resulting from a build using BitBake
+have a particular hierarchy. When you build the kernel on your
+development system, all files needed for the build are taken from the
+source repositories pointed to by the
+:term:`SRC_URI` variable and gathered
+in a temporary work area where they are subsequently used to create the
+unique kernel. Thus, in a sense, the process constructs a local source
+tree specific to your kernel from which to generate the new kernel
+image.
+
+The following figure shows the temporary file structure created on your
+host system when you build the kernel using Bitbake. This
+:term:`Build Directory` contains all the
+source files used during the build.
+
+.. image:: figures/kernel-overview-2-generic.png
+   :align: center
+
+Again, for additional information on the Yocto Project kernel's
+architecture and its branching strategy, see the
+":ref:`kernel-dev/kernel-dev-concepts-appx:yocto linux kernel architecture and branching strategies`"
+section. You can also reference the
+":ref:`kernel-dev/kernel-dev-common:using \`\`devtool\`\` to patch the kernel`"
+and
+":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`"
+sections for detailed example that modifies the kernel.
+
+Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase
+=======================================================================================
+
+This section describes part of the kernel configuration audit phase that
+most developers can ignore. For general information on kernel
+configuration including ``menuconfig``, ``defconfig`` files, and
+configuration fragments, see the
+":ref:`kernel-dev/kernel-dev-common:configuring the kernel`" section.
+
+During this part of the audit phase, the contents of the final
+``.config`` file are compared against the fragments specified by the
+system. These fragments can be system fragments, distro fragments, or
+user-specified configuration elements. Regardless of their origin, the
+OpenEmbedded build system warns the user if a specific option is not
+included in the final kernel configuration.
+
+By default, in order to not overwhelm the user with configuration
+warnings, the system only reports missing "hardware" options as they
+could result in a boot failure or indicate that important hardware is
+not available.
+
+To determine whether or not a given option is "hardware" or
+"non-hardware", the kernel Metadata in ``yocto-kernel-cache`` contains
+files that classify individual or groups of options as either hardware
+or non-hardware. To better show this, consider a situation where the
+``yocto-kernel-cache`` contains the following files:
+::
+
+   yocto-kernel-cache/features/drm-psb/hardware.cfg
+   yocto-kernel-cache/features/kgdb/hardware.cfg
+   yocto-kernel-cache/ktypes/base/hardware.cfg
+   yocto-kernel-cache/bsp/mti-malta32/hardware.cfg
+   yocto-kernel-cache/bsp/qemu-ppc32/hardware.cfg
+   yocto-kernel-cache/bsp/qemuarma9/hardware.cfg
+   yocto-kernel-cache/bsp/mti-malta64/hardware.cfg
+   yocto-kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg
+   yocto-kernel-cache/bsp/common-pc/hardware.cfg
+   yocto-kernel-cache/bsp/common-pc-64/hardware.cfg
+   yocto-kernel-cache/features/rfkill/non-hardware.cfg
+   yocto-kernel-cache/ktypes/base/non-hardware.cfg
+   yocto-kernel-cache/features/aufs/non-hardware.kcf
+   yocto-kernel-cache/features/ocf/non-hardware.kcf
+   yocto-kernel-cache/ktypes/base/non-hardware.kcf
+   yocto-kernel-cache/ktypes/base/hardware.kcf
+   yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf
+
+The following list
+provides explanations for the various files:
+
+-  ``hardware.kcf``: Specifies a list of kernel Kconfig files that
+   contain hardware options only.
+
+-  ``non-hardware.kcf``: Specifies a list of kernel Kconfig files that
+   contain non-hardware options only.
+
+-  ``hardware.cfg``: Specifies a list of kernel ``CONFIG_`` options that
+   are hardware, regardless of whether or not they are within a Kconfig
+   file specified by a hardware or non-hardware Kconfig file (i.e.
+   ``hardware.kcf`` or ``non-hardware.kcf``).
+
+-  ``non-hardware.cfg``: Specifies a list of kernel ``CONFIG_`` options
+   that are not hardware, regardless of whether or not they are within a
+   Kconfig file specified by a hardware or non-hardware Kconfig file
+   (i.e. ``hardware.kcf`` or ``non-hardware.kcf``).
+
+Here is a specific example using the
+``kernel-cache/bsp/mti-malta32/hardware.cfg``:
+::
+
+   CONFIG_SERIAL_8250
+   CONFIG_SERIAL_8250_CONSOLE
+   CONFIG_SERIAL_8250_NR_UARTS
+   CONFIG_SERIAL_8250_PCI
+   CONFIG_SERIAL_CORE
+   CONFIG_SERIAL_CORE_CONSOLE
+   CONFIG_VGA_ARB
+
+The kernel configuration audit automatically detects
+these files (hence the names must be exactly the ones discussed here),
+and uses them as inputs when generating warnings about the final
+``.config`` file.
+
+A user-specified kernel Metadata repository, or recipe space feature,
+can use these same files to classify options that are found within its
+``.cfg`` files as hardware or non-hardware, to prevent the OpenEmbedded
+build system from producing an error or warning when an option is not in
+the final ``.config`` file.

documentation/kernel-dev/kernel-dev-concepts-appx.xml

@@ -1,621 +0,0 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<appendix id='kernel-dev-concepts-appx'>
-<title>Advanced Kernel Concepts</title>
-
-    <section id='kernel-big-picture'>
-        <title>Yocto Project Kernel Development and Maintenance</title>
-
-        <para>
-            Kernels available through the Yocto Project (Yocto Linux kernels),
-            like other kernels, are based off the Linux kernel releases from
-            <ulink url='http://www.kernel.org'></ulink>.
-            At the beginning of a major Linux kernel development cycle, the
-            Yocto Project team chooses a Linux kernel based on factors such as
-            release timing, the anticipated release timing of final upstream
-            <filename>kernel.org</filename> versions, and Yocto Project
-            feature requirements.
-            Typically, the Linux kernel chosen is in the final stages of
-            development by the Linux community.
-            In other words, the Linux kernel is in the release candidate
-            or "rc" phase and has yet to reach final release.
-            But, by being in the final stages of external development, the
-            team knows that the <filename>kernel.org</filename> final release
-            will clearly be within the early stages of the Yocto Project
-            development window.
-        </para>
-
-        <para>
-            This balance allows the Yocto Project team to deliver the most
-            up-to-date Yocto Linux kernel possible, while still ensuring that
-            the team has a stable official release for the baseline Linux
-            kernel version.
-        </para>
-
-        <para>
-            As implied earlier, the ultimate source for Yocto Linux kernels
-            are released kernels from <filename>kernel.org</filename>.
-            In addition to a foundational kernel from
-            <filename>kernel.org</filename>, the available Yocto Linux kernels
-            contain a mix of important new mainline developments, non-mainline
-            developments (when no alternative exists), Board Support Package
-            (BSP) developments, and custom features.
-            These additions result in a commercially released Yocto
-            Project Linux kernel that caters to specific embedded designer
-            needs for targeted hardware.
-        </para>
-
-        <para>
-            You can find a web interface to the Yocto Linux kernels in the
-            <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
-            at
-            <ulink url='&YOCTO_GIT_URL;'></ulink>.
-            If you look at the interface, you will see to the left a
-            grouping of Git repositories titled "Yocto Linux Kernel".
-            Within this group, you will find several Linux Yocto kernels
-            developed and included with Yocto Project releases:
-            <itemizedlist>
-                <listitem><para>
-                    <emphasis><filename>linux-yocto-4.1</filename>:</emphasis>
-                    The stable Yocto Project kernel to use with the Yocto
-                    Project Release 2.0.
-                    This kernel is based on the Linux 4.1 released kernel.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis><filename>linux-yocto-4.4</filename>:</emphasis>
-                    The stable Yocto Project kernel to use with the Yocto
-                    Project Release 2.1.
-                    This kernel is based on the Linux 4.4 released kernel.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis><filename>linux-yocto-4.6</filename>:</emphasis>
-                    A temporary kernel that is not tied to any Yocto Project
-                    release.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis><filename>linux-yocto-4.8</filename>:</emphasis>
-                    The stable yocto Project kernel to use with the Yocto
-                    Project Release 2.2.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis><filename>linux-yocto-4.9</filename>:</emphasis>
-                    The stable Yocto Project kernel to use with the Yocto
-                    Project Release 2.3.
-                    This kernel is based on the Linux 4.9 released kernel.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis><filename>linux-yocto-4.10</filename>:</emphasis>
-                    The default stable Yocto Project kernel to use with the
-                    Yocto Project Release 2.3.
-                    This kernel is based on the Linux 4.10 released kernel.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis><filename>linux-yocto-4.12</filename>:</emphasis>
-                    The default stable Yocto Project kernel to use with the
-                    Yocto Project Release 2.4.
-                    This kernel is based on the Linux 4.12 released kernel.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis><filename>yocto-kernel-cache</filename>:</emphasis>
-                    The <filename>linux-yocto-cache</filename> contains
-                    patches and configurations for the linux-yocto kernel
-                    tree.
-                    This repository is useful when working on the linux-yocto
-                    kernel.
-                    For more information on this "Advanced Kernel Metadata",
-                    see the
-                    "<link linkend='kernel-dev-advanced'>Working With Advanced Metadata (<filename>yocto-kernel-cache</filename>)</link>"
-                    Chapter.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis><filename>linux-yocto-dev</filename>:</emphasis>
-                    A development kernel based on the latest upstream release
-                    candidate available.
-                    </para></listitem>
-            </itemizedlist>
-            <note><title>Notes</title>
-                Long Term Support Initiative (LTSI) for Yocto Linux
-                kernels is as follows:
-                <itemizedlist>
-                    <listitem><para>
-                        For Yocto Project releases 1.7, 1.8, and 2.0,
-                        the LTSI kernel is
-                        <filename>linux-yocto-3.14</filename>.
-                        </para></listitem>
-                    <listitem><para>
-                        For Yocto Project releases 2.1, 2.2, and 2.3,
-                        the LTSI kernel is <filename>linux-yocto-4.1</filename>.
-                        </para></listitem>
-                    <listitem><para>
-                        For Yocto Project release 2.4, the LTSI kernel is
-                        <filename>linux-yocto-4.9</filename>
-                        </para></listitem>
-                    <listitem><para>
-                        <filename>linux-yocto-4.4</filename> is an LTS
-                        kernel.
-                        </para></listitem>
-                </itemizedlist>
-            </note>
-        </para>
-
-        <para>
-            Once a Yocto Linux kernel is officially released, the Yocto
-            Project team goes into their next development cycle, or upward
-            revision (uprev) cycle, while still continuing maintenance on the
-            released kernel.
-            It is important to note that the most sustainable and stable way
-            to include feature development upstream is through a kernel uprev
-            process.
-            Back-porting hundreds of individual fixes and minor features from
-            various kernel versions is not sustainable and can easily
-            compromise quality.
-        </para>
-
-        <para>
-            During the uprev cycle, the Yocto Project team uses an ongoing
-            analysis of Linux kernel development, BSP support, and release
-            timing to select the best possible <filename>kernel.org</filename>
-            Linux kernel version on which to base subsequent Yocto Linux
-            kernel development.
-            The team continually monitors Linux community kernel development
-            to look for significant features of interest.
-            The team does consider back-porting large features if they have a
-            significant advantage.
-            User or community demand can also trigger a back-port or creation
-            of new functionality in the Yocto Project baseline kernel during
-            the uprev cycle.
-        </para>
-
-        <para>
-            Generally speaking, every new Linux kernel both adds features and
-            introduces new bugs.
-            These consequences are the basic properties of upstream
-            Linux kernel development and are managed by the Yocto Project
-            team's Yocto Linux kernel development strategy.
-            It is the Yocto Project team's policy to not back-port minor
-            features to the released Yocto Linux kernel.
-            They only consider back-porting significant technological
-            jumps &dash; and, that is done after a complete gap analysis.
-            The reason for this policy is that back-porting any small to
-            medium sized change from an evolving Linux kernel can easily
-            create mismatches, incompatibilities and very subtle errors.
-        </para>
-
-        <para>
-            The policies described in this section result in both a stable
-            and a cutting edge Yocto Linux kernel that mixes forward ports of
-            existing Linux kernel features and significant and critical new
-            functionality.
-            Forward porting Linux kernel functionality into the Yocto Linux
-            kernels available through the Yocto Project can be thought of as
-            a "micro uprev."
-            The many “micro uprevs” produce a Yocto Linux kernel version with
-            a mix of important new mainline, non-mainline, BSP developments
-            and feature integrations.
-            This Yocto Linux kernel gives insight into new features and
-            allows focused amounts of testing to be done on the kernel,
-            which prevents surprises when selecting the next major uprev.
-            The quality of these cutting edge Yocto Linux kernels is evolving
-            and the kernels are used in leading edge feature and BSP
-            development.
-        </para>
-    </section>
-
-    <section id='yocto-linux-kernel-architecture-and-branching-strategies'>
-        <title>Yocto Linux Kernel Architecture and Branching Strategies</title>
-
-        <para>
-            As mentioned earlier, a key goal of the Yocto Project is
-            to present the developer with a kernel that has a clear and
-            continuous history that is visible to the user.
-            The architecture and mechanisms, in particular the branching
-            strategies, used achieve that goal in a manner similar to
-            upstream Linux kernel development in
-            <filename>kernel.org</filename>.
-        </para>
-
-        <para>
-            You can think of a Yocto Linux kernel as consisting of a
-            baseline Linux kernel with added features logically structured
-            on top of the baseline.
-            The features are tagged and organized by way of a branching
-            strategy implemented by the Yocto Project team using the
-            Source Code Manager (SCM) Git.
-            <note><title>Notes</title>
-                <itemizedlist>
-                    <listitem><para>
-                        Git is the obvious SCM for meeting the Yocto Linux
-                        kernel organizational and structural goals described
-                        in this section.
-                        Not only is Git the SCM for Linux kernel development in
-                        <filename>kernel.org</filename> but, Git continues to
-                         grow in popularity and supports many different work
-                         flows, front-ends and management techniques.
-                        </para></listitem>
-                    <listitem><para>
-                        You can find documentation on Git at
-                        <ulink url='http://git-scm.com/documentation'></ulink>.
-                        You can also get an introduction to Git as it
-                        applies to the Yocto Project in the
-                        "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>"
-                        section in the Yocto Project Overview and Concepts
-                        Manual.
-                        The latter reference provides an overview of
-                        Git and presents a minimal set of Git commands
-                        that allows you to be functional using Git.
-                        You can use as much, or as little, of what Git
-                        has to offer to accomplish what you need for your
-                        project.
-                        You do not have to be a "Git Expert" in order to
-                        use it with the Yocto Project.
-                        </para></listitem>
-                </itemizedlist>
-            </note>
-        </para>
-
-        <para>
-            Using Git's tagging and branching features, the Yocto Project
-            team creates kernel branches at points where functionality is
-            no longer shared and thus, needs to be isolated.
-            For example, board-specific incompatibilities would require
-            different functionality and would require a branch to
-            separate the features.
-            Likewise, for specific kernel features, the same branching
-            strategy is used.
-        </para>
-
-        <para>
-            This "tree-like" architecture results in a structure that has
-            features organized to be specific for particular functionality,
-            single kernel types, or a subset of kernel types.
-            Thus, the user has the ability to see the added features and the
-            commits that make up those features.
-            In addition to being able to see added features, the user
-            can also view the history of what made up the baseline
-            Linux kernel.
-        </para>
-
-        <para>
-            Another consequence of this strategy results in not having to
-            store the same feature twice internally in the tree.
-            Rather, the kernel team stores the unique differences required
-            to apply the feature onto the kernel type in question.
-            <note>
-                The Yocto Project team strives to place features in the tree
-                such that features can be shared by all boards and kernel
-                types where possible.
-                However, during development cycles or when large features
-                are merged, the team cannot always follow this practice.
-                In those cases, the team uses isolated branches to merge
-                features.
-            </note>
-        </para>
-
-        <para>
-            BSP-specific code additions are handled in a similar manner to
-            kernel-specific additions.
-            Some BSPs only make sense given certain kernel types.
-            So, for these types, the team creates branches off the end
-            of that kernel type for all of the BSPs that are supported on
-            that kernel type.
-            From the perspective of the tools that create the BSP branch,
-            the BSP is really no different than a feature.
-            Consequently, the same branching strategy applies to BSPs as
-            it does to kernel features.
-            So again, rather than store the BSP twice, the team only
-            stores the unique differences for the BSP across the supported
-            multiple kernels.
-        </para>
-
-        <para>
-            While this strategy can result in a tree with a significant number
-            of branches, it is important to realize that from the developer's
-            point of view, there is a linear path that travels from the
-            baseline <filename>kernel.org</filename>, through a select
-            group of features and ends with their BSP-specific commits.
-            In other words, the divisions of the kernel are transparent and
-            are not relevant to the developer on a day-to-day basis.
-            From the developer's perspective, this path is the "master" branch
-            in Git terms.
-            The developer does not need to be aware of the existence of any
-            other branches at all.
-            Of course, value exists in the having these branches in the tree,
-            should a person decide to explore them.
-            For example, a comparison between two BSPs at either the commit
-            level or at the line-by-line code <filename>diff</filename> level
-            is now a trivial operation.
-        </para>
-
-        <para>
-            The following illustration shows the conceptual Yocto
-            Linux kernel.
-            <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
-        </para>
-
-        <para>
-            In the illustration, the "Kernel.org Branch Point" marks the
-            specific spot (or Linux kernel release) from which the
-            Yocto Linux kernel is created.
-            From this point forward in the tree, features and differences
-            are organized and tagged.
-        </para>
-
-        <para>
-            The "Yocto Project Baseline Kernel" contains functionality that
-            is common to every kernel type and BSP that is organized
-            further along in the tree.
-            Placing these common features in the tree this way means
-            features do not have to be duplicated along individual
-            branches of the tree structure.
-        </para>
-
-        <para>
-            From the "Yocto Project Baseline Kernel", branch points represent
-            specific functionality for individual Board Support Packages
-            (BSPs) as well as real-time kernels.
-            The illustration represents this through three BSP-specific
-            branches and a real-time kernel branch.
-            Each branch represents some unique functionality for the BSP
-            or for a real-time Yocto Linux kernel.
-        </para>
-
-        <para>
-            In this example structure, the "Real-time (rt) Kernel" branch has
-            common features for all real-time Yocto Linux kernels and
-            contains more branches for individual BSP-specific real-time
-            kernels.
-            The illustration shows three branches as an example.
-            Each branch points the way to specific, unique features for a
-            respective real-time kernel as they apply to a given BSP.
-        </para>
-
-        <para>
-            The resulting tree structure presents a clear path of markers
-            (or branches) to the developer that, for all practical
-            purposes, is the Yocto Linux kernel needed for any given set of
-            requirements.
-            <note>
-                Keep in mind the figure does not take into account all the
-                supported Yocto Linux kernels, but rather shows a single
-                generic kernel just for conceptual purposes.
-                Also keep in mind that this structure represents the Yocto
-                Project
-                <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
-                that are either pulled from during the build or established
-                on the host development system prior to the build by either
-                cloning a particular kernel's Git repository or by
-                downloading and unpacking a tarball.
-            </note>
-        </para>
-
-        <para>
-            Working with the kernel as a structured tree follows recognized
-            community best practices.
-            In particular, the kernel as shipped with the product, should be
-            considered an "upstream source" and viewed as a series of
-            historical and documented modifications (commits).
-            These modifications represent the development and stabilization
-            done by the Yocto Project kernel development team.
-        </para>
-
-        <para>
-            Because commits only change at significant release points in the
-            product life cycle, developers can work on a branch created
-            from the last relevant commit in the shipped Yocto Project Linux
-            kernel.
-            As mentioned previously, the structure is transparent to the
-            developer because the kernel tree is left in this state after
-            cloning and building the kernel.
-        </para>
-    </section>
-
-    <section id='kernel-build-file-hierarchy'>
-        <title>Kernel Build File Hierarchy</title>
-
-        <para>
-            Upstream storage of all the available kernel source code is
-            one thing, while representing and using the code on your host
-            development system is another.
-            Conceptually, you can think of the kernel source repositories
-            as all the source files necessary for all the supported
-            Yocto Linux kernels.
-            As a developer, you are just interested in the source files
-            for the kernel on which you are working.
-            And, furthermore, you need them available on your host system.
-        </para>
-
-        <para>
-            Kernel source code is available on your host system several
-            different ways:
-            <itemizedlist>
-                <listitem><para>
-                    <emphasis>Files Accessed While using <filename>devtool</filename>:</emphasis>
-                    <filename>devtool</filename>, which is available with the
-                    Yocto Project, is the preferred method by which to
-                    modify the kernel.
-                    See the
-                    "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
-                    section.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Cloned Repository:</emphasis>
-                    If you are working in the kernel all the time, you probably
-                    would want to set up your own local Git repository of the
-                    Yocto Linux kernel tree.
-                    For information on how to clone a Yocto Linux kernel
-                    Git repository, see the
-                    "<link linkend='preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</link>"
-                    section.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Temporary Source Files from a Build:</emphasis>
-                    If you just need to make some patches to the kernel using
-                    a traditional BitBake workflow (i.e. not using the
-                    <filename>devtool</filename>), you can access temporary
-                    kernel source files that were extracted and used during
-                    a kernel build.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-
-        <para>
-            The temporary kernel source files resulting from a build using
-            BitBake have a particular hierarchy.
-            When you build the kernel on your development system, all files
-            needed for the build are taken from the source repositories
-            pointed to by the
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
-            variable and gathered in a temporary work area where they are
-            subsequently used to create the unique kernel.
-            Thus, in a sense, the process constructs a local source tree
-            specific to your kernel from which to generate the new kernel
-            image.
-        </para>
-
-        <para>
-            The following figure shows the temporary file structure
-            created on your host system when you build the kernel using
-            Bitbake.
-            This
-            <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
-            contains all the source files used during the build.
-            <imagedata fileref="figures/kernel-overview-2-generic.png"
-                width="6in" depth="5in" align="center" scale="100" />
-        </para>
-
-        <para>
-            Again, for additional information on the Yocto Project kernel's
-            architecture and its branching strategy, see the
-            "<link linkend='yocto-linux-kernel-architecture-and-branching-strategies'>Yocto Linux Kernel Architecture and Branching Strategies</link>"
-            section.
-            You can also reference the
-            "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
-            and
-            "<link linkend='using-traditional-kernel-development-to-patch-the-kernel'>Using Traditional Kernel Development to Patch the Kernel</link>"
-            sections for detailed example that modifies the kernel.
-        </para>
-    </section>
-
-    <section id='determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase'>
-        <title>Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase</title>
-
-        <para>
-            This section describes part of the kernel configuration audit
-            phase that most developers can ignore.
-            For general information on kernel configuration including
-            <filename>menuconfig</filename>, <filename>defconfig</filename>
-            files, and configuration fragments, see the
-            "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>"
-            section.
-        </para>
-
-        <para>
-            During this part of the audit phase, the contents of the final
-            <filename>.config</filename> file are compared against the
-            fragments specified by the system.
-            These fragments can be system fragments, distro fragments,
-            or user-specified configuration elements.
-            Regardless of their origin, the OpenEmbedded build system
-            warns the user if a specific option is not included in the
-            final kernel configuration.
-        </para>
-
-        <para>
-            By default, in order to not overwhelm the user with
-            configuration warnings, the system only reports missing
-            "hardware" options as they could result in a boot
-            failure or indicate that important hardware is not available.
-        </para>
-
-        <para>
-            To determine whether or not a given option is "hardware" or
-            "non-hardware", the kernel Metadata in
-            <filename>yocto-kernel-cache</filename> contains files that
-            classify individual or groups of options as either hardware
-            or non-hardware.
-            To better show this, consider a situation where the
-            <filename>yocto-kernel-cache</filename> contains the following
-            files:
-            <literallayout class='monospaced'>
-     yocto-kernel-cache/features/drm-psb/hardware.cfg
-     yocto-kernel-cache/features/kgdb/hardware.cfg
-     yocto-kernel-cache/ktypes/base/hardware.cfg
-     yocto-kernel-cache/bsp/mti-malta32/hardware.cfg
-     yocto-kernel-cache/bsp/qemu-ppc32/hardware.cfg
-     yocto-kernel-cache/bsp/qemuarma9/hardware.cfg
-     yocto-kernel-cache/bsp/mti-malta64/hardware.cfg
-     yocto-kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg
-     yocto-kernel-cache/bsp/common-pc/hardware.cfg
-     yocto-kernel-cache/bsp/common-pc-64/hardware.cfg
-     yocto-kernel-cache/features/rfkill/non-hardware.cfg
-     yocto-kernel-cache/ktypes/base/non-hardware.cfg
-     yocto-kernel-cache/features/aufs/non-hardware.kcf
-     yocto-kernel-cache/features/ocf/non-hardware.kcf
-     yocto-kernel-cache/ktypes/base/non-hardware.kcf
-     yocto-kernel-cache/ktypes/base/hardware.kcf
-     yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf
-            </literallayout>
-            The following list provides explanations for the various
-            files:
-            <itemizedlist>
-                <listitem><para>
-                    <filename>hardware.kcf</filename>:
-                    Specifies a list of kernel Kconfig files that contain
-                    hardware options only.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>non-hardware.kcf</filename>:
-                    Specifies a list of kernel Kconfig files that contain
-                    non-hardware options only.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>hardware.cfg</filename>:
-                    Specifies a list of kernel <filename>CONFIG_</filename>
-                    options that are hardware, regardless of whether or not
-                    they are within a Kconfig file specified by a hardware
-                    or non-hardware Kconfig file (i.e.
-                    <filename>hardware.kcf</filename> or
-                    <filename>non-hardware.kcf</filename>).
-                    </para></listitem>
-                <listitem><para>
-                    <filename>non-hardware.cfg</filename>:
-                    Specifies a list of kernel <filename>CONFIG_</filename>
-                    options that are not hardware, regardless of whether or
-                    not they are within a Kconfig file specified by a
-                    hardware or non-hardware Kconfig file (i.e.
-                    <filename>hardware.kcf</filename> or
-                    <filename>non-hardware.kcf</filename>).
-                    </para></listitem>
-            </itemizedlist>
-            Here is a specific example using the
-            <filename>kernel-cache/bsp/mti-malta32/hardware.cfg</filename>:
-            <literallayout class='monospaced'>
-     CONFIG_SERIAL_8250
-     CONFIG_SERIAL_8250_CONSOLE
-     CONFIG_SERIAL_8250_NR_UARTS
-     CONFIG_SERIAL_8250_PCI
-     CONFIG_SERIAL_CORE
-     CONFIG_SERIAL_CORE_CONSOLE
-     CONFIG_VGA_ARB
-            </literallayout>
-            The kernel configuration audit automatically detects these
-            files (hence the names must be exactly the ones discussed here),
-            and uses them as inputs when generating warnings about the
-            final <filename>.config</filename> file.
-        </para>
-
-        <para>
-            A user-specified kernel Metadata repository, or recipe space
-            feature, can use these same files to classify options that are
-            found within its <filename>.cfg</filename> files as hardware
-            or non-hardware, to prevent the OpenEmbedded build system from
-            producing an error or warning when an option is not in the
-            final <filename>.config</filename> file.
-        </para>
-    </section>
-</appendix>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/kernel-dev/kernel-dev-customization.xsl

@@ -1,26 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
-
-  <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-<!--
-
-  <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-  <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
-
--->
-
-  <xsl:include href="../template/permalinks.xsl"/>
-  <xsl:include href="../template/section.title.xsl"/>
-  <xsl:include href="../template/component.title.xsl"/>
-  <xsl:include href="../template/division.title.xsl"/>
-  <xsl:include href="../template/formal.object.heading.xsl"/>
-
-  <xsl:param name="html.stylesheet" select="'kernel-dev-style.css'" />
-  <xsl:param name="chapter.autolabel" select="1" />
-  <xsl:param name="appendix.autolabel">A</xsl:param>
-  <xsl:param name="section.autolabel" select="1" />
-  <xsl:param name="section.label.includes.component.label" select="1" />
-
-</xsl:stylesheet>