local.conf: Drop support for mklibs

This is not enabled or tested by default, and has never been
ported to python 3 upstream[1], which means it doesn't work at all
with plain poky. If you need it, please put it in a separate layer
and/or modernize to work with py3.

https://salsa.debian.org/installer-team/mklibs/-/blob/master/src/mklibs

(From meta-yocto rev: c8c8f284eb2abe7e1352850a885454487cc01986)

Signed-off-by: Alexander Kanavin <alex.kanavin@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

bitbake/bin/bitbake

@@ -26,7 +26,7 @@ from bb.main import bitbake_main, BitBakeConfigParameters, BBMainException
 if sys.getfilesystemencoding() != "utf-8":
     sys.exit("Please use a locale setting which supports UTF-8 (such as LANG=en_US.UTF-8).\nPython can't change the filesystem locale after loading so we need a UTF-8 when Python starts or things won't work.")
 
-__version__ = "1.49.2"
+__version__ = "1.51.0"
 
 if __name__ == "__main__":
     if __version__ != bb.__version__:

bitbake/bin/bitbake-getvar

@@ -0,0 +1,48 @@
+#! /usr/bin/env python3
+#
+# Copyright (C) 2021 Richard Purdie
+#
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+import argparse
+import io
+import os
+import sys
+
+bindir = os.path.dirname(__file__)
+topdir = os.path.dirname(bindir)
+sys.path[0:0] = [os.path.join(topdir, 'lib')]
+
+import bb.tinfoil
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Bitbake Query Variable")
+    parser.add_argument("variable", help="variable name to query")
+    parser.add_argument("-r", "--recipe", help="Recipe name to query", default=None, required=False)
+    parser.add_argument('-u', '--unexpand', help='Do not expand the value (with --value)', action="store_true")
+    parser.add_argument('-f', '--flag', help='Specify a variable flag to query (with --value)', default=None)
+    parser.add_argument('--value', help='Only report the value, no history and no variable name', action="store_true")
+    args = parser.parse_args()
+
+    if args.unexpand and not args.value:
+        print("--unexpand only makes sense with --value")
+        sys.exit(1)
+
+    if args.flag and not args.value:
+        print("--flag only makes sense with --value")
+        sys.exit(1)
+
+    with bb.tinfoil.Tinfoil(tracking=True) as tinfoil:
+        if args.recipe:
+            tinfoil.prepare(quiet=2)
+            d = tinfoil.parse_recipe(args.recipe)
+        else:
+            tinfoil.prepare(quiet=2, config_only=True)
+            d = tinfoil.config_data
+        if args.flag:
+            print(str(d.getVarFlag(args.variable, args.flag, expand=(not args.unexpand))))
+        elif args.value:
+            print(str(d.getVar(args.variable, expand=(not args.unexpand))))
+        else:
+            bb.data.emit_var(args.variable, d=d, all=True)

bitbake/bin/bitbake-server

@@ -26,12 +26,10 @@ readypipeinfd = int(sys.argv[3])
 logfile = sys.argv[4]
 lockname = sys.argv[5]
 sockname = sys.argv[6]
-timeout = sys.argv[7]
+timeout = float(sys.argv[7])
 xmlrpcinterface = (sys.argv[8], int(sys.argv[9]))
 if xmlrpcinterface[0] == "None":
     xmlrpcinterface = (None, xmlrpcinterface[1])
-if timeout == "None":
-    timeout = None
 
 # Replace standard fds with our own
 with open('/dev/null', 'r') as si:

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

@@ -16,7 +16,7 @@ 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: ::
+using the following command form::
 
   $ bitbake target
 
@@ -32,7 +32,7 @@ the BitBake command and its options, see ":ref:`The BitBake Command
    your project's ``local.conf`` configuration file.
 
    A common method to determine this value for your build host is to run
-   the following: ::
+   the following::
 
      $ grep processor /proc/cpuinfo
 
@@ -139,7 +139,7 @@ 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: ::
+command::
 
   $ bitbake -e > mybb.log
 
@@ -155,7 +155,7 @@ execution environment.
    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: ::
+   Here is an example that causes BitBake to produce a parsing error::
 
       fakeroot create_shar() {
          cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
@@ -185,7 +185,7 @@ 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: ::
+supports wildcards. An example would be::
 
   BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend"
 
@@ -206,7 +206,7 @@ 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`: ::
+: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'}"
@@ -238,7 +238,7 @@ 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: ::
+want upstream. Here is an example::
 
   BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb"
   BBFILE_COLLECTIONS = "upstream local"
@@ -270,7 +270,7 @@ 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: ::
+contained the following::
 
   PROVIDES += "fullkeyboard"
 
@@ -291,7 +291,7 @@ 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: ::
+line similar to the following in the machine configuration file::
 
   PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
 
@@ -331,7 +331,7 @@ If the first recipe is named ``a_1.1.bb``, then the
 
 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: ::
+file that BitBake parses, you can change that preference::
 
   PREFERRED_VERSION_a = "1.1"
 
@@ -498,7 +498,7 @@ 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: ::
+to ignore a dependency by using a line like the following::
 
   PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
 
@@ -508,7 +508,7 @@ 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: ::
+following::
 
   PACKAGE_ARCHS[vardeps] = "MACHINE"
 
@@ -536,7 +536,7 @@ 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: ::
+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 \
@@ -557,7 +557,7 @@ 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: ::
+``bitbake.conf`` file::
 
   BB_SIGNATURE_HANDLER ?= "OEBasicHash"
 

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

@@ -27,7 +27,7 @@ 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: ::
+something like the following::
 
    src_uri = (d.getVar('SRC_URI') or "").split()
    fetcher = bb.fetch2.Fetch(src_uri, d)
@@ -37,7 +37,7 @@ 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: ::
+The instantiation of the fetch class is usually followed by::
 
    rootdir = l.getVar('WORKDIR')
    fetcher.unpack(rootdir)
@@ -72,7 +72,7 @@ URLs by looking for source files in a specific search order:
 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: ::
+Consider the following two URLs::
 
    http://git.yoctoproject.org/git/poky;protocol=git
    git://git.yoctoproject.org/git/poky;protocol=http
@@ -81,7 +81,7 @@ 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: ::
+Here are some examples that show commonly used mirror definitions::
 
    PREMIRRORS ?= "\
       bzr://.*/.\*  http://somemirror.org/sources/ \\n \
@@ -111,19 +111,19 @@ 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: ::
+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: ::
+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: ::
+shows how you name the URIs::
 
    SRC_URI = "http://example.com/foobar.tar.bz2;name=foo"
    SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d
@@ -163,9 +163,6 @@ govern the behavior of the unpack stage:
 -  *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.
 
@@ -204,7 +201,7 @@ 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: ::
+absolute::
 
    SRC_URI = "file://relativefile.patch"
    SRC_URI = "file:///Users/ich/very_important_software"
@@ -225,7 +222,7 @@ 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: ::
+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"
@@ -235,15 +232,13 @@ Some example URLs are as follows: ::
 
    Because URL parameters are delimited by semi-colons, this can
    introduce ambiguity when parsing URLs that also contain semi-colons,
-   for example:
-   ::
+   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:
-   ::
+   characters::
 
            SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47"
 
@@ -251,8 +246,7 @@ Some example URLs are as follows: ::
    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:
-   ::
+   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"
 
@@ -321,7 +315,7 @@ The supported parameters are as follows:
 
 -  *"port":* The port to which the CVS server connects.
 
-Some example URLs are as follows: ::
+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"
@@ -363,7 +357,7 @@ The supported parameters are as follows:
    username is different than the username used in the main URL, which
    is passed to the subversion command.
 
-Following are three examples using svn: ::
+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"
@@ -436,11 +430,20 @@ This fetcher supports the following parameters:
    parameter implies no branch and only works when the transfer protocol
    is ``file://``.
 
-Here are some example URLs: ::
+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"
 
+.. note::
+
+   Specifying passwords directly in ``git://`` urls is not supported.
+   There are several reasons: ``SRC_URI`` is often written out to logs and
+   other places, and that could easily leak passwords; it is also all too
+   easy to share metadata without removing passwords. SSH keys, ``~/.netrc``
+   and ``~/.ssh/config`` files can be used as alternatives.
+
+
 .. _gitsm-fetcher:
 
 Git Submodule Fetcher (``gitsm://``)
@@ -475,7 +478,7 @@ repository.
 
 To use this fetcher, make sure your recipe has proper
 :term:`SRC_URI`, :term:`SRCREV`, and
-:term:`PV` settings. Here is an example: ::
+:term:`PV` settings. Here is an example::
 
    SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module"
    SRCREV = "EXAMPLE_CLEARCASE_TAG"
@@ -497,7 +500,7 @@ Following are options for the ``SRC_URI`` statement:
       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: ::
+      results in the following::
 
          load /example_vob/example_module
 
@@ -549,7 +552,7 @@ 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: ::
+and port, username, and password, and fetches the Head Revision::
 
    SRC_URI = "p4://example-depot/main/source/..."
    SRCREV = "${AUTOREV}"
@@ -557,7 +560,7 @@ and port, username, and password, and fetches the Head Revision: ::
    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: ::
+password, and fetches a Revision based on a Label::
 
    P4PORT = "tcp:p4server.example.net:1666"
    SRC_URI = "p4://user:passwd@example-depot/main/source/..."
@@ -583,7 +586,7 @@ paths locally is desirable, the fetcher supports two parameters:
     paths locally for the specified location, even in combination with the
     ``module`` parameter.
 
-Here is an example use of the the ``module`` parameter: ::
+Here is an example use of the the ``module`` parameter::
 
    SRC_URI = "p4://user:passwd@example-depot/main;module=source/..."
 
@@ -591,7 +594,7 @@ In this case, the content of the top-level directory ``source/`` will be fetched
 to ``${P4DIR}``, including the directory itself.  The top-level directory will
 be accesible at ``${P4DIR}/source/``.
 
-Here is an example use of the the ``remotepath`` parameter: ::
+Here is an example use of the the ``remotepath`` parameter::
 
    SRC_URI = "p4://user:passwd@example-depot/main;module=source/...;remotepath=keep"
 
@@ -619,7 +622,7 @@ This fetcher supports the following parameters:
 
 -  *"manifest":* Name of the manifest file (default: ``default.xml``).
 
-Here are some example URLs: ::
+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"
@@ -642,11 +645,11 @@ Such functionality is set by the variable:
    delegate access to resources, if this variable is set, the Az Fetcher will
    use it when fetching artifacts from the cloud.
 
-You can specify the AZ_SAS variable as shown below: ::
+You can specify the AZ_SAS variable as shown below::
 
    AZ_SAS = "se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>"
 
-Here is an example URL: ::
+Here is an example URL::
 
    SRC_URI = "az://<azure-storage-account>.blob.core.windows.net/<foo_container>/<bar_file>"
 

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

@@ -20,7 +20,7 @@ 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: ::
+your machine, the BitBake directory appears as follows::
 
    $ ls -al
    total 100
@@ -49,7 +49,7 @@ 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: ::
+command::
 
   $ ./bin/bitbake --version
   BitBake Build Tool Core version 1.23.0, bitbake version 1.23.0
@@ -61,14 +61,14 @@ 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: ::
+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: ::
+``PATH`` variable::
 
   $ export PATH=/home/scott-lenovo/bitbake/bin:$PATH
 
@@ -116,7 +116,7 @@ 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: ::
+    directory::
 
       $ mkdir ~/hello
       $ cd ~/hello
@@ -127,7 +127,7 @@ Following is the complete "Hello World" example.
     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: ::
+    directory. Run the ``bitbake`` command and see what it does::
 
        $ bitbake
        The BBPATH variable is not set and bitbake did not
@@ -161,7 +161,7 @@ Following is the complete "Hello World" example.
     ``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`` variable::
 
       $ BBPATH="projectdirectory"
       $ export BBPATH
@@ -176,7 +176,7 @@ Following is the complete "Hello World" example.
        shell would.
 
 #.  **Run BitBake:** Now that you have ``BBPATH`` defined, run the
-    ``bitbake`` command again: ::
+    ``bitbake`` command again::
 
        $ bitbake
        ERROR: Traceback (most recent call last):
@@ -208,13 +208,13 @@ Following is the complete "Hello World" example.
     http://git.openembedded.org/bitbake/tree/conf/bitbake.conf.
 
     Use the following commands to create the ``conf`` directory in the
-    project directory: ::
+    project directory::
 
       $ mkdir conf
 
     From within the ``conf`` directory,
     use some editor to create the ``bitbake.conf`` so that it contains
-    the following: ::
+    the following::
 
        PN  = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
 
@@ -251,7 +251,7 @@ Following is the complete "Hello World" example.
     glossary.
 
 #.  **Run BitBake:** After making sure that the ``conf/bitbake.conf`` file
-    exists, you can run the ``bitbake`` command again: ::
+    exists, you can run the ``bitbake`` command again::
 
        $ bitbake
        ERROR: Traceback (most recent call last):
@@ -278,7 +278,7 @@ Following is the complete "Hello World" example.
     in the ``classes`` directory of the project (i.e ``hello/classes``
     in this example).
 
-    Create the ``classes`` directory as follows: ::
+    Create the ``classes`` directory as follows::
 
       $ cd $HOME/hello
       $ mkdir classes
@@ -291,7 +291,7 @@ Following is the complete "Hello World" example.
     environments BitBake is supporting.
 
 #.  **Run BitBake:** After making sure that the ``classes/base.bbclass``
-    file exists, you can run the ``bitbake`` command again: ::
+    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.
@@ -314,7 +314,7 @@ Following is the complete "Hello World" example.
     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: ::
+    and the ``conf`` directory::
 
        $ cd $HOME
        $ mkdir mylayer
@@ -322,12 +322,12 @@ Following is the complete "Hello World" example.
        $ mkdir conf
 
     Move to the ``conf`` directory and create a ``layer.conf`` file that has the
-    following: ::
+    following::
 
       BBPATH .= ":${LAYERDIR}"
-      BBFILES += "${LAYERDIR}/\*.bb"
+      BBFILES += "${LAYERDIR}/*.bb"
       BBFILE_COLLECTIONS += "mylayer"
-     `BBFILE_PATTERN_mylayer := "^${LAYERDIR_RE}/"
+      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>`
@@ -335,7 +335,7 @@ Following is the complete "Hello World" example.
 
     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: ::
+    ``printhello.bb`` that has the following::
 
        DESCRIPTION = "Prints Hello World"
        PN = 'printhello'
@@ -356,7 +356,7 @@ Following is the complete "Hello World" example.
     follow the links to the glossary.
 
 #. **Run BitBake With a Target:** Now that a BitBake target exists, run
-    the command and provide that target: ::
+    the command and provide that target::
 
       $ cd $HOME/hello
       $ bitbake printhello
@@ -376,7 +376,7 @@ Following is the complete "Hello World" example.
     ``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: ::
+    create the ``bblayers.conf`` file so that it contains the following::
 
        BBLAYERS ?= " \
            /home/<you>/mylayer \
@@ -386,7 +386,7 @@ Following is the complete "Hello World" example.
 
 #. **Run BitBake With a Target:** Now that you have supplied the
     ``bblayers.conf`` file, run the ``bitbake`` command and provide the
-    target: ::
+    target::
 
        $ bitbake printhello
        Parsing recipes: 100% |##################################################################################|

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

@@ -248,13 +248,13 @@ 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: ::
+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: ::
+the append file would match the following recipe names::
 
   busybox_1.21.1.bb
   busybox_1.21.2.bb
@@ -290,7 +290,7 @@ You can obtain BitBake several different ways:
    are using. The metadata is generally backwards compatible but not
    forward compatible.
 
-   Here is an example that clones the BitBake repository: ::
+   Here is an example that clones the BitBake repository::
 
      $ git clone git://git.openembedded.org/bitbake
 
@@ -298,7 +298,7 @@ You can obtain BitBake several different ways:
    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``: ::
+   is an example that names the directory ``bbdev``::
 
      $ git clone git://git.openembedded.org/bitbake bbdev
 
@@ -317,7 +317,7 @@ You can obtain BitBake several different ways:
          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: ::
+   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
@@ -347,7 +347,7 @@ execution examples.
 Usage and syntax
 ----------------
 
-Following is the usage and syntax for BitBake: ::
+Following is the usage and syntax for BitBake::
 
    $ bitbake -h
    Usage: bitbake [options] [recipename/target recipe:do_task ...]
@@ -469,11 +469,11 @@ 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: ::
+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: ::
+The following command runs the clean task on the ``foo.bb`` recipe file::
 
   $ bitbake -b foo.bb -c clean
 
@@ -497,13 +497,13 @@ 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: ::
+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: ::
+execute the ``do_clean`` task::
 
   $ bitbake -c clean foo
 
@@ -514,7 +514,7 @@ 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: ::
+recipe and ``taskB`` for the second recipe::
 
   $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB
 
@@ -540,7 +540,7 @@ 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: ::
+omits depends common in OpenEmbedded from the graph::
 
   $ bitbake -g foo
 
@@ -582,17 +582,17 @@ accomplished by setting the
 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: ::
+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: ::
+command form to start the builds::
 
   $ bitbake [mc:multiconfigname:]target [[[mc:multiconfigname:]target] ... ]
 
-Here is an example for two extra multiconfigs: ``target1`` and ``target2``: ::
+Here is an example for two extra multiconfigs: ``target1`` and ``target2``::
 
   $ bitbake mc::target mc:target1:target mc:target2:target
 
@@ -613,12 +613,12 @@ multiconfig.
 
 To enable dependencies in a multiple configuration build, you must
 declare the dependencies in the recipe using the following statement
-form: ::
+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``: ::
+multiconfigs: ``target1`` and ``target2``::
 
   image_task[mcdepends] = "mc:target1:target2:image2:rootfs_task"
 
@@ -629,7 +629,7 @@ 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: ::
+using a BitBake command as follows::
 
   $ bitbake mc:target1:image1
 
@@ -639,7 +639,7 @@ 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: ::
+recipe::
 
   image_task[mcdepends] = "mc:target1:target2:image2:image_task"
 

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

@@ -26,7 +26,7 @@ assignment. ::
    VARIABLE = "value"
 
 As expected, if you include leading or
-trailing spaces as part of an assignment, the spaces are retained: ::
+trailing spaces as part of an assignment, the spaces are retained::
 
    VARIABLE = " value"
    VARIABLE = "value "
@@ -40,7 +40,7 @@ blank space (i.e. these are not the same values). ::
 
 You can use single quotes instead of double quotes when setting a
 variable's value. Doing so allows you to use values that contain the
-double quote character: ::
+double quote character::
 
    VARIABLE = 'I have a " in my value'
 
@@ -77,7 +77,7 @@ occurs, you can use BitBake to check the actual value of the suspect
 variable. You can make these checks for both configuration and recipe
 level changes:
 
--  For configuration changes, use the following: ::
+-  For configuration changes, use the following::
 
       $ bitbake -e
 
@@ -91,7 +91,7 @@ level changes:
       Variables that are exported to the environment are preceded by the
       string "export" in the command's output.
 
--  For recipe changes, use the following: ::
+-  For recipe changes, use the following::
 
       $ bitbake recipe -e \| grep VARIABLE="
 
@@ -105,7 +105,7 @@ Outside of :ref:`functions <bitbake-user-manual/bitbake-user-manual-metadata:fun
 BitBake joins any line ending in
 a backslash character ("\") with the following line before parsing
 statements. The most common use for the "\" character is to split
-variable assignments over multiple lines, as in the following example: ::
+variable assignments over multiple lines, as in the following example::
 
    FOO = "bar \
           baz \
@@ -116,7 +116,7 @@ character that follow it are removed when joining lines. Thus, no
 newline characters end up in the value of ``FOO``.
 
 Consider this additional example where the two assignments both assign
-"barbaz" to ``FOO``: ::
+"barbaz" to ``FOO``::
 
    FOO = "barbaz"
    FOO = "bar\
@@ -149,7 +149,7 @@ The "=" operator does not immediately expand variable references in the
 right-hand side. Instead, expansion is deferred until the variable
 assigned to is actually used. The result depends on the current values
 of the referenced variables. The following example should clarify this
-behavior: ::
+behavior::
 
    A = "${B} baz"
    B = "${C} bar"
@@ -177,7 +177,7 @@ Setting a default value (?=)
 You can use the "?=" operator to achieve a "softer" assignment for a
 variable. This type of assignment allows you to define a variable if it
 is undefined when the statement is parsed, but to leave the value alone
-if the variable has a value. Here is an example: ::
+if the variable has a value. Here is an example::
 
    A ?= "aval"
 
@@ -199,7 +199,7 @@ by using the "??=" operator. This assignment behaves identical to "?="
 except that the assignment is made at the end of the parsing process
 rather than immediately. Consequently, when multiple "??=" assignments
 exist, the last one is used. Also, any "=" or "?=" assignment will
-override the value set with "??=". Here is an example: ::
+override the value set with "??=". Here is an example::
 
    A ??= "somevalue"
    A ??= "someothervalue"
@@ -215,7 +215,7 @@ Immediate variable expansion (:=)
 ---------------------------------
 
 The ":=" operator results in a variable's contents being expanded
-immediately, rather than when the variable is actually used: ::
+immediately, rather than when the variable is actually used::
 
    T = "123"
    A := "test ${T}"
@@ -241,7 +241,7 @@ the "+=" and "=+" operators. These operators insert a space between the
 current value and prepended or appended value.
 
 These operators take immediate effect during parsing. Here are some
-examples: ::
+examples::
 
    B = "bval"
    B += "additionaldata"
@@ -260,7 +260,7 @@ If you want to append or prepend values without an inserted space, use
 the ".=" and "=." operators.
 
 These operators take immediate effect during parsing. Here are some
-examples: ::
+examples::
 
    B = "bval"
    B .= "additionaldata"
@@ -278,7 +278,7 @@ style syntax. When you use this syntax, no spaces are inserted.
 
 These operators differ from the ":=", ".=", "=.", "+=", and "=+"
 operators in that their effects are applied at variable expansion time
-rather than being immediately applied. Here are some examples: ::
+rather than being immediately applied. Here are some examples::
 
    B = "bval"
    B_append = " additional data"
@@ -309,7 +309,7 @@ syntax. Specifying a value for removal causes all occurrences of that
 value to be removed from the variable.
 
 When you use this syntax, BitBake expects one or more strings.
-Surrounding spaces and spacing are preserved. Here is an example: ::
+Surrounding spaces and spacing are preserved. Here is an example::
 
    FOO = "123 456 789 123456 123 456 123 456"
    FOO_remove = "123"
@@ -334,27 +334,27 @@ An advantage of the override style operations "_append", "_prepend", and
 "_remove" as compared to the "+=" and "=+" operators is that the
 override style operators provide guaranteed operations. For example,
 consider a class ``foo.bbclass`` that needs to add the value "val" to
-the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows: ::
+the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows::
 
    inherit foo
    FOO = "initial"
 
 If ``foo.bbclass`` uses the "+=" operator,
 as follows, then the final value of ``FOO`` will be "initial", which is
-not what is desired: ::
+not what is desired::
 
    FOO += "val"
 
 If, on the other hand, ``foo.bbclass``
 uses the "_append" operator, then the final value of ``FOO`` will be
-"initial val", as intended: ::
+"initial val", as intended::
 
    FOO_append = " val"
 
 .. note::
 
    It is never necessary to use "+=" together with "_append". The following
-   sequence of assignments appends "barbaz" to FOO: ::
+   sequence of assignments appends "barbaz" to FOO::
 
        FOO_append = "bar"
        FOO_append = "baz"
@@ -381,7 +381,7 @@ standard syntax operations previously mentioned work for variable flags
 except for override style syntax (i.e. "_prepend", "_append", and
 "_remove").
 
-Here are some examples showing how to set variable flags: ::
+Here are some examples showing how to set variable flags::
 
    FOO[a] = "abc"
    FOO[b] = "123"
@@ -393,7 +393,7 @@ respectively. The ``[a]`` flag becomes "abc 456".
 
 No need exists to pre-define variable flags. You can simply start using
 them. One extremely common application is to attach some brief
-documentation to a BitBake variable as follows: ::
+documentation to a BitBake variable as follows::
 
    CACHE[doc] = "The directory holding the cache of the metadata."
 
@@ -401,7 +401,7 @@ Inline Python Variable Expansion
 --------------------------------
 
 You can use inline Python variable expansion to set variables. Here is
-an example: ::
+an example::
 
    DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
 
@@ -410,7 +410,7 @@ This example results in the ``DATE`` variable being set to the current date.
 Probably the most common use of this feature is to extract the value of
 variables from BitBake's internal data dictionary, ``d``. The following
 lines select the values of a package name and its version number,
-respectively: ::
+respectively::
 
    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'}"
@@ -419,12 +419,12 @@ respectively: ::
 
    Inline Python expressions work just like variable expansions insofar as the
    "=" and ":=" operators are concerned. Given the following assignment, foo()
-   is called each time FOO is expanded: ::
+   is called each time FOO is expanded::
 
       FOO = "${@foo()}"
 
    Contrast this with the following immediate assignment, where foo() is only
-   called once, while the assignment is parsed: ::
+   called once, while the assignment is parsed::
 
       FOO := "${@foo()}"
 
@@ -437,7 +437,7 @@ Unsetting variables
 
 It is possible to completely remove a variable or a variable flag from
 BitBake's internal data dictionary by using the "unset" keyword. Here is
-an example: ::
+an example::
 
    unset DATE
    unset do_fetch[noexec]
@@ -452,7 +452,7 @@ When specifying pathnames for use with BitBake, do not use the tilde
 cause BitBake to not recognize the path since BitBake does not expand
 this character in the same way a shell would.
 
-Instead, provide a fuller path as the following example illustrates: ::
+Instead, provide a fuller path as the following example illustrates::
 
    BBLAYERS ?= " \
        /home/scott-lenovo/LayerA \
@@ -463,7 +463,7 @@ Exporting Variables to the Environment
 
 You can export variables to the environment of running tasks by using
 the ``export`` keyword. For example, in the following example, the
-``do_foo`` task prints "value from the environment" when run: ::
+``do_foo`` task prints "value from the environment" when run::
 
    export ENV_VARIABLE
    ENV_VARIABLE = "value from the environment"
@@ -481,7 +481,7 @@ It does not matter whether ``export ENV_VARIABLE`` appears before or
 after assignments to ``ENV_VARIABLE``.
 
 It is also possible to combine ``export`` with setting a value for the
-variable. Here is an example: ::
+variable. Here is an example::
 
    export ENV_VARIABLE = "variable-value"
 
@@ -518,7 +518,7 @@ variable.
    to satisfy conditions. Thus, if you have a variable that is
    conditional on "arm", and "arm" is in ``OVERRIDES``, then the
    "arm"-specific version of the variable is used rather than the
-   non-conditional version. Here is an example: ::
+   non-conditional version. Here is an example::
 
       OVERRIDES = "architecture:os:machine"
       TEST = "default"
@@ -535,7 +535,7 @@ variable.
    an OpenEmbedded metadata-based Linux kernel recipe file. The
    following lines from the recipe file first set the kernel branch
    variable ``KBRANCH`` to a default value, then conditionally override
-   that value based on the architecture of the build: ::
+   that value based on the architecture of the build::
 
       KBRANCH = "standard/base"
       KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
@@ -547,7 +547,7 @@ variable.
 
 -  *Appending and Prepending:* BitBake also supports append and prepend
    operations to variable values based on whether a specific item is
-   listed in ``OVERRIDES``. Here is an example: ::
+   listed in ``OVERRIDES``. Here is an example::
 
       DEPENDS = "glibc ncurses"
       OVERRIDES = "machine:local"
@@ -557,14 +557,14 @@ variable.
 
    Again, using an OpenEmbedded metadata-based kernel recipe file as an
    example, the following lines will conditionally append to the
-   ``KERNEL_FEATURES`` variable based on the architecture: ::
+   ``KERNEL_FEATURES`` variable based on the architecture::
 
       KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
       KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc"
       KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc"
 
 -  *Setting a Variable for a Single Task:* BitBake supports setting a
-   variable just for the duration of a single task. Here is an example: ::
+   variable just for the duration of a single task. Here is an example::
 
       FOO_task-configure = "val 1"
       FOO_task-compile = "val 2"
@@ -580,7 +580,7 @@ variable.
    ``do_compile`` task.
 
    You can also use this syntax with other combinations (e.g.
-   "``_prepend``") as shown in the following example: ::
+   "``_prepend``") as shown in the following example::
 
       EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} "
 
@@ -588,7 +588,7 @@ Key Expansion
 -------------
 
 Key expansion happens when the BitBake datastore is finalized. To better
-understand this, consider the following example: ::
+understand this, consider the following example::
 
    A${B} = "X"
    B = "2"
@@ -614,7 +614,7 @@ There is often confusion concerning the order in which overrides and
 various "append" operators take effect. Recall that an append or prepend
 operation using "_append" and "_prepend" does not result in an immediate
 assignment as would "+=", ".=", "=+", or "=.". Consider the following
-example: ::
+example::
 
    OVERRIDES = "foo"
    A = "Z"
@@ -631,7 +631,7 @@ Applying overrides, however, changes things. Since "foo" is listed in
 version, which is equal to "X". So effectively, ``A_foo`` replaces
 ``A``.
 
-This next example changes the order of the override and the append: ::
+This next example changes the order of the override and the append::
 
    OVERRIDES = "foo"
    A = "Z"
@@ -644,7 +644,7 @@ appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces
 are not appended.
 
 This next example has the order of the appends and overrides reversed
-back as in the first example: ::
+back as in the first example::
 
    OVERRIDES = "foo"
    A = "Y"
@@ -658,7 +658,7 @@ leaving the variable set to "ZX". Finally, applying the override for
 "foo" results in the conditional variable ``A`` becoming "ZX" (i.e.
 ``A`` is replaced with ``A_foo``).
 
-This final example mixes in some varying operators: ::
+This final example mixes in some varying operators::
 
    A = "1"
    A_append = "2"
@@ -720,7 +720,7 @@ file and then have your recipe inherit that class file.
 
 As an example, your recipes could use the following directive to inherit
 an ``autotools.bbclass`` file. The class file would contain common
-functionality for using Autotools that could be shared across recipes: ::
+functionality for using Autotools that could be shared across recipes::
 
    inherit autotools
 
@@ -734,7 +734,7 @@ In this case, BitBake would search for the directory
 
 If you want to use the directive to inherit multiple classes, separate
 them with spaces. The following example shows how to inherit both the
-``buildhistory`` and ``rm_work`` classes: ::
+``buildhistory`` and ``rm_work`` classes::
 
    inherit buildhistory rm_work
 
@@ -742,19 +742,19 @@ An advantage with the inherit directive as compared to both the
 :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`
 directives is that you can inherit class files conditionally. You can
 accomplish this by using a variable expression after the ``inherit``
-statement. Here is an example: ::
+statement. Here is an example::
 
    inherit ${VARNAME}
 
 If ``VARNAME`` is
 going to be set, it needs to be set before the ``inherit`` statement is
 parsed. One way to achieve a conditional inherit in this case is to use
-overrides: ::
+overrides::
 
    VARIABLE = ""
    VARIABLE_someoverride = "myclass"
 
-Another method is by using anonymous Python. Here is an example: ::
+Another method is by using anonymous Python. Here is an example::
 
    python () {
        if condition == value:
@@ -764,7 +764,7 @@ Another method is by using anonymous Python. Here is an example: ::
    }
 
 Alternatively, you could use an in-line Python expression in the
-following form: ::
+following form::
 
    inherit ${@'classname' if condition else ''}
    inherit ${@functionname(params)}
@@ -790,7 +790,7 @@ encapsulated functionality or configuration that does not suit a
 ``.bbclass`` file.
 
 As an example, suppose you needed a recipe to include some self-test
-definitions: ::
+definitions::
 
    include test_defs.inc
 
@@ -831,7 +831,7 @@ include file named ``foo.inc`` that contains the common definitions
 needed to build "foo". You need to be sure ``foo.inc`` is located in the
 same directory as your two recipe files as well. Once these conditions
 are set up, you can share the functionality using a ``require``
-directive from within each recipe: ::
+directive from within each recipe::
 
    require foo.inc
 
@@ -844,7 +844,7 @@ class. BitBake only supports this directive when used within a
 configuration file.
 
 As an example, suppose you needed to inherit a class file called
-``abc.bbclass`` from a configuration file as follows: ::
+``abc.bbclass`` from a configuration file as follows::
 
    INHERIT += "abc"
 
@@ -862,7 +862,7 @@ subdirectory in one of the directories specified in ``BBPATH``.
 If you want to use the directive to inherit multiple classes, you can
 provide them on the same line in the ``local.conf`` file. Use spaces to
 separate the classes. The following example shows how to inherit both
-the ``autotools`` and ``pkgconfig`` classes: ::
+the ``autotools`` and ``pkgconfig`` classes::
 
    INHERIT += "autotools pkgconfig"
 
@@ -895,7 +895,7 @@ Shell Functions
 
 Functions written in shell script and executed either directly as
 functions, tasks, or both. They can also be called by other shell
-functions. Here is an example shell function definition: ::
+functions. Here is an example shell function definition::
 
    some_function () {
        echo "Hello World"
@@ -912,7 +912,7 @@ can also be applied to shell functions. Most commonly, this application
 would be used in a ``.bbappend`` file to modify functions in the main
 recipe. It can also be used to modify functions inherited from classes.
 
-As an example, consider the following: ::
+As an example, consider the following::
 
    do_foo() {
        bbplain first
@@ -931,7 +931,7 @@ As an example, consider the following: ::
        bbplain fourth
    }
 
-Running ``do_foo`` prints the following: ::
+Running ``do_foo`` prints the following::
 
    recipename do_foo: first
    recipename do_foo: second
@@ -952,7 +952,7 @@ BitBake-Style Python Functions
 These functions are written in Python and executed by BitBake or other
 Python functions using ``bb.build.exec_func()``.
 
-An example BitBake function is: ::
+An example BitBake function is::
 
    python some_python_function () {
        d.setVar("TEXT", "Hello World")
@@ -975,7 +975,7 @@ import these modules. Also in these types of functions, the datastore
 Similar to shell functions, you can also apply overrides and
 override-style operators to BitBake-style Python functions.
 
-As an example, consider the following: ::
+As an example, consider the following::
 
    python do_foo_prepend() {
        bb.plain("first")
@@ -989,7 +989,7 @@ As an example, consider the following: ::
        bb.plain("third")
    }
 
-Running ``do_foo`` prints the following: ::
+Running ``do_foo`` prints the following::
 
    recipename do_foo: first
    recipename do_foo: second
@@ -1004,7 +1004,7 @@ Python Functions
 These functions are written in Python and are executed by other Python
 code. Examples of Python functions are utility functions that you intend
 to call from in-line Python or from within other Python functions. Here
-is an example: ::
+is an example::
 
    def get_depends(d):
        if d.getVar('SOMECONDITION'):
@@ -1056,7 +1056,7 @@ functions and regular Python functions defined with "def":
 -  Regular Python functions are called with the usual Python syntax.
    BitBake-style Python functions are usually tasks and are called
    directly by BitBake, but can also be called manually from Python code
-   by using the ``bb.build.exec_func()`` function. Here is an example: ::
+   by using the ``bb.build.exec_func()`` function. Here is an example::
 
       bb.build.exec_func("my_bitbake_style_function", d)
 
@@ -1094,7 +1094,7 @@ Sometimes it is useful to set variables or perform other operations
 programmatically during parsing. To do this, you can define special
 Python functions, called anonymous Python functions, that run at the end
 of parsing. For example, the following conditionally sets a variable
-based on the value of another variable: ::
+based on the value of another variable::
 
    python () {
        if d.getVar('SOMEVAR') == 'value':
@@ -1107,7 +1107,7 @@ the name "__anonymous", rather than no name.
 Anonymous Python functions always run at the end of parsing, regardless
 of where they are defined. If a recipe contains many anonymous
 functions, they run in the same order as they are defined within the
-recipe. As an example, consider the following snippet: ::
+recipe. As an example, consider the following snippet::
 
    python () {
        d.setVar('FOO', 'foo 2')
@@ -1122,7 +1122,7 @@ recipe. As an example, consider the following snippet: ::
    BAR = "bar 1"
 
 The previous example is conceptually
-equivalent to the following snippet: ::
+equivalent to the following snippet::
 
    FOO = "foo 1"
    BAR = "bar 1"
@@ -1136,7 +1136,7 @@ available to tasks, which always run after parsing.
 
 Overrides and override-style operators such as "``_append``" are applied
 before anonymous functions run. In the following example, ``FOO`` ends
-up with the value "foo from anonymous": ::
+up with the value "foo from anonymous"::
 
    FOO = "foo"
    FOO_append = " from outside"
@@ -1173,24 +1173,24 @@ version of the function.
 
 To make use of this technique, you need the following things in place:
 
--  The class needs to define the function as follows: ::
+-  The class needs to define the function as follows::
 
       classname_functionname
 
    For example, if you have a class file
    ``bar.bbclass`` and a function named ``do_foo``, the class must
-   define the function as follows: ::
+   define the function as follows::
 
       bar_do_foo
 
 -  The class needs to contain the ``EXPORT_FUNCTIONS`` statement as
-   follows: ::
+   follows::
 
       EXPORT_FUNCTIONS functionname
 
    For example, continuing with
    the same example, the statement in the ``bar.bbclass`` would be as
-   follows: ::
+   follows::
 
       EXPORT_FUNCTIONS do_foo
 
@@ -1199,7 +1199,7 @@ To make use of this technique, you need the following things in place:
    class version of the function, it should call ``bar_do_foo``.
    Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was
    used as above, the recipe's function could conditionally call the
-   class version of the function as follows: ::
+   class version of the function as follows::
 
       do_foo() {
           if [ somecondition ] ; then
@@ -1233,7 +1233,7 @@ Tasks are either :ref:`shell functions <bitbake-user-manual/bitbake-user-manual-
 that have been promoted to tasks by using the ``addtask`` command. The
 ``addtask`` command can also optionally describe dependencies between
 the task and other tasks. Here is an example that shows how to define a
-task and declare some dependencies: ::
+task and declare some dependencies::
 
    python do_printdate () {
        import time
@@ -1264,12 +1264,12 @@ Additionally, the ``do_printdate`` task becomes dependent upon the
    rerun for experimentation purposes, you can make BitBake always
    consider the task "out-of-date" by using the
    :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>`
-   variable flag, as follows: ::
+   variable flag, as follows::
 
       do_printdate[nostamp] = "1"
 
    You can also explicitly run the task and provide the
-   -f option as follows: ::
+   -f option as follows::
 
       $ bitbake recipe -c printdate -f
 
@@ -1278,7 +1278,7 @@ Additionally, the ``do_printdate`` task becomes dependent upon the
    name.
 
 You might wonder about the practical effects of using ``addtask``
-without specifying any dependencies as is done in the following example: ::
+without specifying any dependencies as is done in the following example::
 
    addtask printdate
 
@@ -1286,7 +1286,7 @@ In this example, assuming dependencies have not been
 added through some other means, the only way to run the task is by
 explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You
 can use the ``do_listtasks`` task to list all tasks defined in a recipe
-as shown in the following example: ::
+as shown in the following example::
 
    $ bitbake recipe -c listtasks
 
@@ -1312,7 +1312,7 @@ Deleting a Task
 
 As well as being able to add tasks, you can delete them. Simply use the
 ``deltask`` command to delete a task. For example, to delete the example
-task used in the previous sections, you would use: ::
+task used in the previous sections, you would use::
 
    deltask printdate
 
@@ -1328,7 +1328,7 @@ to run before ``do_a``.
 
 If you want dependencies such as these to remain intact, use the
 ``[noexec]`` varflag to disable the task instead of using the
-``deltask`` command to delete it: ::
+``deltask`` command to delete it::
 
    do_b[noexec] = "1"
 
@@ -1356,7 +1356,7 @@ environment, you must take these two steps:
    example, assume you want to prevent the build system from accessing
    your ``$HOME/.ccache`` directory. The following command "whitelists"
    the environment variable ``CCACHE_DIR`` causing BitBake to allow that
-   variable into the datastore: ::
+   variable into the datastore::
 
       export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
 
@@ -1366,7 +1366,7 @@ environment, you must take these two steps:
    available in the datastore. To export it to the task environment of
    every running task, use a command similar to the following in your
    local configuration file ``local.conf`` or your distribution
-   configuration file: ::
+   configuration file::
 
       export CCACHE_DIR
 
@@ -1385,7 +1385,7 @@ environment into a special variable named :term:`BB_ORIGENV`.
 The ``BB_ORIGENV`` variable returns a datastore object that can be
 queried using the standard datastore operators such as
 ``getVar(, False)``. The datastore object is useful, for example, to
-find the original ``DISPLAY`` variable. Here is an example: ::
+find the original ``DISPLAY`` variable. Here is an example::
 
    origenv = d.getVar("BB_ORIGENV", False)
    bar = origenv.getVar("BAR", False)
@@ -1398,7 +1398,7 @@ Variable Flags
 
 Variable flags (varflags) help control a task's functionality and
 dependencies. BitBake reads and writes varflags to the datastore using
-the following command forms: ::
+the following command forms::
 
    variable = d.getVarFlags("variable")
    self.d.setVarFlags("FOO", {"func": True})
@@ -1537,7 +1537,7 @@ intent is to make it easy to do things like email notification on build
 failures.
 
 Following is an example event handler that prints the name of the event
-and the content of the ``FILE`` variable: ::
+and the content of the ``FILE`` variable::
 
    addhandler myclass_eventhandler
    python myclass_eventhandler() {
@@ -1676,7 +1676,7 @@ incarnations are buildable. These features are enabled through the
    also specify conditional metadata (using the
    :term:`OVERRIDES` mechanism) for a single
    version, or an optionally named range of versions. Here is an
-   example: ::
+   example::
 
       BBVERSIONS = "1.0 2.0 git"
       SRC_URI_git = "git://someurl/somepath.git"
@@ -1719,7 +1719,7 @@ Dependencies Internal to the ``.bb`` File
 BitBake uses the ``addtask`` directive to manage dependencies that are
 internal to a given recipe file. You can use the ``addtask`` directive
 to indicate when a task is dependent on other tasks or when other tasks
-depend on that recipe. Here is an example: ::
+depend on that recipe. Here is an example::
 
    addtask printdate after do_fetch before do_build
 
@@ -1743,7 +1743,7 @@ task depends on the completion of the ``do_printdate`` task.
 
    -  The directive ``addtask mytask after do_configure`` by itself
       never causes ``do_mytask`` to run. ``do_mytask`` can still be run
-      manually as follows: ::
+      manually as follows::
 
          $ bitbake recipe -c mytask
 
@@ -1757,7 +1757,7 @@ Build Dependencies
 BitBake uses the :term:`DEPENDS` variable to manage
 build time dependencies. The ``[deptask]`` varflag for tasks signifies
 the task of each item listed in ``DEPENDS`` that must complete before
-that task can be executed. Here is an example: ::
+that task can be executed. Here is an example::
 
    do_configure[deptask] = "do_populate_sysroot"
 
@@ -1799,7 +1799,7 @@ dependencies are discovered and added.
 
 The ``[recrdeptask]`` flag is most commonly used in high-level recipes
 that need to wait for some task to finish "globally". For example,
-``image.bbclass`` has the following: ::
+``image.bbclass`` has the following::
 
    do_rootfs[recrdeptask] += "do_packagedata"
 
@@ -1808,7 +1808,7 @@ the current recipe and all recipes reachable (by way of dependencies)
 from the image recipe must run before the ``do_rootfs`` task can run.
 
 BitBake allows a task to recursively depend on itself by
-referencing itself in the task list: ::
+referencing itself in the task list::
 
    do_a[recrdeptask] = "do_a do_b"
 
@@ -1825,7 +1825,7 @@ Inter-Task Dependencies
 BitBake uses the ``[depends]`` flag in a more generic form to manage
 inter-task dependencies. This more generic form allows for
 inter-dependency checks for specific tasks rather than checks for the
-data in ``DEPENDS``. Here is an example: ::
+data in ``DEPENDS``. Here is an example::
 
    do_patch[depends] = "quilt-native:do_populate_sysroot"
 
@@ -1920,7 +1920,7 @@ To help understand how BitBake does this, the section assumes an
 OpenEmbedded metadata-based example.
 
 These checksums are stored in :term:`STAMP`. You can
-examine the checksums using the following BitBake command: ::
+examine the checksums using the following BitBake command::
 
    $ bitbake-dumpsigs
 

bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst

@@ -130,7 +130,7 @@ overview of their function and contents.
       you to control the build based on these parameters.
 
       Disk space monitoring is disabled by default. When setting this
-      variable, use the following form: ::
+      variable, use the following form::
 
          BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]"
 
@@ -166,7 +166,7 @@ overview of their function and contents.
                not specify G, M, or K, Kbytes is assumed by
                default.  Do not use GB, MB, or KB.
 
-      Here are some examples: ::
+      Here are some examples::
 
          BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
          BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
@@ -207,7 +207,7 @@ overview of their function and contents.
       BB_DISKMON_WARNINTERVAL = "50M,5K"
 
       When specifying the variable in your configuration file, use the
-      following form: ::
+      following form::
 
          BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>"
 
@@ -223,7 +223,7 @@ overview of their function and contents.
                G, M, or K for Gbytes, Mbytes, or Kbytes,
                respectively. You cannot use GB, MB, or KB.
 
-      Here is an example: ::
+      Here is an example::
 
          BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
          BB_DISKMON_WARNINTERVAL = "50M,5K"
@@ -329,7 +329,7 @@ overview of their function and contents.
       Specifies the name of the log files saved into
       ``${``\ :term:`T`\ ``}``. By default, the ``BB_LOGFMT``
       variable is undefined and the log file names get created using the
-      following form: ::
+      following form::
 
          log.{task}.{pid}
 
@@ -383,7 +383,7 @@ overview of their function and contents.
       Specifies the name of the executable script files (i.e. run files)
       saved into ``${``\ :term:`T`\ ``}``. By default, the
       ``BB_RUNFMT`` variable is undefined and the run file names get
-      created using the following form: ::
+      created using the following form::
 
          run.{task}.{pid}
 
@@ -511,7 +511,7 @@ overview of their function and contents.
          This variable works similarly to the :term:`BB_TASK_NICE_LEVEL`
          variable except with a task's I/O priorities.
 
-      Set the variable as follows: ::
+      Set the variable as follows::
 
          BB_TASK_IONICE_LEVEL = "class.prio"
 
@@ -529,7 +529,7 @@ overview of their function and contents.
          In order for your I/O priority settings to take effect, you need the
          Completely Fair Queuing (CFQ) Scheduler selected for the backing block
          device. To select the scheduler, use the following command form where
-         device is the device (e.g. sda, sdb, and so forth): ::
+         device is the device (e.g. sda, sdb, and so forth)::
 
             $ sudo sh -c "echo cfq > /sys/block/device/queu/scheduler"
 
@@ -570,7 +570,7 @@ overview of their function and contents.
       To build a different variant of the recipe with a minimal amount of
       code, it usually is as simple as adding the variable to your recipe.
       Here are two examples. The "native" variants are from the
-      OpenEmbedded-Core metadata: ::
+      OpenEmbedded-Core metadata::
 
          BBCLASSEXTEND =+ "native nativesdk"
          BBCLASSEXTEND =+ "multilib:multilib_name"
@@ -658,12 +658,12 @@ overview of their function and contents.
       ``.bb`` files in case a layer is not present.  Use this avoid hard
       dependency on those other layers.
 
-      Use the following form for ``BBFILES_DYNAMIC``: ::
+      Use the following form for ``BBFILES_DYNAMIC``::
 
          collection_name:filename_pattern
 
       The following example identifies two collection names and two filename
-      patterns: ::
+      patterns::
 
          BBFILES_DYNAMIC += "\
              clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
@@ -671,14 +671,14 @@ overview of their function and contents.
          "
 
       When the collection name is prefixed with "!" it will add the file pattern in case
-      the layer is absent: ::
+      the layer is absent::
 
          BBFILES_DYNAMIC += "\
              !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \
          "
 
       This next example shows an error message that occurs because invalid
-      entries are found, which cause parsing to abort: ::
+      entries are found, which cause parsing to abort::
 
          ERROR: BBFILES_DYNAMIC entries must be of the form {!}<collection name>:<filename pattern>, not:
          /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
@@ -701,7 +701,7 @@ overview of their function and contents.
    :term:`BBLAYERS`
       Lists the layers to enable during the build. This variable is defined
       in the ``bblayers.conf`` configuration file in the build directory.
-      Here is an example: ::
+      Here is an example::
 
          BBLAYERS = " \
              /home/scottrif/poky/meta \
@@ -735,13 +735,13 @@ overview of their function and contents.
 
       The following example uses a complete regular expression to tell
       BitBake to ignore all recipe and recipe append files in the
-      ``meta-ti/recipes-misc/`` directory: ::
+      ``meta-ti/recipes-misc/`` directory::
 
          BBMASK = "meta-ti/recipes-misc/"
 
       If you want to mask out multiple directories or recipes, you can
       specify multiple regular expression fragments. This next example
-      masks out multiple directories and individual recipes: ::
+      masks out multiple directories and individual recipes::
 
          BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
          BBMASK += "/meta-oe/recipes-support/"
@@ -762,7 +762,7 @@ overview of their function and contents.
       ``conf/local.conf`` configuration file.
 
       As an example, the following line specifies three multiconfigs, each
-      having a separate configuration file: ::
+      having a separate configuration file::
 
          BBMULTIFONFIG = "configA configB configC"
 
@@ -783,7 +783,7 @@ overview of their function and contents.
       If you run BitBake from a directory outside of the build directory,
       you must be sure to set ``BBPATH`` to point to the build directory.
       Set the variable as you would any environment variable and then run
-      BitBake: ::
+      BitBake::
 
          $ BBPATH="build_directory"
          $ export BBPATH
@@ -852,7 +852,7 @@ overview of their function and contents.
 
       Consider this simple example for two recipes named "a" and "b" that
       produce similarly named packages. In this example, the ``DEPENDS``
-      statement appears in the "a" recipe: ::
+      statement appears in the "a" recipe::
 
          DEPENDS = "b"
 
@@ -1074,7 +1074,7 @@ overview of their function and contents.
       recipes provide the same item. You should always suffix the variable
       with the name of the provided item, and you should set it to the
       :term:`PN` of the recipe to which you want to give
-      precedence. Some examples: ::
+      precedence. Some examples::
 
          PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
          PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
@@ -1086,18 +1086,18 @@ overview of their function and contents.
       ``PREFERRED_PROVIDERS`` is identical to
       :term:`PREFERRED_PROVIDER`. However, the ``PREFERRED_PROVIDERS`` variable
       lets you define preferences for multiple situations using the following
-      form: ::
+      form::
 
          PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..."
 
-      This form is a convenient replacement for the following: ::
+      This form is a convenient replacement for the following::
 
          PREFERRED_PROVIDER_xxx = "yyy"
          PREFERRED_PROVIDER_aaa = "bbb"
 
    :term:`PREFERRED_VERSION`
-      If there are multiple versions of recipes available, this variable
-      determines which recipe should be given preference. You must always
+      If there are multiple versions of a recipe available, this variable
+      determines which version should be given preference. You must always
       suffix the variable with the :term:`PN` you want to
       select, and you should set :term:`PV` accordingly for
       precedence.
@@ -1106,7 +1106,7 @@ overview of their function and contents.
       through the "``%``" character. You can use the character to match any
       number of characters, which can be useful when specifying versions
       that contain long revision numbers that potentially change. Here are
-      two examples: ::
+      two examples::
 
          PREFERRED_VERSION_python = "2.7.3"
          PREFERRED_VERSION_linux-yocto = "4.12%"
@@ -1117,6 +1117,10 @@ overview of their function and contents.
          end of the string. You cannot use the wildcard character in any other
          location of the string.
 
+      If a recipe with the specified version is not available, a warning
+      message will be shown. See :term:`REQUIRED_VERSION` if you want this
+      to be an error instead.
+
    :term:`PREMIRRORS`
       Specifies additional paths from which BitBake gets source code. When
       the build system searches for source code, it first tries the local
@@ -1126,7 +1130,7 @@ overview of their function and contents.
 
       Typically, you would add a specific server for the build system to
       attempt before any others by adding something like the following to
-      your configuration: ::
+      your configuration::
 
          PREMIRRORS_prepend = "\
          git://.*/.* http://www.yoctoproject.org/sources/ \n \
@@ -1148,7 +1152,7 @@ overview of their function and contents.
       ``DEPENDS``.
 
       Consider the following example ``PROVIDES`` statement from a recipe
-      file ``libav_0.8.11.bb``: ::
+      file ``libav_0.8.11.bb``::
 
          PROVIDES += "libpostproc"
 
@@ -1171,7 +1175,7 @@ overview of their function and contents.
    :term:`PRSERV_HOST`
       The network based :term:`PR` service host and port.
 
-      Following is an example of how the ``PRSERV_HOST`` variable is set: ::
+      Following is an example of how the ``PRSERV_HOST`` variable is set::
 
          PRSERV_HOST = "localhost:0"
 
@@ -1192,7 +1196,7 @@ overview of their function and contents.
       you should always use the variable in a form with an attached package
       name. For example, suppose you are building a development package
       that depends on the ``perl`` package. In this case, you would use the
-      following ``RDEPENDS`` statement: ::
+      following ``RDEPENDS`` statement::
 
          RDEPENDS_${PN}-dev += "perl"
 
@@ -1203,11 +1207,11 @@ overview of their function and contents.
       BitBake supports specifying versioned dependencies. Although the
       syntax varies depending on the packaging format, BitBake hides these
       differences from you. Here is the general syntax to specify versions
-      with the ``RDEPENDS`` variable: ::
+      with the ``RDEPENDS`` variable::
 
          RDEPENDS_${PN} = "package (operator version)"
 
-      For ``operator``, you can specify the following: ::
+      For ``operator``, you can specify the following::
 
          =
          <
@@ -1216,7 +1220,7 @@ overview of their function and contents.
          >=
 
       For example, the following sets up a dependency on version 1.2 or
-      greater of the package ``foo``: ::
+      greater of the package ``foo``::
 
          RDEPENDS_${PN} = "foo (>= 1.2)"
 
@@ -1227,6 +1231,16 @@ overview of their function and contents.
       The directory in which a local copy of a ``google-repo`` directory is
       stored when it is synced.
 
+   :term:`REQUIRED_VERSION`
+      If there are multiple versions of a recipe available, this variable
+      determines which version should be given preference. ``REQUIRED_VERSION``
+      works in exactly the same manner as :term:`PREFERRED_VERSION`, except
+      that if the specified version is not available then an error message
+      is shown and the build fails immediately.
+
+      If both ``REQUIRED_VERSION`` and ``PREFERRED_VERSION`` are set for
+      the same recipe, the ``REQUIRED_VERSION`` value applies.
+
    :term:`RPROVIDES`
       A list of package name aliases that a package also provides. These
       aliases are useful for satisfying runtime dependencies of other
@@ -1235,7 +1249,7 @@ overview of their function and contents.
 
       As with all package-controlling variables, you must always use the
       variable in conjunction with a package name override. Here is an
-      example: ::
+      example::
 
          RPROVIDES_${PN} = "widget-abi-2"
 
@@ -1249,11 +1263,11 @@ overview of their function and contents.
       BitBake supports specifying versioned recommends. Although the syntax
       varies depending on the packaging format, BitBake hides these
       differences from you. Here is the general syntax to specify versions
-      with the ``RRECOMMENDS`` variable: ::
+      with the ``RRECOMMENDS`` variable::
 
          RRECOMMENDS_${PN} = "package (operator version)"
 
-      For ``operator``, you can specify the following: ::
+      For ``operator``, you can specify the following::
 
          =
          <
@@ -1262,7 +1276,7 @@ overview of their function and contents.
          >=
 
       For example, the following sets up a recommend on version
-      1.2 or greater of the package ``foo``: ::
+      1.2 or greater of the package ``foo``::
 
          RRECOMMENDS_${PN} = "foo (>= 1.2)"
 

bitbake/lib/bb/__init__.py

@@ -9,7 +9,7 @@
 # SPDX-License-Identifier: GPL-2.0-only
 #
 
-__version__ = "1.49.2"
+__version__ = "1.51.0"
 
 import sys
 if sys.version_info < (3, 5, 0):

bitbake/lib/bb/asyncrpc/__init__.py

@@ -0,0 +1,31 @@
+#
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+import itertools
+import json
+
+# The Python async server defaults to a 64K receive buffer, so we hardcode our
+# maximum chunk size. It would be better if the client and server reported to
+# each other what the maximum chunk sizes were, but that will slow down the
+# connection setup with a round trip delay so I'd rather not do that unless it
+# is necessary
+DEFAULT_MAX_CHUNK = 32 * 1024
+
+
+def chunkify(msg, max_chunk):
+    if len(msg) < max_chunk - 1:
+        yield ''.join((msg, "\n"))
+    else:
+        yield ''.join((json.dumps({
+                'chunk-stream': None
+            }), "\n"))
+
+        args = [iter(msg)] * (max_chunk - 1)
+        for m in map(''.join, itertools.zip_longest(*args, fillvalue='')):
+            yield ''.join(itertools.chain(m, "\n"))
+        yield "\n"
+
+
+from .client import AsyncClient, Client
+from .serv import AsyncServer, AsyncServerConnection

bitbake/lib/bb/asyncrpc/client.py

@@ -0,0 +1,145 @@
+#
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+import abc
+import asyncio
+import json
+import os
+import socket
+from . import chunkify, DEFAULT_MAX_CHUNK
+
+
+class AsyncClient(object):
+    def __init__(self, proto_name, proto_version, logger):
+        self.reader = None
+        self.writer = None
+        self.max_chunk = DEFAULT_MAX_CHUNK
+        self.proto_name = proto_name
+        self.proto_version = proto_version
+        self.logger = logger
+
+    async def connect_tcp(self, address, port):
+        async def connect_sock():
+            return await asyncio.open_connection(address, port)
+
+        self._connect_sock = connect_sock
+
+    async def connect_unix(self, path):
+        async def connect_sock():
+            return await asyncio.open_unix_connection(path)
+
+        self._connect_sock = connect_sock
+
+    async def setup_connection(self):
+        s = '%s %s\n\n' % (self.proto_name, self.proto_version)
+        self.writer.write(s.encode("utf-8"))
+        await self.writer.drain()
+
+    async def connect(self):
+        if self.reader is None or self.writer is None:
+            (self.reader, self.writer) = await self._connect_sock()
+            await self.setup_connection()
+
+    async def close(self):
+        self.reader = None
+
+        if self.writer is not None:
+            self.writer.close()
+            self.writer = None
+
+    async def _send_wrapper(self, proc):
+        count = 0
+        while True:
+            try:
+                await self.connect()
+                return await proc()
+            except (
+                OSError,
+                ConnectionError,
+                json.JSONDecodeError,
+                UnicodeDecodeError,
+            ) as e:
+                self.logger.warning("Error talking to server: %s" % e)
+                if count >= 3:
+                    if not isinstance(e, ConnectionError):
+                        raise ConnectionError(str(e))
+                    raise e
+                await self.close()
+                count += 1
+
+    async def send_message(self, msg):
+        async def get_line():
+            line = await self.reader.readline()
+            if not line:
+                raise ConnectionError("Connection closed")
+
+            line = line.decode("utf-8")
+
+            if not line.endswith("\n"):
+                raise ConnectionError("Bad message %r" % msg)
+
+            return line
+
+        async def proc():
+            for c in chunkify(json.dumps(msg), self.max_chunk):
+                self.writer.write(c.encode("utf-8"))
+            await self.writer.drain()
+
+            l = await get_line()
+
+            m = json.loads(l)
+            if m and "chunk-stream" in m:
+                lines = []
+                while True:
+                    l = (await get_line()).rstrip("\n")
+                    if not l:
+                        break
+                    lines.append(l)
+
+                m = json.loads("".join(lines))
+
+            return m
+
+        return await self._send_wrapper(proc)
+
+
+class Client(object):
+    def __init__(self):
+        self.client = self._get_async_client()
+        self.loop = asyncio.new_event_loop()
+
+        self._add_methods('connect_tcp', 'close')
+
+    @abc.abstractmethod
+    def _get_async_client(self):
+        pass
+
+    def _get_downcall_wrapper(self, downcall):
+        def wrapper(*args, **kwargs):
+            return self.loop.run_until_complete(downcall(*args, **kwargs))
+
+        return wrapper
+
+    def _add_methods(self, *methods):
+        for m in methods:
+            downcall = getattr(self.client, m)
+            setattr(self, m, self._get_downcall_wrapper(downcall))
+
+    def connect_unix(self, path):
+        # AF_UNIX has path length issues so chdir here to workaround
+        cwd = os.getcwd()
+        try:
+            os.chdir(os.path.dirname(path))
+            self.loop.run_until_complete(self.client.connect_unix(os.path.basename(path)))
+            self.loop.run_until_complete(self.client.connect())
+        finally:
+            os.chdir(cwd)
+
+    @property
+    def max_chunk(self):
+        return self.client.max_chunk
+
+    @max_chunk.setter
+    def max_chunk(self, value):
+        self.client.max_chunk = value

bitbake/lib/bb/asyncrpc/serv.py

@@ -0,0 +1,218 @@
+#
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+import abc
+import asyncio
+import json
+import os
+import signal
+import socket
+import sys
+from . import chunkify, DEFAULT_MAX_CHUNK
+
+
+class ClientError(Exception):
+    pass
+
+
+class ServerError(Exception):
+    pass
+
+
+class AsyncServerConnection(object):
+    def __init__(self, reader, writer, proto_name, logger):
+        self.reader = reader
+        self.writer = writer
+        self.proto_name = proto_name
+        self.max_chunk = DEFAULT_MAX_CHUNK
+        self.handlers = {
+            'chunk-stream': self.handle_chunk,
+        }
+        self.logger = logger
+
+    async def process_requests(self):
+        try:
+            self.addr = self.writer.get_extra_info('peername')
+            self.logger.debug('Client %r connected' % (self.addr,))
+
+            # Read protocol and version
+            client_protocol = await self.reader.readline()
+            if client_protocol is None:
+                return
+
+            (client_proto_name, client_proto_version) = client_protocol.decode('utf-8').rstrip().split()
+            if client_proto_name != self.proto_name:
+                self.logger.debug('Rejecting invalid protocol %s' % (self.proto_name))
+                return
+
+            self.proto_version = tuple(int(v) for v in client_proto_version.split('.'))
+            if not self.validate_proto_version():
+                self.logger.debug('Rejecting invalid protocol version %s' % (client_proto_version))
+                return
+
+            # Read headers. Currently, no headers are implemented, so look for
+            # an empty line to signal the end of the headers
+            while True:
+                line = await self.reader.readline()
+                if line is None:
+                    return
+
+                line = line.decode('utf-8').rstrip()
+                if not line:
+                    break
+
+            # Handle messages
+            while True:
+                d = await self.read_message()
+                if d is None:
+                    break
+                await self.dispatch_message(d)
+                await self.writer.drain()
+        except ClientError as e:
+            self.logger.error(str(e))
+        finally:
+            self.writer.close()
+
+    async def dispatch_message(self, msg):
+        for k in self.handlers.keys():
+            if k in msg:
+                self.logger.debug('Handling %s' % k)
+                await self.handlers[k](msg[k])
+                return
+
+        raise ClientError("Unrecognized command %r" % msg)
+
+    def write_message(self, msg):
+        for c in chunkify(json.dumps(msg), self.max_chunk):
+            self.writer.write(c.encode('utf-8'))
+
+    async def read_message(self):
+        l = await self.reader.readline()
+        if not l:
+            return None
+
+        try:
+            message = l.decode('utf-8')
+
+            if not message.endswith('\n'):
+                return None
+
+            return json.loads(message)
+        except (json.JSONDecodeError, UnicodeDecodeError) as e:
+            self.logger.error('Bad message from client: %r' % message)
+            raise e
+
+    async def handle_chunk(self, request):
+        lines = []
+        try:
+            while True:
+                l = await self.reader.readline()
+                l = l.rstrip(b"\n").decode("utf-8")
+                if not l:
+                    break
+                lines.append(l)
+
+            msg = json.loads(''.join(lines))
+        except (json.JSONDecodeError, UnicodeDecodeError) as e:
+            self.logger.error('Bad message from client: %r' % lines)
+            raise e
+
+        if 'chunk-stream' in msg:
+            raise ClientError("Nested chunks are not allowed")
+
+        await self.dispatch_message(msg)
+
+
+class AsyncServer(object):
+    def __init__(self, logger, loop=None):
+        if loop is None:
+            self.loop = asyncio.new_event_loop()
+            self.close_loop = True
+        else:
+            self.loop = loop
+            self.close_loop = False
+
+        self._cleanup_socket = None
+        self.logger = logger
+
+    def start_tcp_server(self, host, port):
+        self.server = self.loop.run_until_complete(
+            asyncio.start_server(self.handle_client, host, port, loop=self.loop)
+        )
+
+        for s in self.server.sockets:
+            self.logger.info('Listening on %r' % (s.getsockname(),))
+            # Newer python does this automatically. Do it manually here for
+            # maximum compatibility
+            s.setsockopt(socket.SOL_TCP, socket.TCP_NODELAY, 1)
+            s.setsockopt(socket.SOL_TCP, socket.TCP_QUICKACK, 1)
+
+        name = self.server.sockets[0].getsockname()
+        if self.server.sockets[0].family == socket.AF_INET6:
+            self.address = "[%s]:%d" % (name[0], name[1])
+        else:
+            self.address = "%s:%d" % (name[0], name[1])
+
+    def start_unix_server(self, path):
+        def cleanup():
+            os.unlink(path)
+
+        cwd = os.getcwd()
+        try:
+            # Work around path length limits in AF_UNIX
+            os.chdir(os.path.dirname(path))
+            self.server = self.loop.run_until_complete(
+                asyncio.start_unix_server(self.handle_client, os.path.basename(path), loop=self.loop)
+            )
+        finally:
+            os.chdir(cwd)
+
+        self.logger.info('Listening on %r' % path)
+
+        self._cleanup_socket = cleanup
+        self.address = "unix://%s" % os.path.abspath(path)
+
+    @abc.abstractmethod
+    def accept_client(self, reader, writer):
+        pass
+
+    async def handle_client(self, reader, writer):
+        # writer.transport.set_write_buffer_limits(0)
+        try:
+            client = self.accept_client(reader, writer)
+            await client.process_requests()
+        except Exception as e:
+            import traceback
+            self.logger.error('Error from client: %s' % str(e), exc_info=True)
+            traceback.print_exc()
+            writer.close()
+        self.logger.info('Client disconnected')
+
+    def run_loop_forever(self):
+        try:
+            self.loop.run_forever()
+        except KeyboardInterrupt:
+            pass
+
+    def signal_handler(self):
+        self.loop.stop()
+
+    def serve_forever(self):
+        asyncio.set_event_loop(self.loop)
+        try:
+            self.loop.add_signal_handler(signal.SIGTERM, self.signal_handler)
+
+            self.run_loop_forever()
+            self.server.close()
+
+            self.loop.run_until_complete(self.server.wait_closed())
+            self.logger.info('Server shutting down')
+        finally:
+            if self.close_loop:
+                if sys.version_info >= (3, 6):
+                    self.loop.run_until_complete(self.loop.shutdown_asyncgens())
+                self.loop.close()
+
+            if self._cleanup_socket is not None:
+                self._cleanup_socket()

bitbake/lib/bb/command.py

@@ -20,6 +20,7 @@ Commands are queued in a CommandQueue
 
 from collections import OrderedDict, defaultdict
 
+import io
 import bb.event
 import bb.cooker
 import bb.remotedata
@@ -500,6 +501,17 @@ class CommandsSync:
         d = command.remotedatastores[dsindex].varhistory
         return getattr(d, method)(*args, **kwargs)
 
+    def dataStoreConnectorVarHistCmdEmit(self, command, params):
+        dsindex = params[0]
+        var = params[1]
+        oval = params[2]
+        val = params[3]
+        d = command.remotedatastores[params[4]]
+
+        o = io.StringIO()
+        command.remotedatastores[dsindex].varhistory.emit(var, oval, val, o, d)
+        return o.getvalue()
+
     def dataStoreConnectorIncHistCmd(self, command, params):
         dsindex = params[0]
         method = params[1]

bitbake/lib/bb/fetch2/git.py

@@ -168,7 +168,11 @@ class Git(FetchMethod):
         if len(branches) != len(ud.names):
             raise bb.fetch2.ParameterError("The number of name and branch parameters is not balanced", ud.url)
 
-        ud.cloneflags = "-s -n"
+        ud.noshared = d.getVar("BB_GIT_NOSHARED") == "1"
+
+        ud.cloneflags = "-n"
+        if not ud.noshared:
+            ud.cloneflags += " -s"
         if ud.bareclone:
             ud.cloneflags += " --mirror"
 
@@ -394,7 +398,7 @@ class Git(FetchMethod):
             tmpdir = tempfile.mkdtemp(dir=d.getVar('DL_DIR'))
             try:
                 # Do the checkout. This implicitly involves a Git LFS fetch.
-                self.unpack(ud, tmpdir, d)
+                Git.unpack(self, ud, tmpdir, d)
 
                 # Scoop up a copy of any stuff that Git LFS downloaded. Merge them into
                 # the bare clonedir.

bitbake/lib/bb/fetch2/s3.py

@@ -18,10 +18,47 @@ The aws tool must be correctly installed and configured prior to use.
 import os
 import bb
 import urllib.request, urllib.parse, urllib.error
+import re
 from bb.fetch2 import FetchMethod
 from bb.fetch2 import FetchError
 from bb.fetch2 import runfetchcmd
 
+def convertToBytes(value, unit):
+    value = float(value)
+    if (unit == "KiB"):
+        value = value*1024.0;
+    elif (unit == "MiB"):
+        value = value*1024.0*1024.0;
+    elif (unit == "GiB"):
+        value = value*1024.0*1024.0*1024.0;
+    return value
+
+class S3ProgressHandler(bb.progress.LineFilterProgressHandler):
+    """
+    Extract progress information from s3 cp output, e.g.:
+    Completed 5.1 KiB/8.8 GiB (12.0 MiB/s) with 1 file(s) remaining
+    """
+    def __init__(self, d):
+        super(S3ProgressHandler, self).__init__(d)
+        # Send an initial progress event so the bar gets shown
+        self._fire_progress(0)
+
+    def writeline(self, line):
+        percs = re.findall(r'^Completed (\d+.{0,1}\d*) (\w+)\/(\d+.{0,1}\d*) (\w+) (\(.+\)) with\s+', line)
+        if percs:
+            completed = (percs[-1][0])
+            completedUnit = (percs[-1][1])
+            total = (percs[-1][2])
+            totalUnit = (percs[-1][3])
+            completed = convertToBytes(completed, completedUnit)
+            total = convertToBytes(total, totalUnit)
+            progress = (completed/total)*100.0
+            rate = percs[-1][4]
+            self.update(progress, rate)
+            return False
+        return True
+
+
 class S3(FetchMethod):
     """Class to fetch urls via 'aws s3'"""
 
@@ -52,7 +89,9 @@ class S3(FetchMethod):
 
         cmd = '%s cp s3://%s%s %s' % (ud.basecmd, ud.host, ud.path, ud.localpath)
         bb.fetch2.check_network_access(d, cmd, ud.url)
-        runfetchcmd(cmd, d)
+
+        progresshandler = S3ProgressHandler(d)
+        runfetchcmd(cmd, d, False, log=progresshandler)
 
         # Additional sanity checks copied from the wget class (although there
         # are no known issues which mean these are required, treat the aws cli

bitbake/lib/bb/fetch2/svn.py

@@ -86,7 +86,7 @@ class Svn(FetchMethod):
         if command == "info":
             svncmd = "%s info %s %s://%s/%s/" % (ud.basecmd, " ".join(options), proto, svnroot, ud.module)
         elif command == "log1":
-            svncmd = "%s log --limit 1 %s %s://%s/%s/" % (ud.basecmd, " ".join(options), proto, svnroot, ud.module)
+            svncmd = "%s log --limit 1 --quiet %s %s://%s/%s/" % (ud.basecmd, " ".join(options), proto, svnroot, ud.module)
         else:
             suffix = ""
 

bitbake/lib/bb/fetch2/wget.py

@@ -472,7 +472,7 @@ class Wget(FetchMethod):
         version_dir = ['', '', '']
         version = ['', '', '']
 
-        dirver_regex = re.compile(r"(?P<pfx>\D*)(?P<ver>(\d+[\.\-_])+(\d+))")
+        dirver_regex = re.compile(r"(?P<pfx>\D*)(?P<ver>(\d+[\.\-_])*(\d+))")
         s = dirver_regex.search(dirver)
         if s:
             version_dir[1] = s.group('ver')

bitbake/lib/bb/progress.py

@@ -94,12 +94,15 @@ class LineFilterProgressHandler(ProgressHandler):
         while True:
             breakpos = self._linebuffer.find('\n') + 1
             if breakpos == 0:
-                break
+                # for the case when the line with progress ends with only '\r'
+                breakpos = self._linebuffer.find('\r') + 1
+                if breakpos == 0:
+                    break
             line = self._linebuffer[:breakpos]
             self._linebuffer = self._linebuffer[breakpos:]
             # Drop any line feeds and anything that precedes them
             lbreakpos = line.rfind('\r') + 1
-            if lbreakpos:
+            if lbreakpos and lbreakpos != breakpos:
                 line = line[lbreakpos:]
             if self.writeline(filter_color(line)):
                 super().write(line)

bitbake/lib/bb/runqueue.py

@@ -2030,8 +2030,6 @@ class RunQueueExecute:
                             logger.debug("%s didn't become valid, skipping setscene" % nexttask)
                             self.sq_task_failoutright(nexttask)
                             return True
-                        else:
-                            self.sqdata.outrightfail.remove(nexttask)
                     if nexttask in self.sqdata.outrightfail:
                         logger.debug2('No package found, so skipping setscene task %s', nexttask)
                         self.sq_task_failoutright(nexttask)
@@ -2296,10 +2294,16 @@ class RunQueueExecute:
             self.updated_taskhash_queue.remove((tid, unihash))
 
             if unihash != self.rqdata.runtaskentries[tid].unihash:
-                hashequiv_logger.verbose("Task %s unihash changed to %s" % (tid, unihash))
-                self.rqdata.runtaskentries[tid].unihash = unihash
-                bb.parse.siggen.set_unihash(tid, unihash)
-                toprocess.add(tid)
+                # Make sure we rehash any other tasks with the same task hash that we're deferred against.
+                torehash = [tid]
+                for deftid in self.sq_deferred:
+                    if self.sq_deferred[deftid] == tid:
+                        torehash.append(deftid)
+                for hashtid in torehash:
+                    hashequiv_logger.verbose("Task %s unihash changed to %s" % (hashtid, unihash))
+                    self.rqdata.runtaskentries[hashtid].unihash = unihash
+                    bb.parse.siggen.set_unihash(hashtid, unihash)
+                    toprocess.add(hashtid)
 
         # Work out all tasks which depend upon these
         total = set()
@@ -2827,6 +2831,8 @@ def update_scenequeue_data(tids, sqdata, rqdata, rq, cooker, stampcache, sqrq, s
             sqdata.stamppresent.remove(tid)
         if tid in sqdata.valid:
             sqdata.valid.remove(tid)
+        if tid in sqdata.outrightfail:
+            sqdata.outrightfail.remove(tid)
 
         noexec, stamppresent = check_setscene_stamps(tid, rqdata, rq, stampcache, noexecstamp=True)
 
@@ -2845,6 +2851,7 @@ def update_scenequeue_data(tids, sqdata, rqdata, rq, cooker, stampcache, sqrq, s
     sqdata.valid |= rq.validate_hashes(tocheck, cooker.data, len(sqdata.stamppresent), False, summary=summary)
 
     sqdata.hashes = {}
+    sqrq.sq_deferred = {}
     for mc in sorted(sqdata.multiconfigs):
         for tid in sorted(sqdata.sq_revdeps):
             if mc_from_tid(tid) != mc:
@@ -2857,10 +2864,13 @@ def update_scenequeue_data(tids, sqdata, rqdata, rq, cooker, stampcache, sqrq, s
                 continue
             if tid in sqrq.scenequeue_notcovered:
                 continue
-            sqdata.outrightfail.add(tid)
+            if tid in sqrq.scenequeue_covered:
+                continue
 
             h = pending_hash_index(tid, rqdata)
             if h not in sqdata.hashes:
+                if tid in tids:
+                    sqdata.outrightfail.add(tid)
                 sqdata.hashes[h] = tid
             else:
                 sqrq.sq_deferred[tid] = sqdata.hashes[h]

bitbake/lib/bb/server/process.py

@@ -367,7 +367,12 @@ class ProcessServer():
                 self.next_heartbeat = now + self.heartbeat_seconds
             if hasattr(self.cooker, "data"):
                 heartbeat = bb.event.HeartbeatEvent(now)
-                bb.event.fire(heartbeat, self.cooker.data)
+                try:
+                    bb.event.fire(heartbeat, self.cooker.data)
+                except Exception as exc:
+                    if not isinstance(exc, bb.BBHandledException):
+                        logger.exception('Running heartbeat function')
+                    self.quit = True
         if nextsleep and now + nextsleep > self.next_heartbeat:
             # Shorten timeout so that we we wake up in time for
             # the heartbeat.
@@ -509,7 +514,7 @@ class BitBakeServer(object):
         os.set_inheritable(self.bitbake_lock.fileno(), True)
         os.set_inheritable(self.readypipein, True)
         serverscript = os.path.realpath(os.path.dirname(__file__) + "/../../../bin/bitbake-server")
-        os.execl(sys.executable, "bitbake-server", serverscript, "decafbad", str(self.bitbake_lock.fileno()), str(self.readypipein), self.logfile, self.bitbake_lock.name, self.sockname,  str(self.server_timeout), str(self.xmlrpcinterface[0]), str(self.xmlrpcinterface[1]))
+        os.execl(sys.executable, "bitbake-server", serverscript, "decafbad", str(self.bitbake_lock.fileno()), str(self.readypipein), self.logfile, self.bitbake_lock.name, self.sockname,  str(self.server_timeout or 0), str(self.xmlrpcinterface[0]), str(self.xmlrpcinterface[1]))
 
 def execServer(lockfd, readypipeinfd, lockname, sockname, server_timeout, xmlrpcinterface):
 

bitbake/lib/bb/siggen.py

@@ -402,7 +402,7 @@ class SignatureGeneratorBasic(SignatureGenerator):
                 p = pickle.dump(data, stream, -1)
                 stream.flush()
             os.chmod(tmpfile, 0o664)
-            os.rename(tmpfile, sigfile)
+            bb.utils.rename(tmpfile, sigfile)
         except (OSError, IOError) as err:
             try:
                 os.unlink(tmpfile)
@@ -542,7 +542,7 @@ class SignatureGeneratorUniHashMixIn(object):
                 hashequiv_logger.debug((1, 2)[unihash == taskhash], 'Found unihash %s in place of %s for %s from %s' % (unihash, taskhash, tid, self.server))
             else:
                 hashequiv_logger.debug2('No reported unihash for %s:%s from %s' % (tid, taskhash, self.server))
-        except hashserv.client.HashConnectionError as e:
+        except ConnectionError as e:
             bb.warn('Error contacting Hash Equivalence Server %s: %s' % (self.server, str(e)))
 
         self.set_unihash(tid, unihash)
@@ -621,7 +621,7 @@ class SignatureGeneratorUniHashMixIn(object):
                     d.setVar('BB_UNIHASH', new_unihash)
                 else:
                     hashequiv_logger.debug('Reported task %s as unihash %s to %s' % (taskhash, unihash, self.server))
-            except hashserv.client.HashConnectionError as e:
+            except ConnectionError as e:
                 bb.warn('Error contacting Hash Equivalence Server %s: %s' % (self.server, str(e)))
         finally:
             if sigfile:
@@ -661,7 +661,7 @@ class SignatureGeneratorUniHashMixIn(object):
                 # TODO: What to do here?
                 hashequiv_logger.verbose('Task %s unihash reported as unwanted hash %s' % (tid, finalunihash))
 
-        except hashserv.client.HashConnectionError as e:
+        except ConnectionError as e:
             bb.warn('Error contacting Hash Equivalence Server %s: %s' % (self.server, str(e)))
 
         return False

bitbake/lib/bb/tests/fetch.py

@@ -390,6 +390,7 @@ class FetcherTest(unittest.TestCase):
         if os.environ.get("BB_TMPDIR_NOCLEAN") == "yes":
             print("Not cleaning up %s. Please remove manually." % self.tempdir)
         else:
+            bb.process.run('chmod u+rw -R %s' % self.tempdir)
             bb.utils.prunedir(self.tempdir)
 
 class MirrorUriTest(FetcherTest):
@@ -673,12 +674,14 @@ class FetcherLocalTest(FetcherTest):
         with self.assertRaises(bb.fetch2.UnpackError):
             self.fetchUnpack(['file://a;subdir=/bin/sh'])
 
-    def test_local_gitfetch_usehead(self):
+    def dummyGitTest(self, suffix):
         # Create dummy local Git repo
         src_dir = tempfile.mkdtemp(dir=self.tempdir,
                                    prefix='gitfetch_localusehead_')
         src_dir = os.path.abspath(src_dir)
         bb.process.run("git init", cwd=src_dir)
+        bb.process.run("git config user.email 'you@example.com'", cwd=src_dir)
+        bb.process.run("git config user.name 'Your Name'", cwd=src_dir)
         bb.process.run("git commit --allow-empty -m'Dummy commit'",
                        cwd=src_dir)
         # Use other branch than master
@@ -690,7 +693,7 @@ class FetcherLocalTest(FetcherTest):
 
         # Fetch and check revision
         self.d.setVar("SRCREV", "AUTOINC")
-        url = "git://" + src_dir + ";protocol=file;usehead=1"
+        url = "git://" + src_dir + ";protocol=file;" + suffix
         fetcher = bb.fetch.Fetch([url], self.d)
         fetcher.download()
         fetcher.unpack(self.unpackdir)
@@ -699,31 +702,23 @@ class FetcherLocalTest(FetcherTest):
         unpack_rev = stdout[0].strip()
         self.assertEqual(orig_rev, unpack_rev)
 
+    def test_local_gitfetch_usehead(self):
+        self.dummyGitTest("usehead=1")
+
     def test_local_gitfetch_usehead_withname(self):
-        # Create dummy local Git repo
-        src_dir = tempfile.mkdtemp(dir=self.tempdir,
-                                   prefix='gitfetch_localusehead_')
-        src_dir = os.path.abspath(src_dir)
-        bb.process.run("git init", cwd=src_dir)
-        bb.process.run("git commit --allow-empty -m'Dummy commit'",
-                       cwd=src_dir)
-        # Use other branch than master
-        bb.process.run("git checkout -b my-devel", cwd=src_dir)
-        bb.process.run("git commit --allow-empty -m'Dummy commit 2'",
-                       cwd=src_dir)
-        stdout = bb.process.run("git rev-parse HEAD", cwd=src_dir)
-        orig_rev = stdout[0].strip()
+        self.dummyGitTest("usehead=1;name=newName")
 
-        # Fetch and check revision
-        self.d.setVar("SRCREV", "AUTOINC")
-        url = "git://" + src_dir + ";protocol=file;usehead=1;name=newName"
-        fetcher = bb.fetch.Fetch([url], self.d)
-        fetcher.download()
-        fetcher.unpack(self.unpackdir)
-        stdout = bb.process.run("git rev-parse HEAD",
-                                cwd=os.path.join(self.unpackdir, 'git'))
-        unpack_rev = stdout[0].strip()
-        self.assertEqual(orig_rev, unpack_rev)
+    def test_local_gitfetch_shared(self):
+        self.dummyGitTest("usehead=1;name=sharedName")
+        alt = os.path.join(self.unpackdir, 'git/.git/objects/info/alternates')
+        self.assertTrue(os.path.exists(alt))
+
+    def test_local_gitfetch_noshared(self):
+        self.d.setVar('BB_GIT_NOSHARED', '1')
+        self.unpackdir += '_noshared'
+        self.dummyGitTest("usehead=1;name=noSharedName")
+        alt = os.path.join(self.unpackdir, 'git/.git/objects/info/alternates')
+        self.assertFalse(os.path.exists(alt))
 
 class FetcherNoNetworkTest(FetcherTest):
     def setUp(self):
@@ -1390,6 +1385,8 @@ class GitMakeShallowTest(FetcherTest):
         self.gitdir = os.path.join(self.tempdir, 'gitshallow')
         bb.utils.mkdirhier(self.gitdir)
         bb.process.run('git init', cwd=self.gitdir)
+        bb.process.run('git config user.email "you@example.com"', cwd=self.gitdir)
+        bb.process.run('git config user.name "Your Name"', cwd=self.gitdir)
 
     def assertRefs(self, expected_refs):
         actual_refs = self.git(['for-each-ref', '--format=%(refname)']).splitlines()
@@ -1513,6 +1510,8 @@ class GitShallowTest(FetcherTest):
 
         bb.utils.mkdirhier(self.srcdir)
         self.git('init', cwd=self.srcdir)
+        self.git('config user.email "you@example.com"', cwd=self.srcdir)
+        self.git('config user.name "Your Name"', cwd=self.srcdir)
         self.d.setVar('WORKDIR', self.tempdir)
         self.d.setVar('S', self.gitdir)
         self.d.delVar('PREMIRRORS')
@@ -1594,6 +1593,7 @@ class GitShallowTest(FetcherTest):
 
         # fetch and unpack, from the shallow tarball
         bb.utils.remove(self.gitdir, recurse=True)
+        bb.process.run('chmod u+w -R "%s"' % ud.clonedir)
         bb.utils.remove(ud.clonedir, recurse=True)
         bb.utils.remove(ud.clonedir.replace('gitsource', 'gitsubmodule'), recurse=True)
 
@@ -1746,6 +1746,8 @@ class GitShallowTest(FetcherTest):
         smdir = os.path.join(self.tempdir, 'gitsubmodule')
         bb.utils.mkdirhier(smdir)
         self.git('init', cwd=smdir)
+        self.git('config user.email "you@example.com"', cwd=smdir)
+        self.git('config user.name "Your Name"', cwd=smdir)
         # Make this look like it was cloned from a remote...
         self.git('config --add remote.origin.url "%s"' % smdir, cwd=smdir)
         self.git('config --add remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"', cwd=smdir)
@@ -1776,6 +1778,8 @@ class GitShallowTest(FetcherTest):
         smdir = os.path.join(self.tempdir, 'gitsubmodule')
         bb.utils.mkdirhier(smdir)
         self.git('init', cwd=smdir)
+        self.git('config user.email "you@example.com"', cwd=smdir)
+        self.git('config user.name "Your Name"', cwd=smdir)
         # Make this look like it was cloned from a remote...
         self.git('config --add remote.origin.url "%s"' % smdir, cwd=smdir)
         self.git('config --add remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"', cwd=smdir)
@@ -1794,7 +1798,7 @@ class GitShallowTest(FetcherTest):
 
         # Set up the mirror
         mirrordir = os.path.join(self.tempdir, 'mirror')
-        os.rename(self.dldir, mirrordir)
+        bb.utils.rename(self.dldir, mirrordir)
         self.d.setVar('PREMIRRORS', 'gitsm://.*/.* file://%s/\n' % mirrordir)
 
         # Fetch from the mirror
@@ -1818,8 +1822,8 @@ class GitShallowTest(FetcherTest):
             self.git('annex init', cwd=self.srcdir)
             open(os.path.join(self.srcdir, 'c'), 'w').close()
             self.git('annex add c', cwd=self.srcdir)
-            self.git('commit -m annex-c -a', cwd=self.srcdir)
-            bb.process.run('chmod u+w -R %s' % os.path.join(self.srcdir, '.git', 'annex'))
+            self.git('commit --author "Foo Bar <foo@bar>" -m annex-c -a', cwd=self.srcdir)
+            bb.process.run('chmod u+w -R %s' % self.srcdir)
 
             uri = 'gitannex://%s;protocol=file;subdir=${S}' % self.srcdir
             fetcher, ud = self.fetch_shallow(uri)
@@ -1912,7 +1916,7 @@ class GitShallowTest(FetcherTest):
         bb.utils.mkdirhier(mirrordir)
         self.d.setVar('PREMIRRORS', 'git://.*/.* file://%s/\n' % mirrordir)
 
-        os.rename(os.path.join(self.dldir, mirrortarball),
+        bb.utils.rename(os.path.join(self.dldir, mirrortarball),
                   os.path.join(mirrordir, mirrortarball))
 
         # Fetch from the mirror
@@ -2094,6 +2098,8 @@ class GitLfsTest(FetcherTest):
 
         bb.utils.mkdirhier(self.srcdir)
         self.git('init', cwd=self.srcdir)
+        self.git('config user.email "you@example.com"', cwd=self.srcdir)
+        self.git('config user.name "Your Name"', cwd=self.srcdir)
         with open(os.path.join(self.srcdir, '.gitattributes'), 'wt') as attrs:
             attrs.write('*.mp3 filter=lfs -text')
         self.git(['add', '.gitattributes'], cwd=self.srcdir)
@@ -2634,3 +2640,29 @@ class NPMTest(FetcherTest):
         fetcher = bb.fetch.Fetch(['npmsw://' + swfile], self.d)
         fetcher.download()
         self.assertTrue(os.path.exists(ud.localpath))
+
+class GitSharedTest(FetcherTest):
+    def setUp(self):
+        super(GitSharedTest, self).setUp()
+        self.recipe_url = "git://git.openembedded.org/bitbake"
+        self.d.setVar('SRCREV', '82ea737a0b42a8b53e11c9cde141e9e9c0bd8c40')
+
+    @skipIfNoNetwork()
+    def test_shared_unpack(self):
+        fetcher = bb.fetch.Fetch([self.recipe_url], self.d)
+
+        fetcher.download()
+        fetcher.unpack(self.unpackdir)
+        alt = os.path.join(self.unpackdir, 'git/.git/objects/info/alternates')
+        self.assertTrue(os.path.exists(alt))
+
+    @skipIfNoNetwork()
+    def test_noshared_unpack(self):
+        self.d.setVar('BB_GIT_NOSHARED', '1')
+        self.unpackdir += '_noshared'
+        fetcher = bb.fetch.Fetch([self.recipe_url], self.d)
+
+        fetcher.download()
+        fetcher.unpack(self.unpackdir)
+        alt = os.path.join(self.unpackdir, 'git/.git/objects/info/alternates')
+        self.assertFalse(os.path.exists(alt))

bitbake/lib/bb/tinfoil.py

@@ -52,6 +52,10 @@ class TinfoilDataStoreConnectorVarHistory:
     def remoteCommand(self, cmd, *args, **kwargs):
         return self.tinfoil.run_command('dataStoreConnectorVarHistCmd', self.dsindex, cmd, args, kwargs)
 
+    def emit(self, var, oval, val, o, d):
+        ret = self.tinfoil.run_command('dataStoreConnectorVarHistCmdEmit', self.dsindex, var, oval, val, d.dsindex)
+        o.write(ret)
+
     def __getattr__(self, name):
         if not hasattr(bb.data_smart.VariableHistory, name):
             raise AttributeError("VariableHistory has no such method %s" % name)

bitbake/lib/bb/ui/knotty.py

@@ -21,6 +21,7 @@ import fcntl
 import struct
 import copy
 import atexit
+from itertools import groupby
 
 from bb.ui import uihelper
 
@@ -539,6 +540,13 @@ def main(server, eventHandler, params, tf = TerminalFilter):
         except OSError:
            pass
 
+    # Add the logging domains specified by the user on the command line
+    for (domainarg, iterator) in groupby(params.debug_domains):
+        dlevel = len(tuple(iterator))
+        l = logconfig["loggers"].setdefault("BitBake.%s" % domainarg, {})
+        l["level"] = logging.DEBUG - dlevel + 1
+        l.setdefault("handlers", []).extend(["BitBake.verbconsole"])
+
     conf = bb.msg.setLoggingConfig(logconfig, logconfigfile)
 
     if sys.stdin.isatty() and sys.stdout.isatty():

bitbake/lib/bb/utils.py

@@ -782,7 +782,7 @@ def movefile(src, dest, newmtime = None, sstat = None):
 
     if sstat[stat.ST_DEV] == dstat[stat.ST_DEV]:
         try:
-            os.rename(src, destpath)
+            bb.utils.rename(src, destpath)
             renamefailed = 0
         except Exception as e:
             if e.errno != errno.EXDEV:
@@ -796,7 +796,7 @@ def movefile(src, dest, newmtime = None, sstat = None):
         if stat.S_ISREG(sstat[stat.ST_MODE]):
             try: # For safety copy then move it over.
                 shutil.copyfile(src, destpath + "#new")
-                os.rename(destpath + "#new", destpath)
+                bb.utils.rename(destpath + "#new", destpath)
                 didcopy = 1
             except Exception as e:
                 print('movefile: copy', src, '->', dest, 'failed.', e)
@@ -874,7 +874,7 @@ def copyfile(src, dest, newmtime = None, sstat = None):
 
             # For safety copy then move it over.
             shutil.copyfile(src, dest + "#new")
-            os.rename(dest + "#new", dest)
+            bb.utils.rename(dest + "#new", dest)
         except Exception as e:
             logger.warning("copyfile: copy %s to %s failed (%s)" % (src, dest, e))
             return False
@@ -1669,3 +1669,15 @@ def is_semver(version):
         return False
 
     return True
+
+# Wrapper around os.rename which can handle cross device problems
+# e.g. from container filesystems
+def rename(src, dst):
+    try:
+        os.rename(src, dst)
+    except OSError as err:
+        if err.errno == 18:
+            # Invalid cross-device link error
+            shutil.move(src, dst)
+        else:
+            raise err

bitbake/lib/bblayers/layerindex.py

@@ -159,12 +159,17 @@ class LayerIndexPlugin(ActionPlugin):
                 logger.plain('  recommended by: %s' % ' '.join(recommendedby))
 
         if dependencies:
-            fetchdir = self.tinfoil.config_data.getVar('BBLAYERS_FETCH_DIR')
-            if not fetchdir:
-                logger.error("Cannot get BBLAYERS_FETCH_DIR")
-                return 1
+            if args.fetchdir:
+                fetchdir = args.fetchdir
+            else:
+                fetchdir = self.tinfoil.config_data.getVar('BBLAYERS_FETCH_DIR')
+                if not fetchdir:
+                    logger.error("Cannot get BBLAYERS_FETCH_DIR")
+                    return 1
+
             if not os.path.exists(fetchdir):
                 os.makedirs(fetchdir)
+
             addlayers = []
 
             for deplayerbranch in dependencies:
@@ -206,6 +211,8 @@ class LayerIndexPlugin(ActionPlugin):
 """
         args.show_only = True
         args.ignore = []
+        args.fetchdir = ""
+        args.shallow = True
         self.do_layerindex_fetch(args)
 
     def register_commands(self, sp):
@@ -214,6 +221,7 @@ class LayerIndexPlugin(ActionPlugin):
         parser_layerindex_fetch.add_argument('-b', '--branch', help='branch name to fetch')
         parser_layerindex_fetch.add_argument('-s', '--shallow', help='do only shallow clones (--depth=1)', action='store_true')
         parser_layerindex_fetch.add_argument('-i', '--ignore', help='assume the specified layers do not need to be fetched/added (separate multiple layers with commas, no spaces)', metavar='LAYER')
+        parser_layerindex_fetch.add_argument('-f', '--fetchdir', help='directory to fetch the layer(s) into (will be created if it does not exist)')
         parser_layerindex_fetch.add_argument('layername', nargs='+', help='layer to fetch')
 
         parser_layerindex_show_depends = self.add_command(sp, 'layerindex-show-depends', self.do_layerindex_show_depends, parserecipes=False)

bitbake/lib/hashserv/client.py

@@ -3,115 +3,28 @@
 # SPDX-License-Identifier: GPL-2.0-only
 #
 
-import asyncio
-import json
 import logging
 import socket
-import os
-from . import chunkify, DEFAULT_MAX_CHUNK, create_async_client
+import bb.asyncrpc
+from . import create_async_client
 
 
 logger = logging.getLogger("hashserv.client")
 
 
-class HashConnectionError(Exception):
-    pass
-
-
-class AsyncClient(object):
+class AsyncClient(bb.asyncrpc.AsyncClient):
     MODE_NORMAL = 0
     MODE_GET_STREAM = 1
 
     def __init__(self):
-        self.reader = None
-        self.writer = None
+        super().__init__('OEHASHEQUIV', '1.1', logger)
         self.mode = self.MODE_NORMAL
-        self.max_chunk = DEFAULT_MAX_CHUNK
 
-    async def connect_tcp(self, address, port):
-        async def connect_sock():
-            return await asyncio.open_connection(address, port)
-
-        self._connect_sock = connect_sock
-
-    async def connect_unix(self, path):
-        async def connect_sock():
-            return await asyncio.open_unix_connection(path)
-
-        self._connect_sock = connect_sock
-
-    async def connect(self):
-        if self.reader is None or self.writer is None:
-            (self.reader, self.writer) = await self._connect_sock()
-
-            self.writer.write("OEHASHEQUIV 1.1\n\n".encode("utf-8"))
-            await self.writer.drain()
-
-            cur_mode = self.mode
-            self.mode = self.MODE_NORMAL
-            await self._set_mode(cur_mode)
-
-    async def close(self):
-        self.reader = None
-
-        if self.writer is not None:
-            self.writer.close()
-            self.writer = None
-
-    async def _send_wrapper(self, proc):
-        count = 0
-        while True:
-            try:
-                await self.connect()
-                return await proc()
-            except (
-                OSError,
-                HashConnectionError,
-                json.JSONDecodeError,
-                UnicodeDecodeError,
-            ) as e:
-                logger.warning("Error talking to server: %s" % e)
-                if count >= 3:
-                    if not isinstance(e, HashConnectionError):
-                        raise HashConnectionError(str(e))
-                    raise e
-                await self.close()
-                count += 1
-
-    async def send_message(self, msg):
-        async def get_line():
-            line = await self.reader.readline()
-            if not line:
-                raise HashConnectionError("Connection closed")
-
-            line = line.decode("utf-8")
-
-            if not line.endswith("\n"):
-                raise HashConnectionError("Bad message %r" % message)
-
-            return line
-
-        async def proc():
-            for c in chunkify(json.dumps(msg), self.max_chunk):
-                self.writer.write(c.encode("utf-8"))
-            await self.writer.drain()
-
-            l = await get_line()
-
-            m = json.loads(l)
-            if m and "chunk-stream" in m:
-                lines = []
-                while True:
-                    l = (await get_line()).rstrip("\n")
-                    if not l:
-                        break
-                    lines.append(l)
-
-                m = json.loads("".join(lines))
-
-            return m
-
-        return await self._send_wrapper(proc)
+    async def setup_connection(self):
+        await super().setup_connection()
+        cur_mode = self.mode
+        self.mode = self.MODE_NORMAL
+        await self._set_mode(cur_mode)
 
     async def send_stream(self, msg):
         async def proc():
@@ -119,7 +32,7 @@ class AsyncClient(object):
             await self.writer.drain()
             l = await self.reader.readline()
             if not l:
-                raise HashConnectionError("Connection closed")
+                raise ConnectionError("Connection closed")
             return l.decode("utf-8").rstrip()
 
         return await self._send_wrapper(proc)
@@ -128,11 +41,11 @@ class AsyncClient(object):
         if new_mode == self.MODE_NORMAL and self.mode == self.MODE_GET_STREAM:
             r = await self.send_stream("END")
             if r != "ok":
-                raise HashConnectionError("Bad response from server %r" % r)
+                raise ConnectionError("Bad response from server %r" % r)
         elif new_mode == self.MODE_GET_STREAM and self.mode == self.MODE_NORMAL:
             r = await self.send_message({"get-stream": None})
             if r != "ok":
-                raise HashConnectionError("Bad response from server %r" % r)
+                raise ConnectionError("Bad response from server %r" % r)
         elif new_mode != self.mode:
             raise Exception(
                 "Undefined mode transition %r -> %r" % (self.mode, new_mode)
@@ -189,12 +102,10 @@ class AsyncClient(object):
         return (await self.send_message({"backfill-wait": None}))["tasks"]
 
 
-class Client(object):
+class Client(bb.asyncrpc.Client):
     def __init__(self):
-        self.client = AsyncClient()
-        self.loop = asyncio.new_event_loop()
-
-        for call in (
+        super().__init__()
+        self._add_methods(
             "connect_tcp",
             "close",
             "get_unihash",
@@ -204,30 +115,7 @@ class Client(object):
             "get_stats",
             "reset_stats",
             "backfill_wait",
-        ):
-            downcall = getattr(self.client, call)
-            setattr(self, call, self._get_downcall_wrapper(downcall))
+        )
 
-    def _get_downcall_wrapper(self, downcall):
-        def wrapper(*args, **kwargs):
-            return self.loop.run_until_complete(downcall(*args, **kwargs))
-
-        return wrapper
-
-    def connect_unix(self, path):
-        # AF_UNIX has path length issues so chdir here to workaround
-        cwd = os.getcwd()
-        try:
-            os.chdir(os.path.dirname(path))
-            self.loop.run_until_complete(self.client.connect_unix(os.path.basename(path)))
-            self.loop.run_until_complete(self.client.connect())
-        finally:
-            os.chdir(cwd)
-
-    @property
-    def max_chunk(self):
-        return self.client.max_chunk
-
-    @max_chunk.setter
-    def max_chunk(self, value):
-        self.client.max_chunk = value
+    def _get_async_client(self):
+        return AsyncClient()

bitbake/lib/hashserv/server.py

@@ -6,15 +6,12 @@
 from contextlib import closing, contextmanager
 from datetime import datetime
 import asyncio
-import json
 import logging
 import math
-import os
-import signal
-import socket
-import sys
 import time
-from . import chunkify, DEFAULT_MAX_CHUNK, create_async_client, TABLE_COLUMNS
+from . import create_async_client, TABLE_COLUMNS
+import bb.asyncrpc
+
 
 logger = logging.getLogger('hashserv.server')
 
@@ -109,12 +106,6 @@ class Stats(object):
         return {k: getattr(self, k) for k in ('num', 'total_time', 'max_time', 'average', 'stdev')}
 
 
-class ClientError(Exception):
-    pass
-
-class ServerError(Exception):
-    pass
-
 def insert_task(cursor, data, ignore=False):
     keys = sorted(data.keys())
     query = '''INSERT%s INTO tasks_v2 (%s) VALUES (%s)''' % (
@@ -128,7 +119,6 @@ async def copy_from_upstream(client, db, method, taskhash):
     if d is not None:
         # Filter out unknown columns
         d = {k: v for k, v in d.items() if k in TABLE_COLUMNS}
-        keys = sorted(d.keys())
 
         with closing(db.cursor()) as cursor:
             insert_task(cursor, d)
@@ -141,7 +131,6 @@ async def copy_outhash_from_upstream(client, db, method, outhash, taskhash):
     if d is not None:
         # Filter out unknown columns
         d = {k: v for k, v in d.items() if k in TABLE_COLUMNS}
-        keys = sorted(d.keys())
 
         with closing(db.cursor()) as cursor:
             insert_task(cursor, d)
@@ -149,7 +138,7 @@ async def copy_outhash_from_upstream(client, db, method, outhash, taskhash):
 
     return d
 
-class ServerClient(object):
+class ServerClient(bb.asyncrpc.AsyncServerConnection):
     FAST_QUERY = 'SELECT taskhash, method, unihash FROM tasks_v2 WHERE method=:method AND taskhash=:taskhash ORDER BY created ASC LIMIT 1'
     ALL_QUERY =  'SELECT *                         FROM tasks_v2 WHERE method=:method AND taskhash=:taskhash ORDER BY created ASC LIMIT 1'
     OUTHASH_QUERY = '''
@@ -168,21 +157,19 @@ class ServerClient(object):
         '''
 
     def __init__(self, reader, writer, db, request_stats, backfill_queue, upstream, read_only):
-        self.reader = reader
-        self.writer = writer
+        super().__init__(reader, writer, 'OEHASHEQUIV', logger)
         self.db = db
         self.request_stats = request_stats
-        self.max_chunk = DEFAULT_MAX_CHUNK
+        self.max_chunk = bb.asyncrpc.DEFAULT_MAX_CHUNK
         self.backfill_queue = backfill_queue
         self.upstream = upstream
 
-        self.handlers = {
+        self.handlers.update({
             'get': self.handle_get,
             'get-outhash': self.handle_get_outhash,
             'get-stream': self.handle_get_stream,
             'get-stats': self.handle_get_stats,
-            'chunk-stream': self.handle_chunk,
-        }
+        })
 
         if not read_only:
             self.handlers.update({
@@ -192,56 +179,19 @@ class ServerClient(object):
                 'backfill-wait': self.handle_backfill_wait,
             })
 
+    def validate_proto_version(self):
+        return (self.proto_version > (1, 0) and self.proto_version <= (1, 1))
+
     async def process_requests(self):
         if self.upstream is not None:
             self.upstream_client = await create_async_client(self.upstream)
         else:
             self.upstream_client = None
 
-        try:
+        await super().process_requests()
 
-
-            self.addr = self.writer.get_extra_info('peername')
-            logger.debug('Client %r connected' % (self.addr,))
-
-            # Read protocol and version
-            protocol = await self.reader.readline()
-            if protocol is None:
-                return
-
-            (proto_name, proto_version) = protocol.decode('utf-8').rstrip().split()
-            if proto_name != 'OEHASHEQUIV':
-                return
-
-            proto_version = tuple(int(v) for v in proto_version.split('.'))
-            if proto_version < (1, 0) or proto_version > (1, 1):
-                return
-
-            # Read headers. Currently, no headers are implemented, so look for
-            # an empty line to signal the end of the headers
-            while True:
-                line = await self.reader.readline()
-                if line is None:
-                    return
-
-                line = line.decode('utf-8').rstrip()
-                if not line:
-                    break
-
-            # Handle messages
-            while True:
-                d = await self.read_message()
-                if d is None:
-                    break
-                await self.dispatch_message(d)
-                await self.writer.drain()
-        except ClientError as e:
-            logger.error(str(e))
-        finally:
-            if self.upstream_client is not None:
-                await self.upstream_client.close()
-
-            self.writer.close()
+        if self.upstream_client is not None:
+            await self.upstream_client.close()
 
     async def dispatch_message(self, msg):
         for k in self.handlers.keys():
@@ -255,47 +205,7 @@ class ServerClient(object):
                         await self.handlers[k](msg[k])
                 return
 
-        raise ClientError("Unrecognized command %r" % msg)
-
-    def write_message(self, msg):
-        for c in chunkify(json.dumps(msg), self.max_chunk):
-            self.writer.write(c.encode('utf-8'))
-
-    async def read_message(self):
-        l = await self.reader.readline()
-        if not l:
-            return None
-
-        try:
-            message = l.decode('utf-8')
-
-            if not message.endswith('\n'):
-                return None
-
-            return json.loads(message)
-        except (json.JSONDecodeError, UnicodeDecodeError) as e:
-            logger.error('Bad message from client: %r' % message)
-            raise e
-
-    async def handle_chunk(self, request):
-        lines = []
-        try:
-            while True:
-                l = await self.reader.readline()
-                l = l.rstrip(b"\n").decode("utf-8")
-                if not l:
-                    break
-                lines.append(l)
-
-            msg = json.loads(''.join(lines))
-        except (json.JSONDecodeError, UnicodeDecodeError) as e:
-            logger.error('Bad message from client: %r' % message)
-            raise e
-
-        if 'chunk-stream' in msg:
-            raise ClientError("Nested chunks are not allowed")
-
-        await self.dispatch_message(msg)
+        raise bb.asyncrpc.ClientError("Unrecognized command %r" % msg)
 
     async def handle_get(self, request):
         method = request['method']
@@ -499,74 +409,20 @@ class ServerClient(object):
             cursor.close()
 
 
-class Server(object):
+class Server(bb.asyncrpc.AsyncServer):
     def __init__(self, db, loop=None, upstream=None, read_only=False):
         if upstream and read_only:
-            raise ServerError("Read-only hashserv cannot pull from an upstream server")
+            raise bb.asyncrpc.ServerError("Read-only hashserv cannot pull from an upstream server")
+
+        super().__init__(logger, loop)
 
         self.request_stats = Stats()
         self.db = db
-
-        if loop is None:
-            self.loop = asyncio.new_event_loop()
-            self.close_loop = True
-        else:
-            self.loop = loop
-            self.close_loop = False
-
         self.upstream = upstream
         self.read_only = read_only
 
-        self._cleanup_socket = None
-
-    def start_tcp_server(self, host, port):
-        self.server = self.loop.run_until_complete(
-            asyncio.start_server(self.handle_client, host, port, loop=self.loop)
-        )
-
-        for s in self.server.sockets:
-            logger.info('Listening on %r' % (s.getsockname(),))
-            # Newer python does this automatically. Do it manually here for
-            # maximum compatibility
-            s.setsockopt(socket.SOL_TCP, socket.TCP_NODELAY, 1)
-            s.setsockopt(socket.SOL_TCP, socket.TCP_QUICKACK, 1)
-
-        name = self.server.sockets[0].getsockname()
-        if self.server.sockets[0].family == socket.AF_INET6:
-            self.address = "[%s]:%d" % (name[0], name[1])
-        else:
-            self.address = "%s:%d" % (name[0], name[1])
-
-    def start_unix_server(self, path):
-        def cleanup():
-            os.unlink(path)
-
-        cwd = os.getcwd()
-        try:
-            # Work around path length limits in AF_UNIX
-            os.chdir(os.path.dirname(path))
-            self.server = self.loop.run_until_complete(
-                asyncio.start_unix_server(self.handle_client, os.path.basename(path), loop=self.loop)
-            )
-        finally:
-            os.chdir(cwd)
-
-        logger.info('Listening on %r' % path)
-
-        self._cleanup_socket = cleanup
-        self.address = "unix://%s" % os.path.abspath(path)
-
-    async def handle_client(self, reader, writer):
-        # writer.transport.set_write_buffer_limits(0)
-        try:
-            client = ServerClient(reader, writer, self.db, self.request_stats, self.backfill_queue, self.upstream, self.read_only)
-            await client.process_requests()
-        except Exception as e:
-            import traceback
-            logger.error('Error from client: %s' % str(e), exc_info=True)
-            traceback.print_exc()
-            writer.close()
-        logger.info('Client disconnected')
+    def accept_client(self, reader, writer):
+        return ServerClient(reader, writer, self.db, self.request_stats, self.backfill_queue, self.upstream, self.read_only)
 
     @contextmanager
     def _backfill_worker(self):
@@ -597,31 +453,8 @@ class Server(object):
         else:
             yield
 
-    def serve_forever(self):
-        def signal_handler():
-            self.loop.stop()
+    def run_loop_forever(self):
+        self.backfill_queue = asyncio.Queue()
 
-        asyncio.set_event_loop(self.loop)
-        try:
-            self.backfill_queue = asyncio.Queue()
-
-            self.loop.add_signal_handler(signal.SIGTERM, signal_handler)
-
-            with self._backfill_worker():
-                try:
-                    self.loop.run_forever()
-                except KeyboardInterrupt:
-                    pass
-
-                self.server.close()
-
-            self.loop.run_until_complete(self.server.wait_closed())
-            logger.info('Server shutting down')
-        finally:
-            if self.close_loop:
-                if sys.version_info >= (3, 6):
-                    self.loop.run_until_complete(self.loop.shutdown_asyncgens())
-                self.loop.close()
-
-            if self._cleanup_socket is not None:
-                self._cleanup_socket()
+        with self._backfill_worker():
+            super().run_loop_forever()

bitbake/lib/hashserv/tests.py

@@ -6,7 +6,6 @@
 #
 
 from . import create_server, create_client
-from .client import HashConnectionError
 import hashlib
 import logging
 import multiprocessing
@@ -277,7 +276,7 @@ class HashEquivalenceCommonTests(object):
         outhash2 = '3c979c3db45c569f51ab7626a4651074be3a9d11a84b1db076f5b14f7d39db44'
         unihash2 = '90e9bc1d1f094c51824adca7f8ea79a048d68824'
 
-        with self.assertRaises(HashConnectionError):
+        with self.assertRaises(ConnectionError):
             ro_client.report_unihash(taskhash2, self.METHOD, outhash2, unihash2)
 
         # Ensure that the database was not modified

bitbake/lib/prserv/serv.py

@@ -5,8 +5,6 @@
 import os,sys,logging
 import signal, time
 from xmlrpc.server import SimpleXMLRPCServer, SimpleXMLRPCRequestHandler
-import threading
-import queue
 import socket
 import io
 import sqlite3
@@ -14,14 +12,10 @@ import bb.server.xmlrpcclient
 import prserv
 import prserv.db
 import errno
-import select
+import multiprocessing
 
 logger = logging.getLogger("BitBake.PRserv")
 
-if sys.hexversion < 0x020600F0:
-    print("Sorry, python 2.6 or later is required.")
-    sys.exit(1)
-
 class Handler(SimpleXMLRPCRequestHandler):
     def _dispatch(self,method,params):
         try:
@@ -37,7 +31,7 @@ singleton = None
 
 
 class PRServer(SimpleXMLRPCServer):
-    def __init__(self, dbfile, logfile, interface, daemon=True):
+    def __init__(self, dbfile, logfile, interface):
         ''' constructor '''
         try:
             SimpleXMLRPCServer.__init__(self, interface,
@@ -50,57 +44,18 @@ class PRServer(SimpleXMLRPCServer):
             raise PRServiceConfigError
 
         self.dbfile=dbfile
-        self.daemon=daemon
         self.logfile=logfile
-        self.working_thread=None
         self.host, self.port = self.socket.getsockname()
-        self.pidfile=PIDPREFIX % (self.host, self.port)
 
         self.register_function(self.getPR, "getPR")
-        self.register_function(self.quit, "quit")
         self.register_function(self.ping, "ping")
         self.register_function(self.export, "export")
-        self.register_function(self.dump_db, "dump_db")
         self.register_function(self.importone, "importone")
         self.register_introspection_functions()
 
-        self.quitpipein, self.quitpipeout = os.pipe()
-
-        self.requestqueue = queue.Queue()
-        self.handlerthread = threading.Thread(target = self.process_request_thread)
-        self.handlerthread.daemon = False
-
-    def process_request_thread(self):
-        """Same as in BaseServer but as a thread.
-
-        In addition, exception handling is done here.
-
-        """
-        iter_count = 1
+        self.iter_count = 0
         # 60 iterations between syncs or sync if dirty every ~30 seconds
-        iterations_between_sync = 60
-
-        bb.utils.set_process_name("PRServ Handler")
-
-        while not self.quitflag:
-            try:
-                (request, client_address) = self.requestqueue.get(True, 30)
-            except queue.Empty:
-                self.table.sync_if_dirty()
-                continue
-            if request is None:
-                continue
-            try:
-                self.finish_request(request, client_address)
-                self.shutdown_request(request)
-                iter_count = (iter_count + 1) % iterations_between_sync
-                if iter_count == 0:
-                    self.table.sync_if_dirty()
-            except:
-                self.handle_error(request, client_address)
-                self.shutdown_request(request)
-                self.table.sync()
-            self.table.sync_if_dirty()
+        self.iterations_between_sync = 60
 
     def sigint_handler(self, signum, stack):
         if self.table:
@@ -109,11 +64,30 @@ class PRServer(SimpleXMLRPCServer):
     def sigterm_handler(self, signum, stack):
         if self.table:
             self.table.sync()
-        self.quit()
-        self.requestqueue.put((None, None))
+        raise(SystemExit)
 
     def process_request(self, request, client_address):
-        self.requestqueue.put((request, client_address))
+        if request is None:
+            return
+        try:
+            self.finish_request(request, client_address)
+            self.shutdown_request(request)
+            self.iter_count = (self.iter_count + 1) % self.iterations_between_sync
+            if self.iter_count == 0:
+                self.table.sync_if_dirty()
+        except:
+            self.handle_error(request, client_address)
+            self.shutdown_request(request)
+            self.table.sync()
+        self.table.sync_if_dirty()
+
+    def serve_forever(self, poll_interval=0.5):
+        signal.signal(signal.SIGINT, self.sigint_handler)
+        signal.signal(signal.SIGTERM, self.sigterm_handler)
+
+        self.db = prserv.db.PRData(self.dbfile)
+        self.table = self.db["PRMAIN"]
+        return super().serve_forever(poll_interval)
 
     def export(self, version=None, pkgarch=None, checksum=None, colinfo=True):
         try:
@@ -122,31 +96,11 @@ class PRServer(SimpleXMLRPCServer):
             logger.error(str(exc))
             return None
 
-    def dump_db(self):
-        """
-        Returns a script (string) that reconstructs the state of the
-        entire database at the time this function is called. The script
-        language is defined by the backing database engine, which is a
-        function of server configuration.
-        Returns None if the database engine does not support dumping to
-        script or if some other error is encountered in processing.
-        """
-        buff = io.StringIO()
-        try:
-            self.table.sync()
-            self.table.dump_db(buff)
-            return buff.getvalue()
-        except Exception as exc:
-            logger.error(str(exc))
-            return None
-        finally:
-            buff.close()
-
     def importone(self, version, pkgarch, checksum, value):
         return self.table.importone(version, pkgarch, checksum, value)
 
     def ping(self):
-        return not self.quitflag
+        return True
 
     def getinfo(self):
         return (self.host, self.port)
@@ -161,144 +115,6 @@ class PRServer(SimpleXMLRPCServer):
             logger.error(str(exc))
             return None
 
-    def quit(self):
-        self.quitflag=True
-        os.write(self.quitpipeout, b"q")
-        os.close(self.quitpipeout)
-        return
-
-    def work_forever(self,):
-        self.quitflag = False
-        # This timeout applies to the poll in TCPServer, we need the select 
-        # below to wake on our quit pipe closing. We only ever call into handle_request
-        # if there is data there.
-        self.timeout = 0.01
-
-        bb.utils.set_process_name("PRServ")
-
-        # DB connection must be created after all forks
-        self.db = prserv.db.PRData(self.dbfile)
-        self.table = self.db["PRMAIN"]
-
-        logger.info("Started PRServer with DBfile: %s, IP: %s, PORT: %s, PID: %s" %
-                     (self.dbfile, self.host, self.port, str(os.getpid())))
-
-        self.handlerthread.start()
-        while not self.quitflag:
-            ready = select.select([self.fileno(), self.quitpipein], [], [], 30)
-            if self.quitflag:
-                break
-            if self.fileno() in ready[0]:
-                self.handle_request()
-        self.handlerthread.join()
-        self.db.disconnect()
-        logger.info("PRServer: stopping...")
-        self.server_close()
-        os.close(self.quitpipein)
-        return
-
-    def start(self):
-        if self.daemon:
-            pid = self.daemonize()
-        else:
-            pid = self.fork()
-            self.pid = pid
-
-        # Ensure both the parent sees this and the child from the work_forever log entry above
-        logger.info("Started PRServer with DBfile: %s, IP: %s, PORT: %s, PID: %s" %
-                     (self.dbfile, self.host, self.port, str(pid)))
-
-    def delpid(self):
-        os.remove(self.pidfile)
-
-    def daemonize(self):
-        """
-        See Advanced Programming in the UNIX, Sec 13.3
-        """
-        try:
-            pid = os.fork()
-            if pid > 0:
-                os.waitpid(pid, 0)
-                #parent return instead of exit to give control 
-                return pid
-        except OSError as e:
-            raise Exception("%s [%d]" % (e.strerror, e.errno))
-
-        os.setsid()
-        """
-        fork again to make sure the daemon is not session leader, 
-        which prevents it from acquiring controlling terminal
-        """
-        try:
-            pid = os.fork()
-            if pid > 0: #parent
-                os._exit(0)
-        except OSError as e:
-            raise Exception("%s [%d]" % (e.strerror, e.errno))
-
-        self.cleanup_handles()
-        os._exit(0)
-
-    def fork(self):
-        try:
-            pid = os.fork()
-            if pid > 0:
-                self.socket.close() # avoid ResourceWarning in parent
-                return pid
-        except OSError as e:
-            raise Exception("%s [%d]" % (e.strerror, e.errno))
-
-        bb.utils.signal_on_parent_exit("SIGTERM")
-        self.cleanup_handles()
-        os._exit(0)
-
-    def cleanup_handles(self):
-        signal.signal(signal.SIGINT, self.sigint_handler)
-        signal.signal(signal.SIGTERM, self.sigterm_handler)
-        os.chdir("/")
-
-        sys.stdout.flush()
-        sys.stderr.flush()
-
-        # We could be called from a python thread with io.StringIO as
-        # stdout/stderr or it could be 'real' unix fd forking where we need
-        # to physically close the fds to prevent the program launching us from
-        # potentially hanging on a pipe. Handle both cases.
-        si = open('/dev/null', 'r')
-        try:
-            os.dup2(si.fileno(),sys.stdin.fileno())
-        except (AttributeError, io.UnsupportedOperation):
-            sys.stdin = si
-        so = open(self.logfile, 'a+')
-        try:
-            os.dup2(so.fileno(),sys.stdout.fileno())
-        except (AttributeError, io.UnsupportedOperation):
-            sys.stdout = so
-        try:
-            os.dup2(so.fileno(),sys.stderr.fileno())
-        except (AttributeError, io.UnsupportedOperation):
-            sys.stderr = so
-
-        # Clear out all log handlers prior to the fork() to avoid calling
-        # event handlers not part of the PRserver
-        for logger_iter in logging.Logger.manager.loggerDict.keys():
-            logging.getLogger(logger_iter).handlers = []
-
-        # Ensure logging makes it to the logfile
-        streamhandler = logging.StreamHandler()
-        streamhandler.setLevel(logging.DEBUG)
-        formatter = bb.msg.BBLogFormatter("%(levelname)s: %(message)s")
-        streamhandler.setFormatter(formatter)
-        logger.addHandler(streamhandler)
-
-        # write pidfile
-        pid = str(os.getpid())
-        with open(self.pidfile, 'w') as pf:
-            pf.write("%s\n" % pid)
-
-        self.work_forever()
-        self.delpid()
-
 class PRServSingleton(object):
     def __init__(self, dbfile, logfile, interface):
         self.dbfile = dbfile
@@ -308,8 +124,10 @@ class PRServSingleton(object):
         self.port = None
 
     def start(self):
-        self.prserv = PRServer(self.dbfile, self.logfile, self.interface, daemon=False)
-        self.prserv.start()
+        self.prserv = PRServer(self.dbfile, self.logfile, self.interface)
+        self.process = multiprocessing.Process(target=self.prserv.serve_forever)
+        self.process.start()
+
         self.host, self.port = self.prserv.getinfo()
 
     def getinfo(self):
@@ -323,13 +141,6 @@ class PRServerConnection(object):
         self.port = port
         self.connection, self.transport = bb.server.xmlrpcclient._create_server(self.host, self.port)
 
-    def terminate(self):
-        try:
-            logger.info("Terminating PRServer...")
-            self.connection.quit()
-        except Exception as exc:
-            sys.stderr.write("%s\n" % str(exc))
-
     def getPR(self, version, pkgarch, checksum):
         return self.connection.getPR(version, pkgarch, checksum)
 
@@ -339,15 +150,82 @@ class PRServerConnection(object):
     def export(self,version=None, pkgarch=None, checksum=None, colinfo=True):
         return self.connection.export(version, pkgarch, checksum, colinfo)
 
-    def dump_db(self):
-        return self.connection.dump_db()
-
     def importone(self, version, pkgarch, checksum, value):
         return self.connection.importone(version, pkgarch, checksum, value)
 
     def getinfo(self):
         return self.host, self.port
 
+def run_as_daemon(func, pidfile, logfile):
+    """
+    See Advanced Programming in the UNIX, Sec 13.3
+    """
+    try:
+        pid = os.fork()
+        if pid > 0:
+            os.waitpid(pid, 0)
+            #parent return instead of exit to give control
+            return pid
+    except OSError as e:
+        raise Exception("%s [%d]" % (e.strerror, e.errno))
+
+    os.setsid()
+    """
+    fork again to make sure the daemon is not session leader,
+    which prevents it from acquiring controlling terminal
+    """
+    try:
+        pid = os.fork()
+        if pid > 0: #parent
+            os._exit(0)
+    except OSError as e:
+        raise Exception("%s [%d]" % (e.strerror, e.errno))
+
+    os.chdir("/")
+
+    sys.stdout.flush()
+    sys.stderr.flush()
+
+    # We could be called from a python thread with io.StringIO as
+    # stdout/stderr or it could be 'real' unix fd forking where we need
+    # to physically close the fds to prevent the program launching us from
+    # potentially hanging on a pipe. Handle both cases.
+    si = open('/dev/null', 'r')
+    try:
+        os.dup2(si.fileno(),sys.stdin.fileno())
+    except (AttributeError, io.UnsupportedOperation):
+        sys.stdin = si
+    so = open(logfile, 'a+')
+    try:
+        os.dup2(so.fileno(),sys.stdout.fileno())
+    except (AttributeError, io.UnsupportedOperation):
+        sys.stdout = so
+    try:
+        os.dup2(so.fileno(),sys.stderr.fileno())
+    except (AttributeError, io.UnsupportedOperation):
+        sys.stderr = so
+
+    # Clear out all log handlers prior to the fork() to avoid calling
+    # event handlers not part of the PRserver
+    for logger_iter in logging.Logger.manager.loggerDict.keys():
+        logging.getLogger(logger_iter).handlers = []
+
+    # Ensure logging makes it to the logfile
+    streamhandler = logging.StreamHandler()
+    streamhandler.setLevel(logging.DEBUG)
+    formatter = bb.msg.BBLogFormatter("%(levelname)s: %(message)s")
+    streamhandler.setFormatter(formatter)
+    logger.addHandler(streamhandler)
+
+    # write pidfile
+    pid = str(os.getpid())
+    with open(pidfile, 'w') as pf:
+        pf.write("%s\n" % pid)
+
+    func()
+    os.remove(pidfile)
+    os._exit(0)
+
 def start_daemon(dbfile, host, port, logfile):
     ip = socket.gethostbyname(host)
     pidfile = PIDPREFIX % (ip, port)
@@ -363,7 +241,7 @@ def start_daemon(dbfile, host, port, logfile):
         return 1
 
     server = PRServer(os.path.abspath(dbfile), os.path.abspath(logfile), (ip,port))
-    server.start()
+    run_as_daemon(server.serve_forever, pidfile, os.path.abspath(logfile))
 
     # Sometimes, the port (i.e. localhost:0) indicated by the user does not match with
     # the one the server actually is listening, so at least warn the user about it
@@ -400,25 +278,13 @@ def stop_daemon(host, port):
         return 1
 
     try:
-        PRServerConnection(ip, port).terminate()
-    except:
-        logger.critical("Stop PRService %s:%d failed" % (host,port))
+        if is_running(pid):
+            print("Sending SIGTERM to pr-server.")
+            os.kill(pid, signal.SIGTERM)
+            time.sleep(0.1)
 
-    try:
-        if pid:
-            wait_timeout = 0
-            print("Waiting for pr-server to exit.")
-            while is_running(pid) and wait_timeout < 50:
-                time.sleep(0.1)
-                wait_timeout += 1
-
-            if is_running(pid):
-                print("Sending SIGTERM to pr-server.")
-                os.kill(pid,signal.SIGTERM)
-                time.sleep(0.1)
-
-            if os.path.exists(pidfile):
-                os.remove(pidfile)
+        if os.path.exists(pidfile):
+            os.remove(pidfile)
 
     except OSError as e:
         err = str(e)
@@ -494,19 +360,14 @@ def auto_start(d):
 
 def auto_shutdown():
     global singleton
-    if singleton:
-        host, port = singleton.getinfo()
-        try:
-            PRServerConnection(host, port).terminate()
-        except:
-            logger.critical("Stop PRService %s:%d failed" % (host,port))
-
-        try:
-            os.waitpid(singleton.prserv.pid, 0)
-        except ChildProcessError:
-            pass
+    if singleton and singleton.process:
+        singleton.process.terminate()
+        singleton.process.join()
         singleton = None
 
 def ping(host, port):
     conn=PRServerConnection(host, port)
     return conn.ping()
+
+def connect(host, port):
+    return PRServerConnection(host, port)

documentation/README

@@ -167,7 +167,7 @@ The layout of the Yocto Project manuals is organized as follows
           Section
             Section
 
-The following headings styles are defined in Sphinx:
+Here are the heading styles defined in Sphinx:
 
     Book              => overline ===
       Chapter         => overline ***
@@ -259,6 +259,9 @@ websites.
 More information can be found here:
 https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html.
 
+Anchor (<#link>) links are forbidden as they are not checked by Sphinx during
+the build and may be broken without knowing about it.
+
 References
 ==========
 

documentation/bitbake.rst

@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+=====================
+BitBake Documentation
+=====================
+
+|
+
+BitBake was originally a part of the OpenEmbedded project. It was inspired by
+the Portage package management system used by the Gentoo Linux distribution. In
+2004, the OpenEmbedded project was split the project into two distinct pieces:
+
+-  BitBake, a generic task executor
+-  OpenEmbedded, a metadata set utilized by BitBake
+
+Today, BitBake is the primary build tool of OpenEmbedded based projects, such as
+the Yocto Project.
+
+The BitBake documentation can be found :doc:`here <bitbake:index>`.

documentation/brief-yoctoprojectqs/index.rst

@@ -60,10 +60,10 @@ following requirements:
 
 -
 
-   -  Git 1.8.3.1 or greater
-   -  tar 1.28 or greater
-   -  Python 3.5.0 or greater.
-   -  gcc 5.0 or greater.
+   -  Git &MIN_GIT_VERSION; or greater
+   -  tar &MIN_TAR_VERSION; or greater
+   -  Python &MIN_PYTHON_VERSION; or greater.
+   -  gcc &MIN_GCC_VERSION; 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
@@ -238,7 +238,7 @@ an entire Linux distribution, including the toolchain, from source.
 
       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: ::
+      local.conf file in the Build directory::
 
          SSTATE_MIRRORS = "\
          file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \

documentation/bsp-guide/bsp.rst

@@ -26,7 +26,7 @@ A BSP consists of a file structure inside a base directory.
 Collectively, you can think of the base directory, its file structure,
 and the contents as a BSP layer. Although not a strict requirement, BSP
 layers in the Yocto Project use the following well-established naming
-convention: ::
+convention::
 
    meta-bsp_root_name
 
@@ -58,7 +58,7 @@ Each repository is a BSP layer supported by the Yocto Project (e.g.
 ``meta-raspberrypi`` and ``meta-intel``). Each of these layers is a
 repository unto itself and clicking on the layer name displays two URLs
 from which you can clone the layer's repository to your local system.
-Here is an example that clones the Raspberry Pi BSP layer: ::
+Here is an example that clones the Raspberry Pi BSP layer::
 
    $ git clone git://git.yoctoproject.org/meta-raspberrypi
 
@@ -84,7 +84,7 @@ established after you run the OpenEmbedded build environment setup
 script (i.e. :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``).
 Adding the root directory allows the :term:`OpenEmbedded Build System`
 to recognize the BSP
-layer and from it build an image. Here is an example: ::
+layer and from it build an image. Here is an example::
 
    BBLAYERS ?= " \
       /usr/local/src/yocto/meta \
@@ -113,7 +113,7 @@ this type of layer is OpenEmbedded's
 `meta-openembedded <https://github.com/openembedded/meta-openembedded>`__
 layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers.
 In cases like this, you need to include the names of the actual layers
-you want to work with, such as: ::
+you want to work with, such as::
 
    BBLAYERS ?= " \
      /usr/local/src/yocto/meta \
@@ -193,7 +193,7 @@ section.
 
    #. *Check Out the Proper Branch:* The branch you check out for
       ``meta-intel`` must match the same branch you are using for the
-      Yocto Project release (e.g. ``&DISTRO_NAME_NO_CAP;``): ::
+      Yocto Project release (e.g. ``&DISTRO_NAME_NO_CAP;``)::
 
          $ cd meta-intel
          $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP;
@@ -216,7 +216,7 @@ section.
    The process is identical to the process used for the ``meta-intel``
    layer except for the layer's name. For example, if you determine that
    your hardware most closely matches the ``meta-raspberrypi``, clone
-   that layer: ::
+   that layer::
 
       $ git clone git://git.yoctoproject.org/meta-raspberrypi
       Cloning into 'meta-raspberrypi'...
@@ -451,7 +451,7 @@ The following sections describe each part of the proposed BSP format.
 License Files
 -------------
 
-You can find these files in the BSP Layer at: ::
+You can find these files in the BSP Layer at::
 
    meta-bsp_root_name/bsp_license_file
 
@@ -469,7 +469,7 @@ section in the Yocto Project Development Tasks Manual.
 README File
 -----------
 
-You can find this file in the BSP Layer at: ::
+You can find this file in the BSP Layer at::
 
    meta-bsp_root_name/README
 
@@ -484,7 +484,7 @@ name of the BSP maintainer with his or her contact information.
 README.sources File
 -------------------
 
-You can find this file in the BSP Layer at: ::
+You can find this file in the BSP Layer at::
 
    meta-bsp_root_name/README.sources
 
@@ -503,7 +503,7 @@ used to generate the images that ship with the BSP.
 Pre-built User Binaries
 -----------------------
 
-You can find these files in the BSP Layer at: ::
+You can find these files in the BSP Layer at::
 
    meta-bsp_root_name/binary/bootable_images
 
@@ -526,7 +526,7 @@ information on the Metadata.
 Layer Configuration File
 ------------------------
 
-You can find this file in the BSP Layer at: ::
+You can find this file in the BSP Layer at::
 
    meta-bsp_root_name/conf/layer.conf
 
@@ -550,7 +550,7 @@ template). ::
    LAYERDEPENDS_bsp = "intel"
 
 To illustrate the string substitutions, here are the corresponding
-statements from the Raspberry Pi ``conf/layer.conf`` file: ::
+statements from the Raspberry Pi ``conf/layer.conf`` file::
 
    # We have a conf and classes directory, append to BBPATH
    BBPATH .= ":${LAYERDIR}"
@@ -576,7 +576,7 @@ recognize the BSP.
 Hardware Configuration Options
 ------------------------------
 
-You can find these files in the BSP Layer at: ::
+You can find these files in the BSP Layer at::
 
    meta-bsp_root_name/conf/machine/*.conf
 
@@ -607,14 +607,14 @@ For example, many ``tune-*`` files (e.g. ``tune-arm1136jf-s.inc``,
 
 To use an include file, you simply include them in the machine
 configuration file. For example, the Raspberry Pi BSP
-``raspberrypi3.conf`` contains the following statement: ::
+``raspberrypi3.conf`` contains the following statement::
 
    include conf/machine/include/rpi-base.inc
 
 Miscellaneous BSP-Specific Recipe Files
 ---------------------------------------
 
-You can find these files in the BSP Layer at: ::
+You can find these files in the BSP Layer at::
 
    meta-bsp_root_name/recipes-bsp/*
 
@@ -624,7 +624,7 @@ Raspberry Pi BSP, there is the ``formfactor_0.0.bbappend`` file, which
 is an append file used to augment the recipe that starts the build.
 Furthermore, there are machine-specific settings used during the build
 that are defined by the ``machconfig`` file further down in the
-directory. Here is the ``machconfig`` file for the Raspberry Pi BSP: ::
+directory. Here is the ``machconfig`` file for the Raspberry Pi BSP::
 
    HAVE_TOUCHSCREEN=0
    HAVE_KEYBOARD=1
@@ -644,7 +644,7 @@ directory. Here is the ``machconfig`` file for the Raspberry Pi BSP: ::
 Display Support Files
 ---------------------
 
-You can find these files in the BSP Layer at: ::
+You can find these files in the BSP Layer at::
 
    meta-bsp_root_name/recipes-graphics/*
 
@@ -655,7 +655,7 @@ to support a display are kept here.
 Linux Kernel Configuration
 --------------------------
 
-You can find these files in the BSP Layer at: ::
+You can find these files in the BSP Layer at::
 
    meta-bsp_root_name/recipes-kernel/linux/linux*.bbappend
    meta-bsp_root_name/recipes-kernel/linux/*.bb
@@ -678,7 +678,7 @@ Suppose you are using the ``linux-yocto_4.4.bb`` recipe to build the
 kernel. In other words, you have selected the kernel in your
 ``"bsp_root_name".conf`` file by adding
 :term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION`
-statements as follows: ::
+statements as follows::
 
    PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
    PREFERRED_VERSION_linux-yocto ?= "4.4%"
@@ -698,7 +698,7 @@ in the Yocto Project Linux Kernel Development Manual.
 
 An alternate scenario is when you create your own kernel recipe for the
 BSP. A good example of this is the Raspberry Pi BSP. If you examine the
-``recipes-kernel/linux`` directory you see the following: ::
+``recipes-kernel/linux`` directory you see the following::
 
    linux-raspberrypi-dev.bb
    linux-raspberrypi.inc
@@ -1042,7 +1042,7 @@ BSP-specific configuration file named ``interfaces`` to the
 also supports several other machines:
 
 #. Edit the ``init-ifupdown_1.0.bbappend`` file so that it contains the
-   following: ::
+   following::
 
       FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
 
@@ -1050,14 +1050,14 @@ also supports several other machines:
    directory.
 
 #. Create and place the new ``interfaces`` configuration file in the
-   BSP's layer here: ::
+   BSP's layer here::
 
       meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces
 
    .. note::
 
       If the ``meta-xyz`` layer did not support multiple machines, you would place
-      the interfaces configuration file in the layer here: ::
+      the interfaces configuration file in the layer here::
 
          meta-xyz/recipes-core/init-ifupdown/files/interfaces
 
@@ -1210,7 +1210,7 @@ BSP Layer Configuration Example
 -------------------------------
 
 The layer's ``conf`` directory contains the ``layer.conf`` configuration
-file. In this example, the ``conf/layer.conf`` is the following: ::
+file. In this example, the ``conf/layer.conf`` is the following::
 
    # We have a conf and classes directory, add to BBPATH
    BBPATH .= ":${LAYERDIR}"
@@ -1242,7 +1242,7 @@ configuration file is what makes a layer a BSP layer as compared to a
 general or kernel layer.
 
 One or more machine configuration files exist in the
-``bsp_layer/conf/machine/`` directory of the layer: ::
+``bsp_layer/conf/machine/`` directory of the layer::
 
    bsp_layer/conf/machine/machine1\.conf
    bsp_layer/conf/machine/machine2\.conf
@@ -1252,7 +1252,7 @@ One or more machine configuration files exist in the
 For example, the machine configuration file for the `BeagleBone and
 BeagleBone Black development boards <https://beagleboard.org/bone>`__ is
 located in the layer ``poky/meta-yocto-bsp/conf/machine`` and is named
-``beaglebone-yocto.conf``: ::
+``beaglebone-yocto.conf``::
 
    #@TYPE: Machine
    #@NAME: Beaglebone-yocto machine
@@ -1447,7 +1447,7 @@ BSP Kernel Recipe Example
 -------------------------
 
 The kernel recipe used to build the kernel image for the BeagleBone
-device was established in the machine configuration: ::
+device was established in the machine configuration::
 
    PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
    PREFERRED_VERSION_linux-yocto ?= "5.0%"
@@ -1458,7 +1458,7 @@ metadata used to build the kernel. In this case, a kernel append file
 kernel recipe (i.e. ``linux-yocto_5.0.bb``), which is located in
 :yocto_git:`/poky/tree/meta/recipes-kernel/linux`.
 
-Following is the contents of the append file: ::
+Following is the contents of the append file::
 
    KBRANCH_genericx86 = "v5.0/standard/base"
    KBRANCH_genericx86-64 = "v5.0/standard/base"

documentation/dev-manual/qemu.rst

@@ -55,16 +55,14 @@ available. Follow these general steps to run 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`):
-      ::
+      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:
-      ::
+      the initialization script from the default ``poky_sdk`` directory::
 
          . poky_sdk/environment-setup-core2-64-poky-linux
 
@@ -86,8 +84,7 @@ available. Follow these general steps to run QEMU:
    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:
-   ::
+4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows::
 
       $ runqemu [option ] [...]
 
@@ -222,18 +219,15 @@ using an NFS server.
    Should you need to start, stop, or restart the NFS share, you can use
    the following commands:
 
-   -  The following command starts the NFS share:
-      ::
+   -  To start the NFS share::
 
          runqemu-export-rootfs start file-system-location
 
-   -  The following command stops the NFS share:
-      ::
+   -  To stop the NFS share::
 
          runqemu-export-rootfs stop file-system-location
 
-   -  The following command restarts the NFS share:
-      ::
+   -  To restart the NFS share::
 
          runqemu-export-rootfs restart file-system-location
 
@@ -306,15 +300,14 @@ present, the toolchain is also automatically used.
       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>`__"
+      See the
+      ":ref:`dev-manual/qemu:running under a network file system (nfs) server`"
       section for more information.
 
 QEMU Command-Line Syntax
 ========================
 
-The basic ``runqemu`` command syntax is as follows:
-::
+The basic ``runqemu`` command syntax is as follows::
 
    $ runqemu [option ] [...]
 
@@ -325,8 +318,7 @@ 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:
-::
+Following is the command-line help output for the ``runqemu`` command::
 
    $ runqemu --help
 
@@ -452,7 +444,7 @@ command line:
    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.
+   -  ``kvm`` option conditions defined above must be met.
 
    -  Your build host has to have virtio net device, which are
       ``/dev/vhost-net``.

documentation/dev-manual/start.rst

@@ -230,8 +230,8 @@ particular working environment and set of practices.
     -  Separate the project's Metadata and code by using separate Git
        repositories. See the ":ref:`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>`__"
+       information on these repositories. See the
+       ":ref:`dev-manual/start:locating yocto project source files`"
        section for information on how to set up local Git repositories
        for related upstream Yocto Project Git repositories.
 
@@ -314,13 +314,13 @@ Project Build Host:
    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
+   -  Git &MIN_GIT_VERSION; or greater
 
-   -  tar 1.28 or greater
+   -  tar &MIN_TAR_VERSION; or greater
 
-   -  Python 3.5.0 or greater.
+   -  Python &MIN_PYTHON_VERSION; or greater.
 
-   -  gcc 5.0 or greater.
+   -  gcc &MIN_GCC_VERSION; 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
@@ -387,36 +387,28 @@ as your Yocto Project build host:
    software. Follow the instructions for your specific machine and the
    type of the software you need to install:
 
-   -  Install `Docker CE for
+   -  Install `Docker Desktop on
       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
+   -  Install `Docker Desktop on
       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/>`__
+   -  Install `Docker Engine on
+      CentOS <https://docs.docker.com/engine/install/centos/>`__
       for Linux build hosts running the CentOS distribution.
 
-   -  Install `Docker CE for
-      Debian <https://docs.docker.com/install/linux/docker-ce/debian/>`__
+   -  Install `Docker Engine on
+      Debian <https://docs.docker.com/engine/install/debian/>`__
       for Linux build hosts running the Debian distribution.
 
-   -  Install `Docker CE for
-      Fedora <https://docs.docker.com/install/linux/docker-ce/fedora/>`__
+   -  Install `Docker Engine for
+      Fedora <https://docs.docker.com/engine/install/fedora/>`__
       for Linux build hosts running the Fedora distribution.
 
-   -  Install `Docker CE for
-      Ubuntu <https://docs.docker.com/install/linux/docker-ce/ubuntu/>`__
+   -  Install `Docker Engine for
+      Ubuntu <https://docs.docker.com/engine/install/ubuntu/>`__
       for Linux build hosts running the Ubuntu distribution.
 
 5. *Optionally Orient Yourself With Docker:* If you are unfamiliar with
@@ -486,8 +478,7 @@ your Yocto Project build host:
    distribution.
 
 3. *Check your Linux distribution is using WSLv2:* Open a Windows
-   PowerShell and run:
-   ::
+   PowerShell and run::
 
       C:\WINDOWS\system32> wsl -l -v
       NAME    STATE   VERSION
@@ -514,8 +505,7 @@ your Yocto Project build host:
 
    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:
-      ::
+      Powershell as Administrator and run::
 
          C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName
          PackageFamilyName
@@ -525,8 +515,7 @@ your Yocto Project build host:
 
       You should now
       replace the PackageFamilyName and your user on the following path
-      to find your VHDX file:
-      ::
+      to find your VHDX file::
 
           ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
           Mode                 LastWriteTime         Length Name
@@ -536,8 +525,7 @@ your Yocto Project build host:
       ``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:
-      ::
+      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
@@ -655,8 +643,7 @@ 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.
+described in the ":ref:`dev-manual/start:accessing index of releases`" section.
 
 .. note::
 
@@ -742,8 +729,7 @@ Follow these steps to create a local version of the upstream
 
 2. *Clone the Repository:* The following example command clones the
    ``poky`` repository and uses the default name "poky" for your local
-   repository:
-   ::
+   repository::
 
       $ git clone git://git.yoctoproject.org/poky
       Cloning into 'poky'...
@@ -759,14 +745,13 @@ Follow these steps to create a local version of the upstream
    "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.
+   based on a tag name, see the
+   ":ref:`dev-manual/start:checking out by branch in poky`" and
+   ":ref:`dev-manual/start:checking 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:
-   ::
+   exists on your system and by default, it is checked out::
 
       $ cd poky
       $ git status
@@ -827,8 +812,7 @@ and then specifically check out that development branch.
 
 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:
-   ::
+   &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.
@@ -840,8 +824,7 @@ and then specifically check out that development 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:
-   ::
+   that is currently checked out for work::
 
       $ git branch
         master
@@ -868,14 +851,12 @@ similar to checking out by branch name except you use tag names.
    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:
-   ::
+   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:
-   ::
+3. *List the Tag Names:* You can list the tag names now::
 
       $ git tag
       1.1_M1.final

documentation/index.rst

@@ -34,7 +34,7 @@ Welcome to the Yocto Project Documentation
    Application Development and the Extensible SDK (eSDK) <sdk-manual/index>
    Toaster Manual <toaster-manual/index>
    Test Environment Manual <test-manual/index>
-   Bitbake User Manual <https://docs.yoctoproject.org/bitbake>
+   bitbake
 
 .. toctree::
    :maxdepth: 1

documentation/kernel-dev/advanced.rst

@@ -56,8 +56,8 @@ 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.
+however, these two variables can hold the same value. See the
+":ref:`kernel-dev/advanced: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
@@ -67,8 +67,7 @@ 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:
-   ::
+   with a machine override as shown here from the ``meta-yocto-bsp`` layer::
 
            KBRANCH_edgerouter = "standard/edgerouter"
 
@@ -87,7 +86,7 @@ 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>`__"
+"preempt-rt" kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
 section for more information on kernel types.
 
 During the build, the kern-tools search for the BSP description file
@@ -106,15 +105,13 @@ You can use the
 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:
-::
+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:
-::
+specify::
 
    KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc"
 
@@ -123,8 +120,8 @@ 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.
+information, see the ":ref:`kernel-dev/advanced:kernel metadata syntax`"
+section.
 
 Kernel Metadata Syntax
 ======================
@@ -148,7 +145,7 @@ 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
+kernel types. :ref:`kernel-dev/advanced:kernel types` define general kernel
 features and policy to be reused in the BSPs.
 
 BSPs define hardware-specific features and aggregate them with kernel
@@ -157,8 +154,7 @@ 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:
-::
+following Metadata file hierarchy is recommended::
 
    base/
       bsp/
@@ -167,10 +163,9 @@ following Metadata file hierarchy is recommended:
       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.
+The ``bsp`` directory contains the :ref:`kernel-dev/advanced: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:
@@ -198,11 +193,12 @@ 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>`__,
+you are creating Metadata in
+:ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`,
 or the top level of
 :yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>`
-if you are creating `Metadata outside of the
-recipe-space <#metadata-outside-the-recipe-space>`__.
+if you are creating
+:ref:`kernel-dev/advanced:metadata outside the recipe-space`.
 
 .. [1]
    ``scc`` stands for Series Configuration Control, but the naming has
@@ -222,8 +218,7 @@ 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:
-::
+``yocto-kernel-cache`` Git repository::
 
    cfg/smp.scc:
       define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
@@ -265,8 +260,7 @@ non-hardware fragment.
 
 As described in the
 ":ref:`kernel-dev/common:validating configuration`" section, you can
-use the following BitBake command to audit your configuration:
-::
+use the following BitBake command to audit your configuration::
 
    $ bitbake linux-yocto -c kernel_configcheck -f
 
@@ -287,8 +281,7 @@ 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:
-::
+``modpost-mask-trivial-warnings.patch`` file::
 
    patches/build/build.scc:
       patch arm-serialize-build-targets.patch
@@ -334,8 +327,7 @@ 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:
-::
+example, consider the following generic listing::
 
    features/myfeature.scc
       define KFEATURE_DESCRIPTION "Enable myfeature"
@@ -353,9 +345,9 @@ as how an additional feature description file is included with the
 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.
+Linux kernel recipe. See the
+":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier
+in the manual.
 
 Kernel Types
 ------------
@@ -364,22 +356,20 @@ 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
+in the ":ref:`kernel-dev/advanced: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:bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` directive
 includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
-which has the following statement that defines the default kernel type:
-::
+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:
-::
+type as follows::
 
    LINUX_KERNEL_TYPE = "preempt-rt"
 
@@ -412,8 +402,7 @@ for Linux Yocto kernels:
 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:
-::
+``yocto-kernel-cache`` Git repository::
 
    # Include this kernel type fragment to get the standard features and
    # configuration values.
@@ -482,15 +471,13 @@ 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:
-::
+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:
-::
+Yocto Project::
 
    beaglebone-standard.scc
    beaglebone-preempt-rt.scc
@@ -498,8 +485,7 @@ Yocto Project:
 Each file uses the root name (i.e "beaglebone") BSP name followed by the
 kernel type.
 
-Examine the ``beaglebone-standard.scc`` file:
-::
+Examine the ``beaglebone-standard.scc`` file::
 
    define KMACHINE beaglebone
    define KTYPE standard
@@ -533,24 +519,21 @@ 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:
-::
+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
+policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more
 information.
 
 To aggregate common configurations and features specific to the kernel
-for `mybsp`, use the following:
-::
+for `mybsp`, use the following::
 
    include mybsp.scc
 
-You can see that in the BeagleBone example with the following:
-::
+You can see that in the BeagleBone example with the following::
 
    include beaglebone.scc
 
@@ -558,15 +541,13 @@ For information on how to break a complete ``.config`` file into the various
 configuration fragments, see the ":ref:`kernel-dev/common:creating configuration 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:
-::
+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:
-::
+("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file::
 
    define KMACHINE mti-malta32-le
    define KMACHINE qemumipsel
@@ -623,8 +604,7 @@ 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``):
-::
+``minnow-standard.scc``)::
 
    define KMACHINE minnow
    define KTYPE standard
@@ -656,8 +636,7 @@ 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``):
-::
+``minnow-tiny.scc``)::
 
    define KMACHINE minnow
    define KTYPE tiny
@@ -720,8 +699,7 @@ See the ":ref:`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:
-::
+in recipe-space within a BSP layer::
 
    meta-my_bsp_layer/
    `-- recipes-kernel
@@ -744,8 +722,7 @@ value when changing the content of files not explicitly listed in the
 
 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:
-::
+form from your kernel append file::
 
    SRC_URI_append_myplatform = " \
        file://myplatform;type=kmeta;destsuffix=myplatform \
@@ -759,8 +736,7 @@ 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:
-::
+``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}"
@@ -825,11 +801,11 @@ 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.
+described in the ":ref:`kernel-dev/advanced: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.
+in the ":ref:`kernel-dev/advanced:patches`" and
+":ref:`kernel-dev/advanced:bsp descriptions`" sections.
 
 Machine Branches
 ----------------
@@ -844,14 +820,12 @@ 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:
-::
+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:
-::
+description::
 
    mybsp.scc:
       define KMACHINE mybsp
@@ -865,15 +839,13 @@ description:
 
 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:
-::
+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:
-::
+might look like this::
 
    mydir/base
    mydir/standard/base
@@ -905,8 +877,7 @@ 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:
-::
+after any ``branch`` commands::
 
    mybsp.scc:
       define KMACHINE mybsp

documentation/kernel-dev/common.rst

@@ -54,8 +54,7 @@ section:
 
 1. *Initialize the BitBake Environment:* Before building an extensible
    SDK, you need to initialize the BitBake build environment by sourcing
-   the build environment script (i.e. :ref:`structure-core-script`):
-   ::
+   the build environment script (i.e. :ref:`structure-core-script`)::
 
       $ cd poky
       $ source oe-init-build-env
@@ -83,16 +82,14 @@ section:
 
    In this example we wish to build for qemux86 so we must set the
    ``MACHINE`` variable to "qemux86" and also add the "kernel-modules".
-   As described we do this by appending to ``conf/local.conf``:
-   ::
+   As described we do this by appending to ``conf/local.conf``::
 
       MACHINE = "qemux86"
       MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
 
 3. *Create a Layer for Patches:* You need to create a layer to hold
    patches created for the kernel image. You can use the
-   ``bitbake-layers create-layer`` command as follows:
-   ::
+   ``bitbake-layers create-layer`` command as follows::
 
       $ cd poky/build
       $ bitbake-layers create-layer ../../meta-mylayer
@@ -116,8 +113,7 @@ section:
 4. *Inform the BitBake Build Environment About Your Layer:* As directed
    when you created your layer, you need to add the layer to the
    :term:`BBLAYERS` variable in the
-   ``bblayers.conf`` file as follows:
-   ::
+   ``bblayers.conf`` file as follows::
 
       $ cd poky/build
       $ bitbake-layers add-layer ../../meta-mylayer
@@ -125,16 +121,14 @@ section:
       $
 
 5. *Build the Extensible SDK:* Use BitBake to build the extensible SDK
-   specifically for use with images to be run using QEMU:
-   ::
+   specifically for use with images to be run using QEMU::
 
       $ cd poky/build
       $ bitbake core-image-minimal -c populate_sdk_ext
 
    Once
    the build finishes, you can find the SDK installer file (i.e.
-   ``*.sh`` file) in the following directory:
-   ::
+   ``*.sh`` file) in the following directory::
 
       poky/build/tmp/deploy/sdk
 
@@ -143,8 +137,7 @@ section:
 
 6. *Install the Extensible SDK:* Use the following command to install
    the SDK. For this example, install the SDK in the default
-   ``poky_sdk`` directory:
-   ::
+   ``poky_sdk`` directory::
 
       $ cd poky/build/tmp/deploy/sdk
       $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh
@@ -172,8 +165,7 @@ section:
    BitBake shell used to build the installer.
 
    After opening a new shell, run the SDK environment setup script as
-   directed by the output from installing the SDK:
-   ::
+   directed by the output from installing the SDK::
 
       $ source poky_sdk/environment-setup-i586-poky-linux
       "SDK environment now set up; additionally you may now run devtool to perform development tasks.
@@ -186,8 +178,7 @@ section:
 
 8. *Build the Clean Image:* The final step in preparing to work on the
    kernel is to build an initial image using ``devtool`` in the new
-   terminal you just set up and initialized for SDK work:
-   ::
+   terminal you just set up and initialized for SDK work::
 
       $ devtool build-image
       Parsing recipes: 100% |##########################################| Time: 0:00:05
@@ -269,16 +260,14 @@ section:
 
    In this example we wish to build for qemux86 so we must set the
    ``MACHINE`` variable to "qemux86" and also add the "kernel-modules".
-   As described we do this by appending to ``conf/local.conf``:
-   ::
+   As described we do this by appending to ``conf/local.conf``::
 
       MACHINE = "qemux86"
       MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
 
 3. *Create a Layer for Patches:* You need to create a layer to hold
    patches created for the kernel image. You can use the
-   ``bitbake-layers create-layer`` command as follows:
-   ::
+   ``bitbake-layers create-layer`` command as follows::
 
       $ cd poky/build
       $ bitbake-layers create-layer ../../meta-mylayer
@@ -301,8 +290,7 @@ section:
 4. *Inform the BitBake Build Environment About Your Layer:* As directed
    when you created your layer, you need to add the layer to the
    :term:`BBLAYERS` variable in the
-   ``bblayers.conf`` file as follows:
-   ::
+   ``bblayers.conf`` file as follows::
 
       $ cd poky/build
       $ bitbake-layers add-layer ../../meta-mylayer
@@ -350,8 +338,7 @@ section:
    the ``yocto-4.12`` branch.
 
    The following commands show how to create a local copy of the
-   ``yocto-kernel-cache`` and be in the ``yocto-4.12`` branch:
-   ::
+   ``yocto-kernel-cache`` and switch to the ``yocto-4.12`` branch::
 
       $ cd ~
       $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12
@@ -365,8 +352,7 @@ section:
 
 At this point, you are ready to start making modifications to the kernel
 using traditional kernel development steps. For a continued example, see
-the "`Using Traditional Kernel Development to Patch the
-Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__"
+the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
 section.
 
 Creating and Preparing a Layer
@@ -395,8 +381,7 @@ following section describes how to create a layer without the aid of
 tools. These steps assume creation of a layer named ``mylayer`` in your
 home directory:
 
-1. *Create Structure*: Create the layer's structure:
-   ::
+1. *Create Structure*: Create the layer's structure::
 
       $ mkdir meta-mylayer
       $ mkdir meta-mylayer/conf
@@ -410,8 +395,7 @@ home directory:
 
 2. *Create the Layer Configuration File*: Move to the
    ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as
-   follows:
-   ::
+   follows::
 
       # We have a conf and classes directory, add to BBPATH
       BBPATH .= ":${LAYERDIR}"
@@ -430,8 +414,7 @@ home directory:
    ``meta-mylayer/recipes-kernel/linux`` directory and create the
    kernel's append file. This example uses the ``linux-yocto-4.12``
    kernel. Thus, the name of the append file is
-   ``linux-yocto_4.12.bbappend``:
-   ::
+   ``linux-yocto_4.12.bbappend``::
 
       FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
 
@@ -463,8 +446,8 @@ Modifying an existing recipe can consist of the following:
 - :ref:`kernel-dev/common:changing the configuration`
 
 Before modifying an existing recipe, be sure that you have created a
-minimal, custom layer from which you can work. See the "`Creating and
-Preparing a Layer <#creating-and-preparing-a-layer>`__" section for
+minimal, custom layer from which you can work. See the
+":ref:`kernel-dev/common:creating and preparing a layer`" section for
 information.
 
 Creating the Append File
@@ -484,8 +467,7 @@ The append file should initially extend the
 :term:`FILESPATH` search path by
 prepending the directory that contains your files to the
 :term:`FILESEXTRAPATHS`
-variable as follows:
-::
+variable as follows::
 
    FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
 
@@ -493,8 +475,7 @@ The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``
 expands to "linux-yocto" in the current directory for this example. If
 you add any new files that modify the kernel recipe and you have
 extended ``FILESPATH`` as described above, you must place the files in
-your layer in the following area:
-::
+your layer in the following area::
 
    your-layer/recipes-kernel/linux/linux-yocto/
 
@@ -510,7 +491,7 @@ As an example, consider the following append file used by the BSPs in
 
    meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend
 
-The following listing shows the file. Be aware that the actual commit ID
+Here are the contents of this file. Be aware that the actual commit ID
 strings in this example listing might be different than the actual
 strings in the file from the ``meta-yocto-bsp`` layer upstream.
 ::
@@ -583,8 +564,7 @@ To group related configurations into multiple files, you perform a
 similar procedure. Here is an example that groups separate
 configurations specifically for Ethernet and graphics into their own
 files and adds the configurations by using a ``SRC_URI`` statement like
-the following in your append file:
-::
+the following in your append file::
 
    SRC_URI += "file://myconfig.cfg \
                file://eth.cfg \
@@ -609,8 +589,8 @@ recipe is processed.
 
    In general, however, the Yocto Project maintainers take care of
    moving the ``SRC_URI``-specified configuration options to the
-   kernel's ``meta`` branch. Not only is it easier for BSP developers to
-   not have to worry about putting those configurations in the branch,
+   kernel's ``meta`` branch. Not only is it easier for BSP developers
+   not to have to put those configurations in the branch,
    but having the maintainers do it allows them to apply 'global'
    knowledge about the kinds of common configuration options multiple
    BSPs in the tree are typically using. This allows for promotion of
@@ -628,8 +608,7 @@ reference them in :term:`SRC_URI`
 statements.
 
 For example, you can apply a three-patch series by adding the following
-lines to your linux-yocto ``.bbappend`` file in your layer:
-::
+lines to your linux-yocto ``.bbappend`` file in your layer::
 
    SRC_URI += "file://0001-first-change.patch"
    SRC_URI += "file://0002-second-change.patch"
@@ -659,8 +638,7 @@ If you have a complete, working Linux kernel ``.config`` file you want
 to use for the configuration, as before, copy that file to the
 appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux``
 directory, and rename the copied file to "defconfig". Then, add the
-following lines to the linux-yocto ``.bbappend`` file in your layer:
-::
+following lines to the linux-yocto ``.bbappend`` file in your layer::
 
    FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
    SRC_URI += "file://defconfig"
@@ -672,6 +650,15 @@ extends the :term:`FILESPATH`
 variable (search directories) to include the ``${PN}`` directory you
 created to hold the configuration changes.
 
+You can also use a regular ``defconfig`` file, as generated by the
+:ref:`ref-tasks-savedefconfig`
+task instead of a complete ``.config`` file. This only specifies the
+non-default configuration values.  You need to additionally set
+:term:`KCONFIG_MODE`
+in the linux-yocto ``.bbappend`` file in your layer::
+
+   KCONFIG_MODE = "alldefconfig"
+
 .. note::
 
    The build system applies the configurations from the ``defconfig``
@@ -686,8 +673,7 @@ Generally speaking, the preferred approach is to determine the
 incremental change you want to make and add that as a configuration
 fragment. For example, if you want to add support for a basic serial
 console, create a file named ``8250.cfg`` in the ``${PN}`` directory
-with the following content (without indentation):
-::
+with the following content (without indentation)::
 
    CONFIG_SERIAL_8250=y
    CONFIG_SERIAL_8250_CONSOLE=y
@@ -699,8 +685,7 @@ with the following content (without indentation):
 
 Next, include this
 configuration fragment and extend the ``FILESPATH`` variable in your
-``.bbappend`` file:
-::
+``.bbappend`` file::
 
    FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
    SRC_URI += "file://8250.cfg"
@@ -710,7 +695,7 @@ Linux kernel, BitBake detects the change in the recipe and fetches and
 applies the new configuration before building the kernel.
 
 For a detailed example showing how to configure the kernel, see the
-"`Configuring the Kernel <#configuring-the-kernel>`__" section.
+":ref:`kernel-dev/common:configuring the kernel`" section.
 
 Using an "In-Tree"  ``defconfig`` File
 --------------------------------------
@@ -719,8 +704,7 @@ It might be desirable to have kernel configuration fragment support
 through a ``defconfig`` file that is pulled from the kernel source tree
 for the configured machine. By default, the OpenEmbedded build system
 looks for ``defconfig`` files in the layer used for Metadata, which is
-"out-of-tree", and then configures them using the following:
-::
+"out-of-tree", and then configures them using the following::
 
    SRC_URI += "file://defconfig"
 
@@ -733,16 +717,14 @@ append files, you can direct the OpenEmbedded build system to use a
 ``defconfig`` file that is "in-tree".
 
 To specify an "in-tree" ``defconfig`` file, use the following statement
-form:
-::
+form::
 
    KBUILD_DEFCONFIG_KMACHINE ?= "defconfig_file"
 
 Here is an example
 that assigns the ``KBUILD_DEFCONFIG`` variable based on "raspberrypi2"
 and provides the path to the "in-tree" ``defconfig`` file to be used for
-a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset:
-::
+a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset::
 
    KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig"
 
@@ -793,8 +775,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
       ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
       section for more information.
 
-   Use the following ``devtool`` command to check out the code:
-   ::
+   Use the following ``devtool`` command to check out the code::
 
       $ devtool modify linux-yocto
 
@@ -820,14 +801,12 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
       noted where you can find the source files (e.g.
       ``poky_sdk/workspace/sources/linux-yocto``). Change to where the
       kernel source code is before making your edits to the
-      ``calibrate.c`` file:
-      ::
+      ``calibrate.c`` file::
 
          $ cd poky_sdk/workspace/sources/linux-yocto
 
    2. *Edit the source file*: Edit the ``init/calibrate.c`` file to have
-      the following changes:
-      ::
+      the following changes::
 
          void calibrate_delay(void)
          {
@@ -847,8 +826,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
                    .
 
 3. *Build the Updated Kernel Source:* To build the updated kernel
-   source, use ``devtool``:
-   ::
+   source, use ``devtool``::
 
       $ devtool build linux-yocto
 
@@ -873,8 +851,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
    using QEMU to verify your changes:
 
    1. *Boot the image*: Boot the modified image in the QEMU emulator
-      using this command:
-      ::
+      using this command::
 
          $ runqemu qemux86
 
@@ -892,8 +869,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
 
 6. *Stage and commit your changes*: Within your eSDK terminal, change
    your working directory to where you modified the ``calibrate.c`` file
-   and use these Git commands to stage and commit your changes:
-   ::
+   and use these Git commands to stage and commit your changes::
 
       $ cd poky_sdk/workspace/sources/linux-yocto
       $ git status
@@ -922,8 +898,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
    image that includes your kernel patches. Execute the following
    command from your
    :term:`Build Directory` in the terminal
-   set up to run BitBake:
-   ::
+   set up to run BitBake::
 
       $ cd poky/build
       $ bitbake core-image-minimal
@@ -954,28 +929,25 @@ emulator console output at boot time through ``printk`` statements in
 the kernel's ``calibrate.c`` source code file. Applying the patch and
 booting the modified image causes the added messages to appear on the
 emulator's console. The example is a continuation of the setup procedure
-found in the "`Getting Ready for Traditional Kernel
-Development <#getting-ready-for-traditional-kernel-development>`__"
+found in the
+":ref:`kernel-dev/common:getting ready for traditional kernel development`"
 Section.
 
 1. *Edit the Source Files* Prior to this step, you should have used Git
    to create a local copy of the repository for your kernel. Assuming
-   you created the repository as directed in the "`Getting Ready for
-   Traditional Kernel
-   Development <#getting-ready-for-traditional-kernel-development>`__"
+   you created the repository as directed in the
+   ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
    section, use the following commands to edit the ``calibrate.c`` file:
 
    1. *Change the working directory*: You need to locate the source
       files in the local copy of the kernel Git repository. Change to
       where the kernel source code is before making your edits to the
-      ``calibrate.c`` file:
-      ::
+      ``calibrate.c`` file::
 
          $ cd ~/linux-yocto-4.12/init
 
    2. *Edit the source file*: Edit the ``calibrate.c`` file to have the
-      following changes:
-      ::
+      following changes::
 
          void calibrate_delay(void)
          {
@@ -995,8 +967,7 @@ Section.
                    .
 
 2. *Stage and Commit Your Changes:* Use standard Git commands to stage
-   and commit the changes you just made:
-   ::
+   and commit the changes you just made::
 
       $ git add calibrate.c
       $ git commit -m "calibrate.c - Added some printk statements"
@@ -1011,13 +982,11 @@ Section.
    updated kernel source files. Add
    :term:`SRC_URI` and
    :term:`SRCREV` statements similar
-   to the following to your ``local.conf``:
-   ::
+   to the following to your ``local.conf``::
 
       $ cd poky/build/conf
 
-   Add the following to the ``local.conf``:
-   ::
+   Add the following to the ``local.conf``::
 
       SRC_URI_pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \
                                 git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
@@ -1033,16 +1002,14 @@ Section.
 
 4. *Build the Image:* With the source modified, your changes staged and
    committed, and the ``local.conf`` file pointing to the kernel files,
-   you can now use BitBake to build the image:
-   ::
+   you can now use BitBake to build the image::
 
       $ cd poky/build
       $ bitbake core-image-minimal
 
 5. *Boot the image*: Boot the modified image in the QEMU emulator using
    this command. When prompted to login to the QEMU console, use "root"
-   with no password:
-   ::
+   with no password::
 
       $ cd poky/build
       $ runqemu qemux86
@@ -1061,8 +1028,7 @@ Section.
 
 7. *Generate the Patch File:* Once you are sure that your patch works
    correctly, you can generate a ``*.patch`` file in the kernel source
-   repository:
-   ::
+   repository::
 
       $ cd ~/linux-yocto-4.12/init
       $ git format-patch -1
@@ -1075,8 +1041,7 @@ Section.
    ``meta-mylayer``. When the layer was created using the
    ``yocto-create`` script, no additional hierarchy was created to
    support patches. Before moving the patch file, you need to add
-   additional structure to your layer using the following commands:
-   ::
+   additional structure to your layer using the following commands::
 
       $ cd ~/meta-mylayer
       $ mkdir recipes-kernel
@@ -1085,8 +1050,7 @@ Section.
 
    Once you have created this
    hierarchy in your layer, you can move the patch file using the
-   following command:
-   ::
+   following command::
 
       $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto
 
@@ -1095,8 +1059,7 @@ Section.
    the OpenEmbedded build system to find the patch. The append file
    needs to be in your layer's ``recipes-kernel/linux`` directory and it
    must be named ``linux-yocto_4.12.bbappend`` and have the following
-   contents:
-   ::
+   contents::
 
       FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
       SRC_URI_append = "file://0001-calibrate.c-Added-some-printk-statements.patch"
@@ -1104,9 +1067,9 @@ Section.
    The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
    enable the OpenEmbedded build system to find the patch file.
 
-   For more information on append files and patches, see the "`Creating
-   the Append File <#creating-the-append-file>`__" and "`Applying
-   Patches <#applying-patches>`__" sections. You can also see the
+   For more information on append files and patches, see the
+   ":ref:`kernel-dev/common:creating the append file`" and
+   ":ref:`kernel-dev/common:applying patches`" sections. You can also see the
    ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`"
    section in the Yocto Project Development Tasks Manual.
 
@@ -1115,8 +1078,7 @@ Section.
       To build ``core-image-minimal`` again and see the effects of your patch,
       you can essentially eliminate the temporary source files saved in
       ``poky/build/tmp/work/...`` and residual effects of the build by entering
-      the following sequence of commands:
-      ::
+      the following sequence of commands::
 
               $ cd poky/build
               $ bitbake -c cleanall yocto-linux
@@ -1140,8 +1102,8 @@ configuration fragments, and how to interactively modify your
 ``.config`` file to create the leanest kernel configuration file
 possible.
 
-For more information on kernel configuration, see the "`Changing the
-Configuration <#changing-the-configuration>`__" section.
+For more information on kernel configuration, see the
+":ref:`kernel-dev/common:changing the configuration`" section.
 
 Using  ``menuconfig``
 ---------------------
@@ -1162,8 +1124,7 @@ environment, you must do the following:
 -  You must be sure of the state of your build's configuration in the
    :term:`Source Directory`.
 
--  Your build host must have the following two packages installed:
-   ::
+-  Your build host must have the following two packages installed::
 
       libncurses5-dev
       libtinfo-dev
@@ -1171,8 +1132,7 @@ environment, you must do the following:
 The following commands initialize the BitBake environment, run the
 :ref:`ref-tasks-kernel_configme`
 task, and launch ``menuconfig``. These commands assume the Source
-Directory's top-level folder is ``poky``:
-::
+Directory's top-level folder is ``poky``::
 
    $ cd poky
    $ source oe-init-build-env
@@ -1234,8 +1194,7 @@ the ``.config`` file would be:
 
 Within the ``.config`` file, you can see the kernel settings. For
 example, the following entry shows that symmetric multi-processor
-support is not set:
-::
+support is not set::
 
    # CONFIG_SMP is not set
 
@@ -1276,8 +1235,7 @@ your layer's ``recipes-kernel/linux`` directory, and rename the copied
 file to "defconfig" (e.g.
 ``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then,
 add the following lines to the linux-yocto ``.bbappend`` file in your
-layer:
-::
+layer::
 
    FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
    SRC_URI += "file://defconfig"
@@ -1297,8 +1255,8 @@ created to hold the configuration changes.
    applies these on top of and after applying the existing ``defconfig`` file
    configurations.
 
-For more information on configuring the kernel, see the "`Changing the
-Configuration <#changing-the-configuration>`__" section.
+For more information on configuring the kernel, see the
+":ref:`kernel-dev/common:changing the configuration`" section.
 
 Creating Configuration Fragments
 --------------------------------
@@ -1325,8 +1283,7 @@ appear in the ``.config`` file, which is in the :term:`Build Directory`.
 It is simple to create a configuration fragment. One method is to use
 shell commands. For example, issuing the following from the shell
 creates a configuration fragment file named ``my_smp.cfg`` that enables
-multi-processor support within the kernel:
-::
+multi-processor support within the kernel::
 
    $ echo "CONFIG_SMP=y" >> my_smp.cfg
 
@@ -1344,8 +1301,7 @@ To create a configuration fragment using this method, follow these
 steps:
 
 1. *Complete a Build Through Kernel Configuration:* Complete a build at
-   least through the kernel configuration task as follows:
-   ::
+   least through the kernel configuration task as follows::
 
       $ bitbake linux-yocto -c kernel_configme -f
 
@@ -1354,8 +1310,7 @@ steps:
    your build state might become unknown, it is best to run this task
    prior to starting ``menuconfig``.
 
-2. *Launch menuconfig:* Run the ``menuconfig`` command:
-   ::
+2. *Launch menuconfig:* Run the ``menuconfig`` command::
 
       $ bitbake linux-yocto -c menuconfig
 
@@ -1363,14 +1318,13 @@ steps:
    to prepare a configuration fragment. The resulting file
    ``fragment.cfg`` is placed in the
    ``${``\ :term:`WORKDIR`\ ``}``
-   directory:
-   ::
+   directory::
 
       $ bitbake linux-yocto -c diffconfig
 
 The ``diffconfig`` command creates a file that is a list of Linux kernel
-``CONFIG_`` assignments. See the "`Changing the
-Configuration <#changing-the-configuration>`__" section for additional
+``CONFIG_`` assignments. See the
+":ref:`kernel-dev/common:changing the configuration`" section for additional
 information on how to use the output as a configuration fragment.
 
 .. note::
@@ -1389,8 +1343,7 @@ options in a file called ``myconfig.cfg``. If you put that file inside a
 directory named ``linux-yocto`` that resides in the same directory as
 the kernel's append file within your layer and then add the following
 statements to the kernel's append file, those configuration options will
-be picked up and applied when the kernel is built:
-::
+be picked up and applied when the kernel is built::
 
    FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
    SRC_URI += "file://myconfig.cfg"
@@ -1399,8 +1352,7 @@ As mentioned earlier, you can group related configurations into multiple
 files and name them all in the ``SRC_URI`` statement as well. For
 example, you could group separate configurations specifically for
 Ethernet and graphics into their own files and add those by using a
-``SRC_URI`` statement like the following in your append file:
-::
+``SRC_URI`` statement like the following in your append file::
 
    SRC_URI += "file://myconfig.cfg \
                file://eth.cfg \
@@ -1411,8 +1363,7 @@ Validating Configuration
 
 You can use the
 :ref:`ref-tasks-kernel_configcheck`
-task to provide configuration validation:
-::
+task to provide configuration validation::
 
    $ bitbake linux-yocto -c kernel_configcheck -f
 
@@ -1539,8 +1490,7 @@ To streamline the configuration, do the following:
    successfully. Use this configuration file as your baseline.
 
 2. *Run Configure and Check Tasks:* Separately run the
-   ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks:
-   ::
+   ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks::
 
       $ bitbake linux-yocto -c kernel_configme -f
       $ bitbake linux-yocto -c kernel_configcheck -f
@@ -1574,8 +1524,7 @@ Expanding Variables
 Sometimes it is helpful to determine what a variable expands to during a
 build. You can examine the values of variables by examining the
 output of the ``bitbake -e`` command. The output is long and is more
-easily managed in a text file, which allows for easy searches:
-::
+easily managed in a text file, which allows for easy searches::
 
    $ bitbake -e virtual/kernel > some_text_file
 
@@ -1592,15 +1541,13 @@ source directory. Follow these steps to clean up the version string:
 
 1. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned
    Git repository (source directory) and use the following Git command
-   to list the files that have been changed, added, or removed:
-   ::
+   to list the files that have been changed, added, or removed::
 
       $ git status
 
 2. *Commit the Changes:* You should commit those changes to the kernel
    source tree regardless of whether or not you will save, export, or
-   use the changes:
-   ::
+   use the changes::
 
       $ git add
       $ git commit -s -a -m "getting rid of -dirty"
@@ -1614,8 +1561,7 @@ source directory. Follow these steps to clean up the version string:
    ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
    section. For
    information on building the kernel image when using Bitbake, see the
-   "`Using Traditional Kernel Development to Patch the
-   Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__"
+   ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
    section.
 
 Working With Your Own Sources
@@ -1636,8 +1582,7 @@ linux-yocto custom recipe (``linux-yocto-custom.bb``) that uses
 ``kernel.org`` sources and the Yocto Project Linux kernel tools for
 managing kernel Metadata. You can find this recipe in the ``poky`` Git
 repository of the Yocto Project :yocto_git:`Source Repository <>`
-at:
-::
+at::
 
    poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
 
@@ -1658,8 +1603,7 @@ Here are some basic steps you can use to work with your own sources:
    ``defconfig`` file or configuration fragment files in your layer.
    When you use the ``linux-yocto-custom.bb`` recipe, you must specify a
    configuration. If you do not have a ``defconfig`` file, you can run
-   the following:
-   ::
+   the following::
 
       $ make defconfig
 
@@ -1711,8 +1655,7 @@ Here are some basic steps you can use to work with your own sources:
       ``LINUX_VERSION`` with the Source Control Manager (SCM) revision
       as derived from the :term:`SRCPV`
       variable. The combined results are a string with the following
-      form:
-      ::
+      form::
 
          3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
 
@@ -1726,15 +1669,15 @@ Here are some basic steps you can use to work with your own sources:
       triggers an explicit build failure. You must change it to match a
       list of the machines that your new recipe supports. For example,
       to support the ``qemux86`` and ``qemux86-64`` machines, use the
-      following form:
-      ::
+      following form::
 
          COMPATIBLE_MACHINE = "qemux86|qemux86-64"
 
 5. *Customize Your Recipe as Needed:* Provide further customizations to
    your recipe as needed just as you would customize an existing
-   linux-yocto recipe. See the "`Modifying an Existing
-   Recipe <#modifying-an-existing-recipe>`__" section for information.
+   linux-yocto recipe. See the
+   ":ref:`ref-manual/devtool-reference:modifying an existing recipe`" section
+   for information.
 
 Working with Out-of-Tree Modules
 ================================
@@ -1809,8 +1752,7 @@ Typically, you will need to set the following variables:
 
 Depending on the build system used by the module sources, you might need
 to make some adjustments. For example, a typical module ``Makefile``
-looks much like the one provided with the ``hello-mod`` template:
-::
+looks much like the one provided with the ``hello-mod`` template::
 
    obj-m := hello.o
 
@@ -1847,8 +1789,7 @@ them appropriately for your machine configuration file:
 -  :term:`MACHINE_EXTRA_RRECOMMENDS`
 
 Modules are often not required for boot and can be excluded from certain
-build configurations. The following allows for the most flexibility:
-::
+build configurations. The following allows for the most flexibility::
 
    MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
 
@@ -1897,26 +1838,22 @@ branch.
 
    $ git whatchanged origin/standard/base..origin/standard/emenlow
 
-To see short, one line summaries of changes use the ``git log`` command:
-::
+To see short, one line summaries of changes use the ``git log`` command::
 
    $ git log --oneline origin/standard/base..origin/standard/emenlow
 
-Use this command to see code differences for the changes:
-::
+Use this command to see code differences for the changes::
 
    $ git diff origin/standard/base..origin/standard/emenlow
 
 Use this command to see the commit log messages and the text
-differences:
-::
+differences::
 
    $ git show origin/standard/base..origin/standard/emenlow
 
 Use this command to create individual patches for each change. Here is
 an example that creates patch files for each commit and places them
-in your ``Documents`` directory:
-::
+in your ``Documents`` directory::
 
    $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
 
@@ -1925,15 +1862,13 @@ Showing a Particular Feature or Branch Change
 
 Tags in the Yocto Project kernel tree divide changes for significant
 features or branches. The ``git show`` tag command shows changes based
-on a tag. Here is an example that shows ``systemtap`` changes:
-::
+on a tag. Here is an example that shows ``systemtap`` changes::
 
    $ git show systemtap
 
 You can use the ``git branch --contains`` tag command to
 show the branches that contain a particular feature. This command shows
-the branches that contain the ``systemtap`` feature:
-::
+the branches that contain the ``systemtap`` feature::
 
    $ git branch --contains systemtap
 
@@ -1988,8 +1923,7 @@ build.
          searched during the build as potential feature directories.
 
    Continuing with the example, suppose the "test.scc" feature you are
-   adding has a ``test.scc`` file in the following directory:
-   ::
+   adding has a ``test.scc`` file in the following directory::
 
       my_recipe
       |
@@ -2003,8 +1937,7 @@ build.
    a similarly named configuration fragment file ``test.cfg``.
 
 2. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the
-   recipe's ``SRC_URI`` statement:
-   ::
+   recipe's ``SRC_URI`` statement::
 
       SRC_URI_append = " file://test.scc"
 
@@ -2013,8 +1946,7 @@ build.
 
 3. *Specify the Feature as a Kernel Feature:* Use the
    ``KERNEL_FEATURES`` statement to specify the feature as a kernel
-   feature:
-   ::
+   feature::
 
       KERNEL_FEATURES_append = " test.scc"
 

documentation/kernel-dev/concepts-appx.rst

@@ -359,8 +359,7 @@ 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`` contains the following files::
 
    yocto-kernel-cache/features/drm-psb/hardware.cfg
    yocto-kernel-cache/features/kgdb/hardware.cfg
@@ -380,8 +379,7 @@ or non-hardware. To better show this, consider a situation where the
    yocto-kernel-cache/ktypes/base/hardware.kcf
    yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf
 
-The following list
-provides explanations for the various files:
+Here are explanations for the various files:
 
 -  ``hardware.kcf``: Specifies a list of kernel Kconfig files that
    contain hardware options only.
@@ -400,8 +398,7 @@ provides explanations for the various files:
    (i.e. ``hardware.kcf`` or ``non-hardware.kcf``).
 
 Here is a specific example using the
-``kernel-cache/bsp/mti-malta32/hardware.cfg``:
-::
+``kernel-cache/bsp/mti-malta32/hardware.cfg``::
 
    CONFIG_SERIAL_8250
    CONFIG_SERIAL_8250_CONSOLE

documentation/kernel-dev/faq.rst

@@ -7,7 +7,7 @@ Kernel Development FAQ
 Common Questions and Solutions
 ==============================
 
-The following lists some solutions for common questions.
+Here are some solutions for common questions.
 
 How do I use my own Linux kernel ``.config`` file?
 --------------------------------------------------
@@ -57,8 +57,7 @@ These other variables are useful for installing specific modules:
 
 For example, set the following in the ``qemux86.conf`` file to include
 the ``ab123`` kernel modules with images built for the ``qemux86``
-machine:
-::
+machine::
 
    MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123"
 
@@ -71,8 +70,7 @@ How do I change the Linux kernel command line?
 The Linux kernel command line is
 typically specified in the machine config using the ``APPEND`` variable.
 For example, you can add some helpful debug information doing the
-following:
-::
+following::
 
    APPEND += "printk.time=y initcall_debug debug"
 

documentation/kernel-dev/intro.rst

@@ -90,8 +90,7 @@ understand the following documentation:
 -  The ":ref:`dev-manual/common-tasks:understanding and creating layers`"
    section in the Yocto Project Development Tasks Manual.
 
--  The "`Kernel Modification
-   Workflow <#kernel-modification-workflow>`__" section.
+-  The ":ref:`kernel-dev/intro:kernel modification workflow`" section.
 
 Kernel Modification Workflow
 ============================

documentation/kernel-dev/maint-appx.rst

@@ -28,8 +28,7 @@ in the Yocto Project Linux kernel in any clone of the Yocto Project
 Linux kernel source repository and ``yocto-kernel-cache`` Git trees. For
 example, the following commands clone the Yocto Project baseline Linux
 kernel that branches off ``linux.org`` version 4.12 and the
-``yocto-kernel-cache``, which contains stores of kernel Metadata:
-::
+``yocto-kernel-cache``, which contains stores of kernel Metadata::
 
    $ git clone git://git.yoctoproject.org/linux-yocto-4.12
    $ git clone git://git.yoctoproject.org/linux-kernel-cache
@@ -42,16 +41,14 @@ section.
 
 Once you have cloned the kernel Git repository and the cache of Metadata
 on your local machine, you can discover the branches that are available
-in the repository using the following Git command:
-::
+in the repository using the following Git command::
 
    $ git branch -a
 
 Checking out a branch allows you to work with a particular Yocto Linux
 kernel. For example, the following commands check out the
 "standard/beagleboard" branch of the Yocto Linux kernel repository and
-the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository:
-::
+the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository::
 
    $ cd ~/linux-yocto-4.12
    $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard
@@ -111,8 +108,7 @@ patch, or BSP:
 
    For a typical build, the target of the search is a feature
    description in an ``.scc`` file whose name follows this format (e.g.
-   ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``):
-   ::
+   ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``)::
 
       bsp_root_name-kernel_type.scc
 
@@ -222,8 +218,7 @@ build process generates a build tree that is separate from your kernel's
 local Git source repository tree. This build tree has a name that uses
 the following form, where ``${MACHINE}`` is the metadata name of the
 machine (BSP) and "kernel_type" is one of the Yocto Project supported
-kernel types (e.g. "standard"):
-::
+kernel types (e.g. "standard")::
 
    linux-${MACHINE}-kernel_type-build
 

documentation/overview-manual/concepts.rst

@@ -55,8 +55,7 @@ This section briefly introduces BitBake. If you want more information on
 BitBake, see the :doc:`BitBake User Manual <bitbake:index>`.
 
 To see a list of the options BitBake supports, use either of the
-following commands:
-::
+following commands::
 
    $ bitbake -h
    $ bitbake --help
@@ -66,8 +65,7 @@ The most common usage for BitBake is ``bitbake recipename``, where
 to as the "target"). The target often equates to the first part of a
 recipe's filename (e.g. "foo" for a recipe named ``foo_1.3.0-r0.bb``).
 So, to process the ``matchbox-desktop_1.2.3.bb`` recipe file, you might
-type the following:
-::
+type the following::
 
    $ bitbake matchbox-desktop
 
@@ -132,7 +130,7 @@ Layers
 
 Layers are repositories that contain related metadata (i.e. sets of
 instructions) that tell the OpenEmbedded build system how to build a
-target. Yocto Project's `layer model <#the-yocto-project-layer-model>`__
+target. :ref:`overview-manual/yp-intro:the yocto project layer model`
 facilitates collaboration, sharing, customization, and reuse within the
 Yocto Project development environment. Layers logically separate
 information for your project. For example, you can use a layer to hold
@@ -207,8 +205,8 @@ you can tell BitBake the target architecture for which you are building
 the image, where to store downloaded source, and other build properties.
 
 The following figure shows an expanded representation of the "User
-Configuration" box of the `general workflow
-figure <#general-workflow-figure>`__:
+Configuration" box of the :ref:`general workflow
+figure <overview-manual/concepts:openembedded build system concepts>`:
 
 .. image:: figures/user-configuration.png
    :align: center
@@ -374,7 +372,7 @@ provide Metadata for the software, machine, and policies.
 
 In general, three types of layer input exists. You can see them below
 the "User Configuration" box in the `general workflow
-figure <#general-workflow-figure>`__:
+figure <overview-manual/concepts:openembedded build system concepts>`:
 
 -  *Metadata (.bb + Patches):* Software layers containing
    user-supplied recipe files, patches, and append files. A good example
@@ -387,8 +385,8 @@ figure <#general-workflow-figure>`__:
 -  *Machine BSP Configuration:* Board Support Package (BSP) layers (i.e.
    "BSP Layer" in the following figure) providing machine-specific
    configurations. This type of information is specific to a particular
-   target architecture. A good example of a BSP layer from the `Poky
-   Reference Distribution <#gs-reference-distribution-poky>`__ is the
+   target architecture. A good example of a BSP layer from the
+   :ref:`overview-manual/yp-intro:reference distribution (poky)` is the
    :yocto_git:`meta-yocto-bsp </poky/tree/meta-yocto-bsp>`
    layer.
 
@@ -403,7 +401,8 @@ figure <#general-workflow-figure>`__:
    that contain many policy configurations for the Poky distribution.
 
 The following figure shows an expanded representation of these three
-layers from the `general workflow figure <#general-workflow-figure>`__:
+layers from the :ref:`general workflow figure
+<overview-manual/concepts:openembedded build system concepts>`:
 
 .. image:: figures/layer-input.png
    :align: center
@@ -418,9 +417,9 @@ in the
 section in the
 Yocto Project Development Tasks Manual. For a general discussion on
 layers and the many layers from which you can draw, see the
-"`Layers <#overview-layers>`__" and "`The Yocto Project Layer
-Model <#the-yocto-project-layer-model>`__" sections both earlier in this
-manual.
+":ref:`overview-manual/concepts:layers`" and
+":ref:`overview-manual/yp-intro:the yocto project layer model`" sections both
+earlier in this manual.
 
 If you explored the previous links, you discovered some areas where many
 layers that work with the Yocto Project exist. The :yocto_git:`Source
@@ -514,11 +513,12 @@ Sources
 -------
 
 In order for the OpenEmbedded build system to create an image or any
-target, it must be able to access source files. The `general workflow
-figure <#general-workflow-figure>`__ represents source files using the
-"Upstream Project Releases", "Local Projects", and "SCMs (optional)"
-boxes. The figure represents mirrors, which also play a role in locating
-source files, with the "Source Materials" box.
+target, it must be able to access source files. The :ref:`general workflow
+figure <overview-manual/concepts:openembedded build system concepts>`
+represents source files using the "Upstream Project Releases", "Local
+Projects", and "SCMs (optional)" boxes. The figure represents mirrors,
+which also play a role in locating source files, with the "Source
+Materials" box.
 
 The method by which source files are ultimately organized is a function
 of the project. For example, for released software, projects tend to use
@@ -554,7 +554,7 @@ Directory if needed without fear of removing any downloaded source file.
 
 The remainder of this section provides a deeper look into the source
 files and the mirrors. Here is a more detailed look at the source file
-area of the `general workflow figure <#general-workflow-figure>`__:
+area of the :ref:`general workflow figure <overview-manual/concepts:openembedded build system concepts>`:
 
 .. image:: figures/source-input.png
    :align: center
@@ -628,9 +628,9 @@ Package Feeds
 
 When the OpenEmbedded build system generates an image or an SDK, it gets
 the packages from a package feed area located in the
-:term:`Build Directory`. The `general
-workflow figure <#general-workflow-figure>`__ shows this package feeds
-area in the upper-right corner.
+:term:`Build Directory`. The :ref:`general workflow figure
+<overview-manual/concepts:openembedded build system concepts>`
+shows this package feeds area in the upper-right corner.
 
 This section looks a little closer into the package feeds area used by
 the build system. Here is a more detailed look at the area:
@@ -691,10 +691,10 @@ BitBake Tool
 
 The OpenEmbedded build system uses
 :term:`BitBake` to produce images and
-Software Development Kits (SDKs). You can see from the `general workflow
-figure <#general-workflow-figure>`__, the BitBake area consists of
-several functional areas. This section takes a closer look at each of
-those areas.
+Software Development Kits (SDKs). You can see from the :ref:`general workflow
+figure <overview-manual/concepts:openembedded build system concepts>`,
+the BitBake area consists of several functional areas. This section takes a
+closer look at each of those areas.
 
 .. note::
 
@@ -820,7 +820,7 @@ source files, which are located in the
 :term:`S` directory.
 
 For more information on how the source directories are created, see the
-"`Source Fetching <#source-fetching-dev-environment>`__" section. For
+":ref:`overview-manual/concepts:source fetching`" section. For
 more information on how to create patches and how the build system
 processes patches, see the
 ":ref:`dev-manual/common-tasks:patching code`"
@@ -957,8 +957,8 @@ details on how this is accomplished, you can look at
 Depending on the type of packages being created (RPM, DEB, or IPK), the
 :ref:`do_package_write_* <ref-tasks-package_write_deb>`
 task creates the actual packages and places them in the Package Feed
-area, which is ``${TMPDIR}/deploy``. You can see the "`Package
-Feeds <#package-feeds-dev-environment>`__" section for more detail on
+area, which is ``${TMPDIR}/deploy``. You can see the
+":ref:`overview-manual/concepts:package feeds`" section for more detail on
 that part of the build process.
 
 .. note::
@@ -1066,15 +1066,13 @@ the image. The formats used for the root filesystem depend on the
 support compression.
 
 As an example, a dynamically created task when creating a particular
-image type would take the following form:
-::
+image type would take the following form::
 
    do_image_type
 
 So, if the type
 as specified by the ``IMAGE_FSTYPES`` were ``ext4``, the dynamically
-generated task would be as follows:
-::
+generated task would be as follows::
 
    do_image_ext4
 
@@ -1119,7 +1117,7 @@ and
 :ref:`ref-tasks-populate_sdk_ext`
 tasks use these key variables to help create the list of packages to
 actually install. For information on the variables listed in the figure,
-see the "`Application Development SDK <#sdk-dev-environment>`__"
+see the ":ref:`overview-manual/concepts:application development sdk`"
 section.
 
 The ``do_populate_sdk`` task helps create the standard SDK and handles
@@ -1147,8 +1145,8 @@ For each task that completes successfully, BitBake writes a stamp file
 into the :term:`STAMPS_DIR`
 directory. The beginning of the stamp file's filename is determined by
 the :term:`STAMP` variable, and the end
-of the name consists of the task's name and current `input
-checksum <#overview-checksums>`__.
+of the name consists of the task's name and current :ref:`input
+checksum <overview-manual/concepts:checksums (signatures)>`.
 
 .. note::
 
@@ -1165,10 +1163,10 @@ file does not exist, the task is rerun.
 .. note::
 
    The stamp mechanism is more general than the shared state (sstate)
-   cache mechanism described in the "`Setscene Tasks and Shared
-   State <#setscene-tasks-and-shared-state>`__" section. BitBake avoids
-   rerunning any task that has a valid stamp file, not just tasks that
-   can be accelerated through the sstate cache.
+   cache mechanism described in the
+   ":ref:`overview-manual/concepts:setscene tasks and shared state`" section.
+   BitBake avoids rerunning any task that has a valid stamp file, not just
+   tasks that can be accelerated through the sstate cache.
 
    However, you should realize that stamp files only serve as a marker
    that some work has been done and that these files do not record task
@@ -1271,7 +1269,8 @@ Images
 
 The images produced by the build system are compressed forms of the root
 filesystem and are ready to boot on a target device. You can see from
-the `general workflow figure <#general-workflow-figure>`__ that BitBake
+the :ref:`general workflow figure
+<overview-manual/concepts:openembedded build system concepts>` that BitBake
 output, in part, consists of images. This section takes a closer look at
 this output:
 
@@ -1327,7 +1326,8 @@ current configuration.
 Application Development SDK
 ---------------------------
 
-In the `general workflow figure <#general-workflow-figure>`__, the
+In the :ref:`general workflow figure
+<overview-manual/concepts:openembedded build system concepts>`, the
 output labeled "Application Development SDK" represents an SDK. The SDK
 generation process differs depending on whether you build an extensible
 SDK (e.g. ``bitbake -c populate_sdk_ext`` imagename) or a standard SDK
@@ -1357,8 +1357,8 @@ can initialize the environment before using the tools.
       your own SDK installer.
 
    -  For background information on cross-development toolchains in the
-      Yocto Project development environment, see the "`Cross-Development
-      Toolchain Generation <#cross-development-toolchain-generation>`__"
+      Yocto Project development environment, see the
+      ":ref:`overview-manual/concepts:cross-development toolchain generation`"
       section.
 
    -  For information on setting up a cross-development environment, see
@@ -1474,8 +1474,7 @@ cross-compiler that is used internally within BitBake only.
    gcc-cross
    .
 
-The chain of events that occurs when the standard toolchain is bootstrapped:
-::
+The chain of events that occurs when the standard toolchain is bootstrapped::
 
    binutils-cross -> linux-libc-headers -> gcc-cross -> libgcc-initial -> glibc -> libgcc -> gcc-runtime
 
@@ -1524,8 +1523,7 @@ might not be the same machine as the Build Host.
    can take advantage of pre-built images that ship with the Yocto
    Project and already contain cross-development toolchain installers.
 
-Here is the bootstrap process for the relocatable toolchain:
-::
+Here is the bootstrap process for the relocatable toolchain::
 
    gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian
 
@@ -1699,8 +1697,7 @@ to the task.
 
 Like the ``WORKDIR`` case, situations exist where dependencies should be
 ignored. For these situations, you can instruct the build process to
-ignore a dependency by using a line like the following:
-::
+ignore a dependency by using a line like the following::
 
    PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
 
@@ -1710,8 +1707,7 @@ reference it.
 
 Equally, there are cases where you need to add dependencies BitBake is
 not able to find. You can accomplish this by using a line like the
-following:
-::
+following::
 
    PACKAGE_ARCHS[vardeps] = "MACHINE"
 
@@ -1741,8 +1737,7 @@ and the dependent task hashes can be influenced. Within the BitBake
 configuration file, you can give BitBake some extra information to help
 it construct the basehash. The following statement effectively results
 in a list of global variable dependency excludes (i.e. variables never
-included in any checksum):
-::
+included in any checksum)::
 
    BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \\
        SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \\
@@ -1767,16 +1762,15 @@ desired. This file defines the two basic signature generators
 "OEBasicHash". By default, a dummy "noop" signature handler is enabled
 in BitBake. This means that behavior is unchanged from previous
 versions. OE-Core uses the "OEBasicHash" signature handler by default
-through this setting in the ``bitbake.conf`` file:
-::
+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 <#stamp-files-and-the-rerunning-of-tasks>`__. 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
+as the "OEBasic" version but adds the task hash to the :ref:`stamp
+files <overview-manual/concepts:stamp files and the rerunning of tasks>`. 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.
 
@@ -1822,8 +1816,7 @@ The Yocto Project team has tried to keep the details of the
 implementation hidden in ``sstate`` class. From a user's perspective,
 adding shared state wrapping to a task is as simple as this
 :ref:`ref-tasks-deploy` example taken
-from the :ref:`deploy <ref-classes-deploy>` class:
-::
+from the :ref:`deploy <ref-classes-deploy>` class::
 
    DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
    SSTATETASKS += "do_deploy"
@@ -1867,8 +1860,7 @@ The following list explains the previous example:
       instead, skipping the ``do_deploy`` task.
 
 -  The following task definition is glue logic needed to make the
-   previous settings effective:
-   ::
+   previous settings effective::
 
       python do_deploy_setscene () {
           sstate_setscene(d)
@@ -1894,16 +1886,16 @@ The following list explains the previous example:
       In cases where ``sstate-inputdirs`` and ``sstate-outputdirs`` would be
       the same, you can use ``sstate-plaindirs``. For example, to preserve the
       ${:term:`PKGD`} and ${:term:`PKGDEST`} output from the ``do_package``
-      task, use the following:
-      ::
+      task, use the following::
 
               do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
 
 
 -  The ``do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"`` line appends
-   extra metadata to the `stamp
-   file <#stamp-files-and-the-rerunning-of-tasks>`__. In this case, the
-   metadata makes the task specific to a machine's architecture. See
+   extra metadata to the :ref:`stamp
+   file <overview-manual/concepts:stamp files and the rerunning of tasks>`. In
+   this case, the metadata makes the task specific to a machine's architecture.
+   See
    ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:the task list`"
    section in the BitBake User Manual for more information on the
    ``stamp-extra-info`` flag.
@@ -1912,24 +1904,21 @@ The following list explains the previous example:
    multiple directories. For example, the following declares
    ``PKGDESTWORK`` and ``SHLIBWORK`` as shared state input directories,
    which populates the shared state cache, and ``PKGDATA_DIR`` and
-   ``SHLIBSDIR`` as the corresponding shared state output directories:
-   ::
+   ``SHLIBSDIR`` as the corresponding shared state output directories::
 
       do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
       do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
 
 -  These methods also include the ability to take a lockfile when
    manipulating shared state directory structures, for cases where file
-   additions or removals are sensitive:
-   ::
+   additions or removals are sensitive::
 
       do_package[sstate-lockfile] = "${PACKAGELOCK}"
 
 Behind the scenes, the shared state code works by looking in
 :term:`SSTATE_DIR` and
 :term:`SSTATE_MIRRORS` for
-shared state files. Here is an example:
-::
+shared state files. Here is an example::
 
    SSTATE_MIRRORS ?= "\
        file://.\* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
@@ -2111,8 +2100,7 @@ accomplished using fakeroot.
    under fakeroot. Otherwise, the task cannot run root-only operations,
    and cannot see the fake file ownership and permissions set by the
    other task. You need to also add a dependency on
-   ``virtual/fakeroot-native:do_populate_sysroot``, giving the following:
-   ::
+   ``virtual/fakeroot-native:do_populate_sysroot``, giving the following::
 
       fakeroot do_mytask () {
           ...

documentation/overview-manual/development-environment.rst

@@ -157,7 +157,8 @@ these tarballs gives you a snapshot of the released files.
 
    -  The recommended method for setting up the Yocto Project
       :term:`Source Directory` and the files
-      for supported BSPs (e.g., ``meta-intel``) is to use `Git <#git>`__
+      for supported BSPs (e.g., ``meta-intel``) is to use
+      :ref:`overview-manual/development-environment:git`
       to create a local copy of the upstream repositories.
 
    -  Be sure to always work in matching branches for both the selected
@@ -214,7 +215,8 @@ Git Workflows and the Yocto Project
 ===================================
 
 Developing using the Yocto Project likely requires the use of
-`Git <#git>`__. Git is a free, open source distributed version control
+:ref:`overview-manual/development-environment:git`.
+Git is a free, open source distributed version control
 system used as part of many collaborative design environments. This
 section provides workflow concepts using the Yocto Project and Git. In
 particular, the information covers basic practices that describe roles
@@ -382,11 +384,10 @@ commands.
 Repositories, Tags, and Branches
 --------------------------------
 
-As mentioned briefly in the previous section and also in the "`Git
-Workflows and the Yocto
-Project <#gs-git-workflows-and-the-yocto-project>`__" section, the Yocto
-Project maintains source repositories at :yocto_git:`/`. If you
-look at this web-interface of the repositories, each item is a separate
+As mentioned briefly in the previous section and also in the
+":ref:`overview-manual/development-environment:git workflows and the yocto project`"
+section, the Yocto Project maintains source repositories at :yocto_git:`/`.
+If you look at this web-interface of the repositories, each item is a separate
 Git repository.
 
 Git repositories use branching techniques that track content change (not
@@ -429,8 +430,7 @@ local working area (also called a branch) that tracks a specific
 development branch from the upstream source Git repository. in other
 words, you can define your local Git environment to work on any
 development branch in the repository. To help illustrate, consider the
-following example Git commands:
-::
+following example Git commands::
 
    $ cd ~
    $ git clone git://git.yoctoproject.org/poky
@@ -475,8 +475,7 @@ create and checkout a local working Git branch based on a tag name. When
 you do this, you get a snapshot of the Git repository that reflects the
 state of the files when the change was made associated with that tag.
 The most common use is to checkout a working branch that matches a
-specific Yocto Project release. Here is an example:
-::
+specific Yocto Project release. Here is an example::
 
    $ cd ~
    $ git clone git://git.yoctoproject.org/poky
@@ -541,7 +540,7 @@ descriptions and strategies on how to use these commands:
    in this form assumes the local branch already exists. This command is
    analogous to "cd".
 
--  *git checkout –b working-branch upstream-branch:* Creates and
+-  *git checkout -b working-branch upstream-branch:* Creates and
    checks out a working branch on your local machine. The local branch
    tracks the upstream branch. You can use your local branch to isolate
    your work. It is a good idea to use local branches when adding

documentation/overview-manual/intro.rst

@@ -12,19 +12,18 @@ introduces the Yocto Project by providing concepts, software overviews,
 best-known-methods (BKMs), and any other high-level introductory
 information suitable for a new Yocto Project user.
 
-The following list describes what you can get from this manual:
+Here is what you can get from this manual:
 
--  `Introducing the Yocto Project <#overview-yp>`__\ *:* This chapter
-   provides an introduction to the Yocto Project. You will learn about
-   features and challenges of the Yocto Project, the layer model,
+-  :ref:`overview-manual/yp-intro:introducing the yocto project`\ *:*
+   This chapter provides an introduction to the Yocto Project. You will learn
+   about features and challenges of the Yocto Project, the layer model,
    components and tools, development methods, the
    :term:`Poky` reference distribution, the
    OpenEmbedded build system workflow, and some basic Yocto terms.
 
--  `The Yocto Project Development
-   Environment <#overview-development-environment>`__\ *:* This chapter
-   helps you get started understanding the Yocto Project development
-   environment. You will learn about open source, development hosts,
+-  :ref:`overview-manual/development-environment:the yocto project development environment`\ *:*
+   This chapter helps you get started understanding the Yocto Project
+   development environment. You will learn about open source, development hosts,
    Yocto Project source repositories, workflows using Git and the Yocto
    Project, a Git primer, and information about licensing.
 

documentation/overview-manual/yp-intro.rst

@@ -38,8 +38,7 @@ to the Yocto Project.
 Features
 --------
 
-The following list describes features and advantages of the Yocto
-Project:
+Here are features and advantages of the Yocto Project:
 
 -  *Widely Adopted Across the Industry:* Many semiconductor, operating
    system, software, and service vendors adopt and support the Yocto
@@ -96,18 +95,18 @@ Project:
    of your design instead of adopting decisions enforced by some system
    software provider.
 
--  *Uses a Layer Model:* The Yocto Project `layer
-   infrastructure <#the-yocto-project-layer-model>`__ groups related
-   functionality into separate bundles. You can incrementally add these
-   grouped functionalities to your project as needed. Using layers to
+-  *Uses a Layer Model:* The Yocto Project :ref:`layer
+   infrastructure <overview-manual/yp-intro:the yocto project layer model>`
+   groups related functionality into separate bundles. You can incrementally
+   add these grouped functionalities to your project as needed. Using layers to
    isolate and group functionality reduces project complexity and
    redundancy, allows you to easily extend the system, make
    customizations, and keep functionality organized.
 
 -  *Supports Partial Builds:* You can build and rebuild individual
    packages as needed. Yocto Project accomplishes this through its
-   `shared-state cache <#shared-state-cache>`__ (sstate) scheme. Being
-   able to build and debug components individually eases project
+   :ref:`overview-manual/concepts:shared state cache` (sstate) scheme.
+   Being able to build and debug components individually eases project
    development.
 
 -  *Releases According to a Strict Schedule:* Major releases occur on a
@@ -137,8 +136,7 @@ Project:
 Challenges
 ----------
 
-The following list presents challenges you might encounter when
-developing using the Yocto Project:
+Here are challenges you might encounter when developing using the Yocto Project:
 
 -  *Steep Learning Curve:* The Yocto Project has a steep learning curve
    and has many different ways to accomplish similar tasks. It can be
@@ -155,8 +153,9 @@ developing using the Yocto Project:
    documents on the Yocto Project website.
 
 -  *Project Workflow Could Be Confusing:* The `Yocto Project
-   workflow <#overview-development-environment>`__ could be confusing if
-   you are used to traditional desktop and server software development.
+   workflow <overview-manual/development-environment:the yocto project development environment>`
+   could be confusing if you are used to traditional desktop and server
+   software development.
    In a desktop development environment, mechanisms exist to easily pull
    and install new packages, which are typically pre-compiled binaries
    from servers accessible over the Internet. Using the Yocto Project,
@@ -291,8 +290,8 @@ associated with the Yocto Project.
 Development Tools
 -----------------
 
-The following list consists of tools that help you develop images and
-applications using the Yocto Project:
+Here are tools that help you develop images and applications using
+the Yocto Project:
 
 -  *CROPS:* `CROPS <https://github.com/crops/poky-container/>`__ is an
    open source, cross-platform development framework that leverages
@@ -346,8 +345,8 @@ applications using the Yocto Project:
 Production Tools
 ----------------
 
-The following list consists of tools that help production related
-activities using the Yocto Project:
+Here are tools that help with production related activities using the
+Yocto Project:
 
 -  *Auto Upgrade Helper:* This utility when used in conjunction with the
    :term:`OpenEmbedded Build System`
@@ -437,14 +436,13 @@ activities using the Yocto Project:
    Thanks to Pseudo, the Yocto Project never needs root privileges to
    build images for your target system.
 
-   You can read more about Pseudo in the "`Fakeroot and
-   Pseudo <#fakeroot-and-pseudo>`__" section.
+   You can read more about Pseudo in the
+   ":ref:`overview-manual/concepts:fakeroot and pseudo`" section.
 
 Open-Embedded Build System Components
 -------------------------------------
 
-The following list consists of components associated with the
-:term:`OpenEmbedded Build System`:
+Here are components associated with the :term:`OpenEmbedded Build System`:
 
 -  *BitBake:* BitBake is a core component of the Yocto Project and is
    used by the OpenEmbedded build system to build images. While BitBake
@@ -480,9 +478,9 @@ The following list consists of components associated with the
 
    Sharing a core set of metadata results in Poky as an integration
    layer on top of OE-Core. You can see that in this
-   `figure <#yp-key-dev-elements>`__. The Yocto Project combines various
-   components such as BitBake, OE-Core, script "glue", and documentation
-   for its build system.
+   :ref:`figure <overview-manual/yp-intro:what is the yocto project?>`.
+   The Yocto Project combines various components such as BitBake, OE-Core,
+   script "glue", and documentation for its build system.
 
 Reference Distribution (Poky)
 -----------------------------
@@ -490,8 +488,8 @@ Reference Distribution (Poky)
 Poky is the Yocto Project reference distribution. It contains the
 :term:`OpenEmbedded Build System`
 (BitBake and OE-Core) as well as a set of metadata to get you started
-building your own distribution. See the
-`figure <#what-is-the-yocto-project>`__ in "What is the Yocto Project?"
+building your own distribution. See the figure in
+":ref:`overview-manual/yp-intro:what is the yocto project?`"
 section for an illustration that shows Poky and its relationship with
 other parts of the Yocto Project.
 
@@ -503,14 +501,14 @@ To use the Yocto Project tools and components, you can download
    Poky does not contain binary files. It is a working example of how to
    build your own custom Linux distribution from source.
 
-You can read more about Poky in the "`Reference Embedded Distribution
-(Poky) <#reference-embedded-distribution>`__" section.
+You can read more about Poky in the
+":ref:`overview-manual/yp-intro:reference embedded distribution (poky)`"
+section.
 
 Packages for Finished Targets
 -----------------------------
 
-The following lists components associated with packages for finished
-targets:
+Here are components associated with packages for finished targets:
 
 -  *Matchbox:* Matchbox is an Open Source, base environment for the X
    Window System running on non-desktop, embedded platforms such as
@@ -567,7 +565,7 @@ Linux.
 
 3. *CROPS:* The final and best solution available now for developing
    using the Yocto Project on a system not native to Linux is with
-   `CROPS <#gs-crops-overview>`__.
+   :ref:`CROPS <overview-manual/yp-intro:development tools>`.
 
 Development Methods
 ===================
@@ -727,7 +725,8 @@ Sato.
 One of the most powerful properties of Poky is that every aspect of a
 build is controlled by the metadata. You can use metadata to augment
 these base image types by adding metadata
-`layers <#the-yocto-project-layer-model>`__ that extend functionality.
+`layers <overview-manual/yp-intro:the yocto project layer model>` that extend
+functionality.
 These layers can provide, for example, an additional software stack for
 an image type, add a board support package (BSP) for additional
 hardware, or even create a new image type.
@@ -784,8 +783,8 @@ Following is a brief summary of the "workflow":
 7. The build system generates the file system image and a customized
    Extensible SDK (eSDK) for application development in parallel.
 
-For a very detailed look at this workflow, see the "`OpenEmbedded Build
-System Concepts <#openembedded-build-system-build-concepts>`__" section.
+For a very detailed look at this workflow, see the
+":ref:`overview-manual/concepts:openembedded build system concepts`" section.
 
 Some Basic Terms
 ================

documentation/poky.yaml

@@ -1,12 +1,12 @@
-DISTRO : "3.2.3"
-DISTRO_NAME_NO_CAP : "gatesgarth"
-DISTRO_NAME : "Gatesgarth"
-DISTRO_NAME_NO_CAP_MINUS_ONE : "dunfell"
+DISTRO : "3.3"
+DISTRO_NAME_NO_CAP : "hardknott"
+DISTRO_NAME : "Hardknott"
+DISTRO_NAME_NO_CAP_MINUS_ONE : "gatesgarth"
 DISTRO_NAME_NO_CAP_LTS : "dunfell"
-YOCTO_DOC_VERSION : "3.2.3"
-YOCTO_DOC_VERSION_MINUS_ONE : "3.1.6"
-DISTRO_REL_TAG : "yocto-3.2.3"
-POKYVERSION : "24.0.3"
+YOCTO_DOC_VERSION : "3.3"
+YOCTO_DOC_VERSION_MINUS_ONE : "3.2.4"
+DISTRO_REL_TAG : "yocto-3.3"
+POKYVERSION : "25.0.0"
 YOCTO_POKY : "poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;"
 YOCTO_DL_URL : "https://downloads.yoctoproject.org"
 YOCTO_AB_URL : "https://autobuilder.yoctoproject.org"
@@ -40,3 +40,7 @@ CENTOS8_HOST_PACKAGES_ESSENTIAL : "-y epel-release
      python3-GitPython python3-jinja2 python3-pexpect xz which SDL-devel xterm \
      rpcgen mesa-libGL-devel"
 PIP3_HOST_PACKAGES_DOC : "$ sudo pip3 install sphinx sphinx_rtd_theme pyyaml"
+MIN_PYTHON_VERSION : "3.6.0"
+MIN_TAR_VERSION : "1.28"
+MIN_GIT_VERSION : "1.8.3.1"
+MIN_GCC_VERSION : "5.0"

documentation/profile-manual/intro.rst

@@ -39,12 +39,12 @@ an 'sdk' image e.g. ::
    $ bitbake core-image-sato-sdk
 
 or alternatively by adding 'tools-profile' to the EXTRA_IMAGE_FEATURES line in
-your local.conf: ::
+your local.conf::
 
    EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile"
 
 If you use the 'tools-profile' method, you don't need to build an sdk image -
-the tracing and profiling tools will be included in non-sdk images as well e.g.: ::
+the tracing and profiling tools will be included in non-sdk images as well e.g.::
 
    $ bitbake core-image-sato
 
@@ -55,7 +55,7 @@ the tracing and profiling tools will be included in non-sdk images as well e.g.:
 
    You can prevent that by setting the
    :term:`INHIBIT_PACKAGE_STRIP`
-   variable to "1" in your ``local.conf`` when you build the image: ::
+   variable to "1" in your ``local.conf`` when you build the image::
 
       INHIBIT_PACKAGE_STRIP = "1"
 
@@ -65,11 +65,11 @@ If you've already built a stripped image, you can generate debug
 packages (xxx-dbg) which you can manually install as needed.
 
 To generate debug info for packages, you can add dbg-pkgs to
-EXTRA_IMAGE_FEATURES in local.conf. For example: ::
+EXTRA_IMAGE_FEATURES in local.conf. For example::
 
    EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs"
 
 Additionally, in order to generate the right type of debuginfo, we also need to
-set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file: ::
+set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file::
 
    PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'

documentation/profile-manual/usage.rst

@@ -48,7 +48,7 @@ For this section, we'll assume you've already performed the basic setup
 outlined in the ":ref:`profile-manual/intro:General Setup`" section.
 
 In particular, you'll get the most mileage out of perf if you profile an
-image built with the following in your ``local.conf`` file: ::
+image built with the following in your ``local.conf`` file::
 
    INHIBIT_PACKAGE_STRIP = "1"
 
@@ -62,7 +62,7 @@ Basic Perf Usage
 
 The perf tool is pretty much self-documenting. To remind yourself of the
 available commands, simply type 'perf', which will show you basic usage
-along with the available perf subcommands: ::
+along with the available perf subcommands::
 
    root@crownbay:~# perf
 
@@ -110,7 +110,7 @@ applets in Yocto. ::
 The quickest and easiest way to get some basic overall data about what's
 going on for a particular workload is to profile it using 'perf stat'.
 'perf stat' basically profiles using a few default counters and displays
-the summed counts at the end of the run: ::
+the summed counts at the end of the run::
 
    root@crownbay:~# perf stat wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2
    Connecting to downloads.yoctoproject.org (140.211.169.59:80)
@@ -139,7 +139,7 @@ Also, note that 'perf stat' isn't restricted to a fixed set of counters
 - basically any event listed in the output of 'perf list' can be tallied
 by 'perf stat'. For example, suppose we wanted to see a summary of all
 the events related to kernel memory allocation/freeing along with cache
-hits and misses: ::
+hits and misses::
 
    root@crownbay:~# perf stat -e kmem:* -e cache-references -e cache-misses wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2
    Connecting to downloads.yoctoproject.org (140.211.169.59:80)
@@ -191,7 +191,7 @@ directory. ::
 To see the results in a
 'text-based UI' (tui), simply run 'perf report', which will read the
 perf.data file in the current working directory and display the results
-in an interactive UI: ::
+in an interactive UI::
 
    root@crownbay:~# perf report
 
@@ -217,7 +217,7 @@ Before we do that, however, let's try running a different profile, one
 which shows something a little more interesting. The only difference
 between the new profile and the previous one is that we'll add the -g
 option, which will record not just the address of a sampled function,
-but the entire callchain to the sampled function as well: ::
+but the entire callchain to the sampled function as well::
 
    root@crownbay:~# perf record -g wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2
    Connecting to downloads.yoctoproject.org (140.211.169.59:80)
@@ -293,7 +293,7 @@ busybox binary, which is actually stripped out by the Yocto build
 system.
 
 One way around that is to put the following in your ``local.conf`` file
-when you build the image: ::
+when you build the image::
 
    INHIBIT_PACKAGE_STRIP = "1"
 
@@ -302,26 +302,26 @@ what can we do to get perf to resolve the symbols? Basically we need to
 install the debuginfo for the BusyBox package.
 
 To generate the debug info for the packages in the image, we can add
-``dbg-pkgs`` to :term:`EXTRA_IMAGE_FEATURES` in ``local.conf``. For example: ::
+``dbg-pkgs`` to :term:`EXTRA_IMAGE_FEATURES` in ``local.conf``. For example::
 
    EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs"
 
 Additionally, in order to generate the type of debuginfo that perf
 understands, we also need to set
 :term:`PACKAGE_DEBUG_SPLIT_STYLE`
-in the ``local.conf`` file: ::
+in the ``local.conf`` file::
 
    PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'
 
 Once we've done that, we can install the
 debuginfo for BusyBox. The debug packages once built can be found in
 ``build/tmp/deploy/rpm/*`` on the host system. Find the busybox-dbg-...rpm
-file and copy it to the target. For example: ::
+file and copy it to the target. For example::
 
    [trz@empanada core2]$ scp /home/trz/yocto/crownbay-tracing-dbg/build/tmp/deploy/rpm/core2_32/busybox-dbg-1.20.2-r2.core2_32.rpm root@192.168.1.31:
    busybox-dbg-1.20.2-r2.core2_32.rpm                     100% 1826KB   1.8MB/s   00:01
 
-Now install the debug rpm on the target: ::
+Now install the debug rpm on the target::
 
    root@crownbay:~# rpm -i busybox-dbg-1.20.2-r2.core2_32.rpm
 
@@ -382,7 +382,7 @@ traditional tools can also make use of the expanded possibilities now
 available to them, and in some cases have, as mentioned previously).
 
 We can get a list of the available events that can be used to profile a
-workload via 'perf list': ::
+workload via 'perf list'::
 
    root@crownbay:~# perf list
 
@@ -525,7 +525,7 @@ workload via 'perf list': ::
 Only a subset of these would be of interest to us when looking at this
 workload, so let's choose the most likely subsystems (identified by the
 string before the colon in the Tracepoint events) and do a 'perf stat'
-run using only those wildcarded subsystems: ::
+run using only those wildcarded subsystems::
 
    root@crownbay:~# perf stat -e skb:* -e net:* -e napi:* -e sched:* -e workqueue:* -e irq:* -e syscalls:* wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2
    Performance counter stats for 'wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2':
@@ -587,7 +587,7 @@ run using only those wildcarded subsystems: ::
 
 
 Let's pick one of these tracepoints
-and tell perf to do a profile using it as the sampling event: ::
+and tell perf to do a profile using it as the sampling event::
 
    root@crownbay:~# perf record -g -e sched:sched_wakeup wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2
 
@@ -644,14 +644,14 @@ individual steps that go into the higher-level behavior exposed by the
 coarse-grained profiling data.
 
 As a concrete example, we can trace all the events we think might be
-applicable to our workload: ::
+applicable to our workload::
 
    root@crownbay:~# perf record -g -e skb:* -e net:* -e napi:* -e sched:sched_switch -e sched:sched_wakeup -e irq:*
     -e syscalls:sys_enter_read -e syscalls:sys_exit_read -e syscalls:sys_enter_write -e syscalls:sys_exit_write
     wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2
 
 We can look at the raw trace output using 'perf script' with no
-arguments: ::
+arguments::
 
    root@crownbay:~# perf script
 
@@ -735,7 +735,7 @@ two programming language bindings, one for Python and one for Perl.
 
 Now that we have the trace data in perf.data, we can use 'perf script
 -g' to generate a skeleton script with handlers for the read/write
-entry/exit events we recorded: ::
+entry/exit events we recorded::
 
    root@crownbay:~# perf script -g python
    generated Python script: perf-script.py
@@ -755,7 +755,7 @@ with its parameters. For example:
                   print "skbaddr=%u, len=%u, name=%s\n" % (skbaddr, len, name),
 
 We can run that script directly to print all of the events contained in the
-perf.data file: ::
+perf.data file::
 
    root@crownbay:~# perf script -s perf-script.py
 
@@ -833,7 +833,7 @@ result of all the per-event tallies. For that, we use the special
             for event_name, count in counts.iteritems():
                     print "%-40s %10s\n" % (event_name, count)
 
-The end result is a summary of all the events recorded in the trace: ::
+The end result is a summary of all the events recorded in the trace::
 
    skb__skb_copy_datagram_iovec                  13148
    irq__softirq_entry                             4796
@@ -877,13 +877,13 @@ To do system-wide profiling or tracing, you typically use the -a flag to
 'perf record'.
 
 To demonstrate this, open up one window and start the profile using the
--a flag (press Ctrl-C to stop tracing): ::
+-a flag (press Ctrl-C to stop tracing)::
 
    root@crownbay:~# perf record -g -a
    ^C[ perf record: Woken up 6 times to write data ]
    [ perf record: Captured and wrote 1.400 MB perf.data (~61172 samples) ]
 
-In another window, run the wget test: ::
+In another window, run the wget test::
 
    root@crownbay:~# wget http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2
    Connecting to downloads.yoctoproject.org (140.211.169.59:80)
@@ -903,7 +903,7 @@ unresolvable symbols in the expanded Xorg callchain).
 Note also that we have both kernel and userspace entries in the above
 snapshot. We can also tell perf to focus on userspace but providing a
 modifier, in this case 'u', to the 'cycles' hardware counter when we
-record a profile: ::
+record a profile::
 
    root@crownbay:~# perf record -g -a -e cycles:u
    ^C[ perf record: Woken up 2 times to write data ]
@@ -923,13 +923,13 @@ the entries associated with the libc-xxx.so DSO.
    :align: center
 
 We can also use the system-wide -a switch to do system-wide tracing.
-Here we'll trace a couple of scheduler events: ::
+Here we'll trace a couple of scheduler events::
 
    root@crownbay:~# perf record -a -e sched:sched_switch -e sched:sched_wakeup
    ^C[ perf record: Woken up 38 times to write data ]
    [ perf record: Captured and wrote 9.780 MB perf.data (~427299 samples) ]
 
-We can look at the raw output using 'perf script' with no arguments: ::
+We can look at the raw output using 'perf script' with no arguments::
 
    root@crownbay:~# perf script
 
@@ -952,7 +952,7 @@ do with what we're interested in, namely events that schedule 'perf'
 itself in and out or that wake perf up. We can get rid of those by using
 the '--filter' option - for each event we specify using -e, we can add a
 --filter after that to filter out trace events that contain fields with
-specific values: ::
+specific values::
 
    root@crownbay:~# perf record -a -e sched:sched_switch --filter 'next_comm != perf && prev_comm != perf' -e sched:sched_wakeup --filter 'comm != perf'
    ^C[ perf record: Woken up 38 times to write data ]
@@ -1017,7 +1017,7 @@ perf isn't restricted to the fixed set of static tracepoints listed by
 'perf list'. Users can also add their own 'dynamic' tracepoints anywhere
 in the kernel. For instance, suppose we want to define our own
 tracepoint on do_fork(). We can do that using the 'perf probe' perf
-subcommand: ::
+subcommand::
 
    root@crownbay:~# perf probe do_fork
    Added new event:
@@ -1031,7 +1031,7 @@ Adding a new tracepoint via
 'perf probe' results in an event with all the expected files and format
 in /sys/kernel/debug/tracing/events, just the same as for static
 tracepoints (as discussed in more detail in the trace events subsystem
-section: ::
+section::
 
    root@crownbay:/sys/kernel/debug/tracing/events/probe/do_fork# ls -al
    drwxr-xr-x    2 root     root             0 Oct 28 11:42 .
@@ -1056,7 +1056,7 @@ section: ::
    print fmt: "(%lx)", REC->__probe_ip
 
 We can list all dynamic tracepoints currently in
-existence: ::
+existence::
 
    root@crownbay:~# perf probe -l
     probe:do_fork (on do_fork)
@@ -1064,13 +1064,13 @@ existence: ::
 
 Let's record system-wide ('sleep 30' is a
 trick for recording system-wide but basically do nothing and then wake
-up after 30 seconds): ::
+up after 30 seconds)::
 
    root@crownbay:~# perf record -g -a -e probe:do_fork sleep 30
    [ perf record: Woken up 1 times to write data ]
    [ perf record: Captured and wrote 0.087 MB perf.data (~3812 samples) ]
 
-Using 'perf script' we can see each do_fork event that fired: ::
+Using 'perf script' we can see each do_fork event that fired::
 
    root@crownbay:~# perf script
 
@@ -1163,7 +1163,7 @@ addressed by a Yocto bug: :yocto_bugs:`Bug 3388 - perf: enable man pages for
 basic 'help' functionality </show_bug.cgi?id=3388>`.
 
 The man pages in text form, along with some other files, such as a set
-of examples, can be found in the 'perf' directory of the kernel tree: ::
+of examples, can be found in the 'perf' directory of the kernel tree::
 
    tools/perf/Documentation
 
@@ -1197,7 +1197,7 @@ Basic ftrace usage
 'ftrace' essentially refers to everything included in the /tracing
 directory of the mounted debugfs filesystem (Yocto follows the standard
 convention and mounts it at /sys/kernel/debug). Here's a listing of all
-the files found in /sys/kernel/debug/tracing on a Yocto system: ::
+the files found in /sys/kernel/debug/tracing on a Yocto system::
 
    root@sugarbay:/sys/kernel/debug/tracing# ls
    README                      kprobe_events               trace
@@ -1222,12 +1222,12 @@ the ftrace documentation.
 
 We'll start by looking at some of the available built-in tracers.
 
-cat'ing the 'available_tracers' file lists the set of available tracers: ::
+cat'ing the 'available_tracers' file lists the set of available tracers::
 
    root@sugarbay:/sys/kernel/debug/tracing# cat available_tracers
    blk function_graph function nop
 
-The 'current_tracer' file contains the tracer currently in effect: ::
+The 'current_tracer' file contains the tracer currently in effect::
 
    root@sugarbay:/sys/kernel/debug/tracing# cat current_tracer
    nop
@@ -1237,7 +1237,7 @@ The above listing of current_tracer shows that the
 there's actually no tracer currently in effect.
 
 echo'ing one of the available_tracers into current_tracer makes the
-specified tracer the current tracer: ::
+specified tracer the current tracer::
 
    root@sugarbay:/sys/kernel/debug/tracing# echo function > current_tracer
    root@sugarbay:/sys/kernel/debug/tracing# cat current_tracer
@@ -1247,7 +1247,7 @@ The above sets the current tracer to be the 'function tracer'. This tracer
 traces every function call in the kernel and makes it available as the
 contents of the 'trace' file. Reading the 'trace' file lists the
 currently buffered function calls that have been traced by the function
-tracer: ::
+tracer::
 
    root@sugarbay:/sys/kernel/debug/tracing# cat trace | less
 
@@ -1306,7 +1306,7 @@ great way to learn about how the kernel code works in a dynamic sense.
 
 It is a little more difficult to follow the call chains than it needs to
 be - luckily there's a variant of the function tracer that displays the
-callchains explicitly, called the 'function_graph' tracer: ::
+callchains explicitly, called the 'function_graph' tracer::
 
    root@sugarbay:/sys/kernel/debug/tracing# echo function_graph > current_tracer
    root@sugarbay:/sys/kernel/debug/tracing# cat trace | less
@@ -1442,7 +1442,7 @@ One especially important directory contained within the
 /sys/kernel/debug/tracing directory is the 'events' subdirectory, which
 contains representations of every tracepoint in the system. Listing out
 the contents of the 'events' subdirectory, we see mainly another set of
-subdirectories: ::
+subdirectories::
 
    root@sugarbay:/sys/kernel/debug/tracing# cd events
    root@sugarbay:/sys/kernel/debug/tracing/events# ls -al
@@ -1491,7 +1491,7 @@ subdirectories: ::
 Each one of these subdirectories
 corresponds to a 'subsystem' and contains yet again more subdirectories,
 each one of those finally corresponding to a tracepoint. For example,
-here are the contents of the 'kmem' subsystem: ::
+here are the contents of the 'kmem' subsystem::
 
    root@sugarbay:/sys/kernel/debug/tracing/events# cd kmem
    root@sugarbay:/sys/kernel/debug/tracing/events/kmem# ls -al
@@ -1513,7 +1513,7 @@ here are the contents of the 'kmem' subsystem: ::
    drwxr-xr-x    2 root     root             0 Nov 14 23:19 mm_page_pcpu_drain
 
 Let's see what's inside the subdirectory for a
-specific tracepoint, in this case the one for kmalloc: ::
+specific tracepoint, in this case the one for kmalloc::
 
    root@sugarbay:/sys/kernel/debug/tracing/events/kmem# cd kmalloc
    root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# ls -al
@@ -1529,7 +1529,7 @@ tracepoint describes the event in memory, which is used by the various
 tracing tools that now make use of these tracepoint to parse the event
 and make sense of it, along with a 'print fmt' field that allows tools
 like ftrace to display the event as text. Here's what the format of the
-kmalloc event looks like: ::
+kmalloc event looks like::
 
    root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# cat format
    name: kmalloc
@@ -1568,20 +1568,20 @@ The 'enable' file
 in the tracepoint directory is what allows the user (or tools such as
 trace-cmd) to actually turn the tracepoint on and off. When enabled, the
 corresponding tracepoint will start appearing in the ftrace 'trace' file
-described previously. For example, this turns on the kmalloc tracepoint: ::
+described previously. For example, this turns on the kmalloc tracepoint::
 
    root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# echo 1 > enable
 
 At the moment, we're not interested in the function tracer or
 some other tracer that might be in effect, so we first turn it off, but
 if we do that, we still need to turn tracing on in order to see the
-events in the output buffer: ::
+events in the output buffer::
 
    root@sugarbay:/sys/kernel/debug/tracing# echo nop > current_tracer
    root@sugarbay:/sys/kernel/debug/tracing# echo 1 > tracing_on
 
 Now, if we look at the 'trace' file, we see nothing
-but the kmalloc events we just turned on: ::
+but the kmalloc events we just turned on::
 
    root@sugarbay:/sys/kernel/debug/tracing# cat trace | less
    # tracer: nop
@@ -1627,7 +1627,7 @@ but the kmalloc events we just turned on: ::
             <idle>-0     [000] ..s3 18156.400660: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d554800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
    matchbox-termin-1361  [001] ...1 18156.552800: kmalloc: call_site=ffffffff81614050 ptr=ffff88006db34800 bytes_req=576 bytes_alloc=1024 gfp_flags=GFP_KERNEL|GFP_REPEAT
 
-To again disable the kmalloc event, we need to send 0 to the enable file: ::
+To again disable the kmalloc event, we need to send 0 to the enable file::
 
    root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# echo 0 > enable
 
@@ -1669,12 +1669,12 @@ a per-CPU graphical display. It directly uses 'trace-cmd' as the
 plumbing that accomplishes all that underneath the covers (and actually
 displays the trace-cmd command it uses, as we'll see).
 
-To start a trace using kernelshark, first start kernelshark: ::
+To start a trace using kernelshark, first start kernelshark::
 
    root@sugarbay:~# kernelshark
 
 Then bring up the 'Capture' dialog by
-choosing from the kernelshark menu: ::
+choosing from the kernelshark menu::
 
    Capture | Record
 
@@ -1724,12 +1724,12 @@ ftrace Documentation
 --------------------
 
 The documentation for ftrace can be found in the kernel Documentation
-directory: ::
+directory::
 
    Documentation/trace/ftrace.txt
 
 The documentation for the trace event subsystem can also be found in the kernel
-Documentation directory: ::
+Documentation directory::
 
    Documentation/trace/events.txt
 
@@ -1784,7 +1784,7 @@ which it extracts from the open syscall's argstr.
 Normally, to execute this
 probe, you'd simply install systemtap on the system you want to probe,
 and directly run the probe on that system e.g. assuming the name of the
-file containing the above text is trace_open.stp: ::
+file containing the above text is trace_open.stp::
 
    # stap trace_open.stp
 
@@ -1825,7 +1825,7 @@ target, with arguments if necessary.
 In order to do this from a remote host, however, you need to have access
 to the build for the image you booted. The 'crosstap' script provides
 details on how to do this if you run the script on the host without
-having done a build: ::
+having done a build::
 
    $ crosstap root@192.168.1.88 trace_open.stp
 
@@ -1885,7 +1885,7 @@ Running a Script on a Target
 ----------------------------
 
 Once you've done that, you should be able to run a systemtap script on
-the target: ::
+the target::
 
    $ cd /path/to/yocto
    $ source oe-init-build-env
@@ -1903,17 +1903,17 @@ the target: ::
    You can also run generated QEMU images with a command like 'runqemu qemux86-64'
 
 Once you've done that, you can cd to whatever
-directory contains your scripts and use 'crosstap' to run the script: ::
+directory contains your scripts and use 'crosstap' to run the script::
 
    $ cd /path/to/my/systemap/script
    $ crosstap root@192.168.7.2 trace_open.stp
 
-If you get an error connecting to the target e.g.: ::
+If you get an error connecting to the target e.g.::
 
    $ crosstap root@192.168.7.2 trace_open.stp
    error establishing ssh connection on remote 'root@192.168.7.2'
 
-Try ssh'ing to the target and see what happens: ::
+Try ssh'ing to the target and see what happens::
 
    $ ssh root@192.168.7.2
 
@@ -2038,7 +2038,7 @@ tracing.
 Collecting and viewing a trace on the target (inside a shell)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-First, from the host, ssh to the target: ::
+First, from the host, ssh to the target::
 
    $ ssh -l root 192.168.1.47
    The authenticity of host '192.168.1.47 (192.168.1.47)' can't be established.
@@ -2047,30 +2047,30 @@ First, from the host, ssh to the target: ::
    Warning: Permanently added '192.168.1.47' (RSA) to the list of known hosts.
    root@192.168.1.47's password:
 
-Once on the target, use these steps to create a trace: ::
+Once on the target, use these steps to create a trace::
 
    root@crownbay:~# lttng create
    Spawning a session daemon
    Session auto-20121015-232120 created.
    Traces will be written in /home/root/lttng-traces/auto-20121015-232120
 
-Enable the events you want to trace (in this case all kernel events): ::
+Enable the events you want to trace (in this case all kernel events)::
 
    root@crownbay:~# lttng enable-event --kernel --all
    All kernel events are enabled in channel channel0
 
-Start the trace: ::
+Start the trace::
 
    root@crownbay:~# lttng start
    Tracing started for session auto-20121015-232120
 
 And then stop the trace after awhile or after running a particular workload that
-you want to trace: ::
+you want to trace::
 
    root@crownbay:~# lttng stop
    Tracing stopped for session auto-20121015-232120
 
-You can now view the trace in text form on the target: ::
+You can now view the trace in text form on the target::
 
    root@crownbay:~# lttng view
    [23:21:56.989270399] (+?.?????????) sys_geteuid: { 1 }, { }
@@ -2116,14 +2116,14 @@ You can now view the trace in text form on the target: ::
 
 You can now safely destroy the trace
 session (note that this doesn't delete the trace - it's still there in
-~/lttng-traces): ::
+~/lttng-traces)::
 
    root@crownbay:~# lttng destroy
    Session auto-20121015-232120 destroyed at /home/root
 
 Note that the trace is saved in a directory of the same name as returned by
 'lttng create', under the ~/lttng-traces directory (note that you can change this by
-supplying your own name to 'lttng create'): ::
+supplying your own name to 'lttng create')::
 
    root@crownbay:~# ls -al ~/lttng-traces
    drwxrwx---    3 root     root          1024 Oct 15 23:21 .
@@ -2139,18 +2139,18 @@ generated by the lttng-ust build.
 
 The 'hello' test program isn't installed on the rootfs by the lttng-ust
 build, so we need to copy it over manually. First cd into the build
-directory that contains the hello executable: ::
+directory that contains the hello executable::
 
    $ cd build/tmp/work/core2_32-poky-linux/lttng-ust/2.0.5-r0/git/tests/hello/.libs
 
-Copy that over to the target machine: ::
+Copy that over to the target machine::
 
    $ scp hello root@192.168.1.20:
 
 You now have the instrumented lttng 'hello world' test program on the
 target, ready to test.
 
-First, from the host, ssh to the target: ::
+First, from the host, ssh to the target::
 
    $ ssh -l root 192.168.1.47
    The authenticity of host '192.168.1.47 (192.168.1.47)' can't be established.
@@ -2159,35 +2159,35 @@ First, from the host, ssh to the target: ::
    Warning: Permanently added '192.168.1.47' (RSA) to the list of known hosts.
    root@192.168.1.47's password:
 
-Once on the target, use these steps to create a trace: ::
+Once on the target, use these steps to create a trace::
 
    root@crownbay:~# lttng create
    Session auto-20190303-021943 created.
    Traces will be written in /home/root/lttng-traces/auto-20190303-021943
 
-Enable the events you want to trace (in this case all userspace events): ::
+Enable the events you want to trace (in this case all userspace events)::
 
    root@crownbay:~# lttng enable-event --userspace --all
    All UST events are enabled in channel channel0
 
-Start the trace: ::
+Start the trace::
 
    root@crownbay:~# lttng start
    Tracing started for session auto-20190303-021943
 
-Run the instrumented hello world program: ::
+Run the instrumented hello world program::
 
    root@crownbay:~# ./hello
    Hello, World!
    Tracing... done.
 
 And then stop the trace after awhile or after running a particular workload
-that you want to trace: ::
+that you want to trace::
 
    root@crownbay:~# lttng stop
    Tracing stopped for session auto-20190303-021943
 
-You can now view the trace in text form on the target: ::
+You can now view the trace in text form on the target::
 
    root@crownbay:~# lttng view
    [02:31:14.906146544] (+?.?????????) hello:1424 ust_tests_hello:tptest: { cpu_id = 1 }, { intfield = 0, intfield2 = 0x0, longfield = 0, netintfield = 0, netintfieldhex = 0x0, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4,  seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2, boolfield = 1 }
@@ -2199,7 +2199,7 @@ You can now view the trace in text form on the target: ::
    .
 
 You can now safely destroy the trace session (note that this doesn't delete the
-trace - it's still there in ~/lttng-traces): ::
+trace - it's still there in ~/lttng-traces)::
 
    root@crownbay:~# lttng destroy
    Session auto-20190303-021943 destroyed at /home/root
@@ -2244,7 +2244,7 @@ Basic blktrace Usage
 --------------------
 
 To record a trace, simply run the 'blktrace' command, giving it the name
-of the block device you want to trace activity on: ::
+of the block device you want to trace activity on::
 
    root@crownbay:~# blktrace /dev/sdc
 
@@ -2265,7 +2265,7 @@ dumps them to userspace for blkparse to merge and sort later). ::
     Total:                  8660 events (dropped 0),      406 KiB data
 
 If you examine the files saved to disk, you see multiple files, one per CPU and
-with the device name as the first part of the filename: ::
+with the device name as the first part of the filename::
 
    root@crownbay:~# ls -al
    drwxr-xr-x    6 root     root          1024 Oct 27 22:39 .
@@ -2275,7 +2275,7 @@ with the device name as the first part of the filename: ::
 
 To view the trace events, simply invoke 'blkparse' in the directory
 containing the trace files, giving it the device name that forms the
-first part of the filenames: ::
+first part of the filenames::
 
    root@crownbay:~# blkparse sdc
 
@@ -2373,7 +2373,7 @@ Live Mode
 
 blktrace and blkparse are designed from the ground up to be able to
 operate together in a 'pipe mode' where the stdout of blktrace can be
-fed directly into the stdin of blkparse: ::
+fed directly into the stdin of blkparse::
 
    root@crownbay:~# blktrace /dev/sdc -o - | blkparse -i -
 
@@ -2386,7 +2386,7 @@ identify and capture conditions of interest.
 
 There's actually another blktrace command that implements the above
 pipeline as a single command, so the user doesn't have to bother typing
-in the above command sequence: ::
+in the above command sequence::
 
    root@crownbay:~# btrace /dev/sdc
 
@@ -2401,19 +2401,19 @@ the traced device at all by providing native support for sending all
 trace data over the network.
 
 To have blktrace operate in this mode, start blktrace on the target
-system being traced with the -l option, along with the device to trace: ::
+system being traced with the -l option, along with the device to trace::
 
    root@crownbay:~# blktrace -l /dev/sdc
    server: waiting for connections...
 
 On the host system, use the -h option to connect to the target system,
-also passing it the device to trace: ::
+also passing it the device to trace::
 
    $ blktrace -d /dev/sdc -h 192.168.1.43
    blktrace: connecting to 192.168.1.43
    blktrace: connected!
 
-On the target system, you should see this: ::
+On the target system, you should see this::
 
    server: connection from 192.168.1.43
 
@@ -2424,7 +2424,7 @@ In another shell, execute a workload you want to trace. ::
    linux-2.6.19.2.tar.b 100% \|*******************************\| 41727k 0:00:00 ETA
 
 When it's done, do a Ctrl-C on the host system to stop the
-trace: ::
+trace::
 
    ^C=== sdc ===
     CPU  0:                 7691 events,      361 KiB data
@@ -2432,7 +2432,7 @@ trace: ::
     Total:                 11800 events (dropped 0),      554 KiB data
 
 On the target system, you should also see a trace summary for the trace
-just ended: ::
+just ended::
 
    server: end of run for 192.168.1.43:sdc
    === sdc ===
@@ -2441,20 +2441,20 @@ just ended: ::
     Total:                 11800 events (dropped 0),      554 KiB data
 
 The blktrace instance on the host will
-save the target output inside a hostname-timestamp directory: ::
+save the target output inside a hostname-timestamp directory::
 
    $ ls -al
    drwxr-xr-x   10 root     root          1024 Oct 28 02:40 .
    drwxr-sr-x    4 root     root          1024 Oct 26 18:24 ..
    drwxr-xr-x    2 root     root          1024 Oct 28 02:40 192.168.1.43-2012-10-28-02:40:56
 
-cd into that directory to see the output files: ::
+cd into that directory to see the output files::
 
    $ ls -l
    -rw-r--r--    1 root     root        369193 Oct 28 02:44 sdc.blktrace.0
    -rw-r--r--    1 root     root        197278 Oct 28 02:44 sdc.blktrace.1
 
-And run blkparse on the host system using the device name: ::
+And run blkparse on the host system using the device name::
 
    $ blkparse sdc
 
@@ -2517,25 +2517,25 @@ userspace tools.
 
 To enable tracing for a given device, use /sys/block/xxx/trace/enable,
 where xxx is the device name. This for example enables tracing for
-/dev/sdc: ::
+/dev/sdc::
 
    root@crownbay:/sys/kernel/debug/tracing# echo 1 > /sys/block/sdc/trace/enable
 
 Once you've selected the device(s) you want
-to trace, selecting the 'blk' tracer will turn the blk tracer on: ::
+to trace, selecting the 'blk' tracer will turn the blk tracer on::
 
    root@crownbay:/sys/kernel/debug/tracing# cat available_tracers
    blk function_graph function nop
 
    root@crownbay:/sys/kernel/debug/tracing# echo blk > current_tracer
 
-Execute the workload you're interested in: ::
+Execute the workload you're interested in::
 
    root@crownbay:/sys/kernel/debug/tracing# cat /media/sdc/testfile.txt
 
 And look at the output (note here that we're using 'trace_pipe' instead of
 trace to capture this trace - this allows us to wait around on the pipe
-for data to appear): ::
+for data to appear)::
 
    root@crownbay:/sys/kernel/debug/tracing# cat trace_pipe
                cat-3587  [001] d..1  3023.276361:   8,32   Q   R 1699848 + 8 [cat]
@@ -2554,7 +2554,7 @@ for data to appear): ::
                cat-3587  [001] d..1  3023.276497:   8,32   m   N cfq3587 activate rq, drv=1
                cat-3587  [001] d..2  3023.276500:   8,32   D   R 1699848 + 8 [cat]
 
-And this turns off tracing for the specified device: ::
+And this turns off tracing for the specified device::
 
    root@crownbay:/sys/kernel/debug/tracing# echo 0 > /sys/block/sdc/trace/enable
 
@@ -2572,6 +2572,6 @@ section can be found here:
 
 The above manpages, along with manpages for the other blktrace utilities
 (btt, blkiomon, etc) can be found in the /doc directory of the blktrace
-tools git repo: ::
+tools git repo::
 
    $ git clone git://git.kernel.dk/blktrace.git

documentation/ref-manual/classes.rst

@@ -168,8 +168,7 @@ example use for this class.
    the "subpath" parameter limits the checkout to a specific subpath
    of the tree. Here is an example where ``${BP}`` is used so that the files
    are extracted into the subdirectory expected by the default value of
-   ``S``:
-   ::
+   ``S``::
 
            SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
 
@@ -221,8 +220,7 @@ each recipe you wish to blacklist. Specify the :term:`PN`
 value as a variable flag (varflag) and provide a reason, which is
 reported, if the package is requested to be built as the value. For
 example, if you want to blacklist a recipe called "exoticware", you add
-the following to your ``local.conf`` or distribution configuration:
-::
+the following to your ``local.conf`` or distribution configuration::
 
    INHERIT += "blacklist"
    PNBLACKLIST[exoticware] = "Not supported by our organization."
@@ -470,8 +468,7 @@ information about using ``devshell``.
 The ``devupstream`` class uses
 :term:`BBCLASSEXTEND` to add a variant of the
 recipe that fetches from an alternative URI (e.g. Git) instead of a
-tarball. Following is an example:
-::
+tarball. Following is an example::
 
    BBCLASSEXTEND = "devupstream:target"
    SRC_URI_class-devupstream = "git://git.example.com/example"
@@ -481,8 +478,7 @@ Adding the above statements to your recipe creates a variant that has
 :term:`DEFAULT_PREFERENCE` set to "-1".
 Consequently, you need to select the variant of the recipe to use it.
 Any development-specific adjustments can be done by using the
-``class-devupstream`` override. Here is an example:
-::
+``class-devupstream`` override. Here is an example::
 
    DEPENDS_append_class-devupstream = " gperf-native"
    do_configure_prepend_class-devupstream() {
@@ -501,29 +497,6 @@ Support for other version control systems such as Subversion is limited
 due to BitBake's automatic fetch dependencies (e.g.
 ``subversion-native``).
 
-.. _ref-classes-distutils:
-
-``distutils*.bbclass``
-======================
-
-The ``distutils*`` classes support recipes for Python version 2.x
-extensions, which are simple. These recipes usually only need to point
-to the source's archive and then inherit the proper class. Building is
-split into two methods depending on which method the module authors
-used.
-
--  Extensions that use an Autotools-based build system require Autotools
-   and the classes based on ``distutils`` in their recipes.
-
--  Extensions that use build systems based on ``distutils`` require the
-   ``distutils`` class in their recipes.
-
--  Extensions that use build systems based on ``setuptools`` require the
-   :ref:`setuptools <ref-classes-setuptools>` class in their recipes.
-
-The ``distutils-common-base`` class is required by some of the
-``distutils*`` classes to provide common Python2 support.
-
 .. _ref-classes-distutils3:
 
 ``distutils3*.bbclass``
@@ -542,15 +515,9 @@ used.
    ``distutils`` class in their recipes.
 
 -  Extensions that use build systems based on ``setuptools3`` require
-   the :ref:`setuptools3 <ref-classes-setuptools>` class in their
+   the :ref:`setuptools3 <ref-classes-setuptools3>` class in their
    recipes.
 
-The ``distutils3*`` classes either inherit their corresponding
-``distutils*`` class or replicate them using a Python3 version instead
-(e.g. ``distutils3-base`` inherits ``distutils-common-base``, which is
-the same as ``distutils-base`` but inherits ``python3native`` instead of
-``pythonnative``).
-
 .. _ref-classes-externalsrc:
 
 ``externalsrc.bbclass``
@@ -573,8 +540,7 @@ By default, this class expects the source code to support recipe builds
 that use the :term:`B` variable to point to the directory in
 which the OpenEmbedded build system places the generated objects built
 from the recipes. By default, the ``B`` directory is set to the
-following, which is separate from the source directory (``S``):
-::
+following, which is separate from the source directory (``S``)::
 
    ${WORKDIR}/${BPN}/{PV}/
 
@@ -610,8 +576,7 @@ be performed using the
    useradd
    class to add user and group configuration to a specific recipe.
 
-Here is an example that uses this class in an image recipe:
-::
+Here is an example that uses this class in an image recipe::
 
    inherit extrausers
    EXTRA_USERS_PARAMS = "\
@@ -624,8 +589,7 @@ Here is an example that uses this class in an image recipe:
        "
 
 Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
-passwords:
-::
+passwords::
 
    inherit extrausers
    EXTRA_USERS_PARAMS = "\
@@ -633,8 +597,7 @@ passwords:
        useradd -P tester01 tester-sue; \
        "
 
-Finally, here is an example that sets the root password to "1876*18":
-::
+Finally, here is an example that sets the root password to "1876*18"::
 
    inherit extrausers
    EXTRA_USERS_PARAMS = "\
@@ -896,8 +859,7 @@ system need to either inherit the ``icecc`` class or nobody should.
 At the distribution level, you can inherit the ``icecc`` class to be
 sure that all builders start with the same sstate signatures. After
 inheriting the class, you can then disable the feature by setting the
-:term:`ICECC_DISABLED` variable to "1" as follows:
-::
+:term:`ICECC_DISABLED` variable to "1" as follows::
 
    INHERIT_DISTRO_append = " icecc"
    ICECC_DISABLED ??= "1"
@@ -905,8 +867,7 @@ inheriting the class, you can then disable the feature by setting the
 This practice
 makes sure everyone is using the same signatures but also requires
 individuals that do want to use Icecream to enable the feature
-individually as follows in your ``local.conf`` file:
-::
+individually as follows in your ``local.conf`` file::
 
    ICECC_DISABLED = ""
 
@@ -954,8 +915,7 @@ types.
 
 By default, the :ref:`image <ref-classes-image>` class automatically
 enables the ``image_types`` class. The ``image`` class uses the
-``IMGCLASSES`` variable as follows:
-::
+``IMGCLASSES`` variable as follows::
 
    IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
    IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
@@ -997,8 +957,7 @@ during the :ref:`ref-tasks-rootfs` task, which optimizes
 the size of libraries contained in the image.
 
 By default, the class is enabled in the ``local.conf.template`` using
-the :term:`USER_CLASSES` variable as follows:
-::
+the :term:`USER_CLASSES` variable as follows::
 
    USER_CLASSES ?= "buildstats image-mklibs image-prelink"
 
@@ -1013,8 +972,7 @@ the dynamic linking of shared libraries to reduce executable startup
 time.
 
 By default, the class is enabled in the ``local.conf.template`` using
-the :term:`USER_CLASSES` variable as follows:
-::
+the :term:`USER_CLASSES` variable as follows::
 
    USER_CLASSES ?= "buildstats image-mklibs image-prelink"
 
@@ -1043,8 +1001,7 @@ configuration). However, to skip one or more checks in recipes, you
 should use :term:`INSANE_SKIP`. For example, to skip
 the check for symbolic link ``.so`` files in the main package of a
 recipe, add the following to the recipe. You need to realize that the
-package name override, in this example ``${PN}``, must be used:
-::
+package name override, in this example ``${PN}``, must be used::
 
    INSANE_SKIP_${PN} += "dev-so"
 
@@ -1052,7 +1009,7 @@ Please keep in mind that the QA checks
 exist in order to detect real or potential problems in the packaged
 output. So exercise caution when disabling these checks.
 
-The following list shows the tests you can list with the ``WARN_QA`` and
+Here are the tests you can list with the ``WARN_QA`` and
 ``ERROR_QA`` variables:
 
 -  ``already-stripped:`` Checks that produced binaries have not
@@ -1181,8 +1138,7 @@ The following list shows the tests you can list with the ``WARN_QA`` and
 
 -  ``invalid-packageconfig:`` Checks that no undefined features are
    being added to :term:`PACKAGECONFIG`. For
-   example, any name "foo" for which the following form does not exist:
-   ::
+   example, any name "foo" for which the following form does not exist::
 
       PACKAGECONFIG[foo] = "..."
 
@@ -1304,8 +1260,8 @@ The following list shows the tests you can list with the ``WARN_QA`` and
 
    .. note::
 
-      If you are not using runtime package management on your target
-      system, then you do not need to worry about this situation.
+      This is only relevant when you are using runtime package management
+      on your target system.
 
 -  ``xorg-driver-abi:`` Checks that all packages containing Xorg
    drivers have ABI dependencies. The ``xserver-xorg`` recipe provides
@@ -1665,8 +1621,7 @@ a couple different ways:
    .. note::
 
       When creating a recipe this way, the recipe name must follow this
-      naming convention:
-      ::
+      naming convention::
 
          myrecipe-native.bb
 
@@ -1674,8 +1629,7 @@ a couple different ways:
       Not using this naming convention can lead to subtle problems
       caused by existing code that depends on that naming convention.
 
--  Create or modify a target recipe that contains the following:
-   ::
+-  Create or modify a target recipe that contains the following::
 
       BBCLASSEXTEND = "native"
 
@@ -1706,8 +1660,7 @@ couple different ways:
    inherit statement in the recipe after all other inherit statements so
    that the ``nativesdk`` class is inherited last.
 
--  Create a ``nativesdk`` variant of any recipe by adding the following:
-   ::
+-  Create a ``nativesdk`` variant of any recipe by adding the following::
 
        BBCLASSEXTEND = "nativesdk"
 
@@ -1718,8 +1671,7 @@ couple different ways:
 
 .. note::
 
-   When creating a recipe, you must follow this naming convention:
-   ::
+   When creating a recipe, you must follow this naming convention::
 
            nativesdk-myrecipe.bb
 
@@ -1782,8 +1734,7 @@ before attempting to fetch it from the upstream specified in
 :term:`SRC_URI` within each recipe.
 
 To use this class, inherit it globally and specify
-:term:`SOURCE_MIRROR_URL`. Here is an example:
-::
+:term:`SOURCE_MIRROR_URL`. Here is an example::
 
    INHERIT += "own-mirrors"
    SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
@@ -2046,8 +1997,7 @@ established and then populates the SDK. After populating the SDK, the
 contains the cross-compiler and associated tooling, and the target,
 which contains a target root filesystem that is configured for the SDK
 usage. These two images reside in :term:`SDK_OUTPUT`,
-which consists of the following:
-::
+which consists of the following::
 
    ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs
    ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs
@@ -2138,13 +2088,13 @@ For information on setting up and running ptests, see the
 ":ref:`dev-manual/common-tasks:testing packages with ptest`"
 section in the Yocto Project Development Tasks Manual.
 
-.. _ref-classes-python-dir:
+.. _ref-classes-python3-dir:
 
-``python-dir.bbclass``
-======================
+``python3-dir.bbclass``
+=======================
 
-The ``python-dir`` class provides the base version, location, and site
-package location for Python.
+The ``python3-dir`` class provides the base version, location, and site
+package location for Python 3.
 
 .. _ref-classes-python3native:
 
@@ -2155,14 +2105,17 @@ The ``python3native`` class supports using the native version of Python
 3 built by the build system rather than support of the version provided
 by the build host.
 
-.. _ref-classes-pythonnative:
+.. _ref-classes-python3targetconfig:
 
-``pythonnative.bbclass``
-========================
+``python3targetconfig.bbclass``
+===============================
 
-When inherited by a recipe, the ``pythonnative`` class supports using
-the native version of Python built by the build system rather than using
-the version provided by the build host.
+The ``python3targetconfig`` class supports using the native version of Python
+3 built by the build system rather than support of the version provided
+by the build host, except that the configuration for the target machine
+is accessible (such as correct installation directories). This also adds a
+dependency on target ``python3``, so should only be used where appropriate
+in order to avoid unnecessarily lengthening builds.
 
 .. _ref-classes-qemu:
 
@@ -2206,8 +2159,7 @@ installed by ``libtool``. Removing these files results in them being
 absent from both the sysroot and target packages.
 
 If a recipe needs the ``.la`` files to be installed, then the recipe can
-override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows:
-::
+override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows::
 
    REMOVE_LIBTOOL_LA = "0"
 
@@ -2257,8 +2209,7 @@ recipe, enabling ``rm_work`` will potentially result in your changes to
 the source being lost. To exclude some recipes from having their work
 directories deleted by ``rm_work``, you can add the names of the recipe
 or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which
-can also be set in your ``local.conf`` file. Here is an example:
-::
+can also be set in your ``local.conf`` file. Here is an example::
 
    RM_WORK_EXCLUDE += "busybox glibc"
 
@@ -2323,22 +2274,13 @@ additional configuration options you want to pass SCons command line.
 The ``sdl`` class supports recipes that need to build software that uses
 the Simple DirectMedia Layer (SDL) library.
 
-.. _ref-classes-setuptools:
-
-``setuptools.bbclass``
-======================
-
-The ``setuptools`` class supports Python version 2.x extensions that use
-build systems based on ``setuptools``. If your recipe uses these build
-systems, the recipe needs to inherit the ``setuptools`` class.
-
 .. _ref-classes-setuptools3:
 
 ``setuptools3.bbclass``
 =======================
 
 The ``setuptools3`` class supports Python version 3.x extensions that
-use build systems based on ``setuptools3``. If your recipe uses these
+use build systems based on ``setuptools``. If your recipe uses these
 build systems, the recipe needs to inherit the ``setuptools3`` class.
 
 .. _ref-classes-sign_rpm:
@@ -2566,8 +2508,7 @@ You should set :term:`SYSTEMD_SERVICE` to the
 name of the service file. You should also use a package name override to
 indicate the package to which the value applies. If the value applies to
 the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here
-is an example from the connman recipe:
-::
+is an example from the connman recipe::
 
    SYSTEMD_SERVICE_${PN} = "connman.service"
 
@@ -2643,8 +2584,7 @@ The tests are commands that run on the target system over ``ssh``. Each
 test is written in Python and makes use of the ``unittest`` module.
 
 The ``testimage.bbclass`` runs tests on an image when called using the
-following:
-::
+following::
 
    $ bitbake -c testimage image
 
@@ -2663,8 +2603,7 @@ section in the Yocto Project Development Tasks Manual.
 
 This class supports running automated tests against software development
 kits (SDKs). The ``testsdk`` class runs tests on an SDK when called
-using the following:
-::
+using the following::
 
    $ bitbake -c testsdk image
 
@@ -2719,8 +2658,7 @@ the environment for installed SDKs.
 The ``typecheck`` class provides support for validating the values of
 variables set at the configuration level against their defined types.
 The OpenEmbedded build system allows you to define the type of a
-variable using the "type" varflag. Here is an example:
-::
+variable using the "type" varflag. Here is an example::
 
    IMAGE_FEATURES[type] = "list"
 
@@ -2730,14 +2668,12 @@ variable using the "type" varflag. Here is an example:
 ========================
 
 The ``uboot-config`` class provides support for U-Boot configuration for
-a machine. Specify the machine in your recipe as follows:
-::
+a machine. Specify the machine in your recipe as follows::
 
    UBOOT_CONFIG ??= <default>
    UBOOT_CONFIG[foo] = "config,images"
 
-You can also specify the machine using this method:
-::
+You can also specify the machine using this method::
 
    UBOOT_MACHINE = "config"
 

documentation/ref-manual/devtool-reference.rst

@@ -22,8 +22,7 @@ Getting Help
 
 The ``devtool`` command line is organized similarly to Git in that it
 has a number of sub-commands for each function. You can run
-``devtool --help`` to see all the commands:
-::
+``devtool --help`` to see all the commands::
 
    $ devtool -h
    NOTE: Starting bitbake server...
@@ -79,8 +78,7 @@ has a number of sub-commands for each function. You can run
 
 As directed in the general help output, you can
 get more syntax on a specific command by providing the command name and
-using "--help":
-::
+using "--help"::
 
    $ devtool add --help
    NOTE: Starting bitbake server...
@@ -172,14 +170,13 @@ you. The source files the recipe uses should exist in an external area.
 
 The following example creates and adds a new recipe named ``jackson`` to
 a workspace layer the tool creates. The source code built by the recipes
-resides in ``/home/user/sources/jackson``:
-::
+resides in ``/home/user/sources/jackson``::
 
    $ devtool add jackson /home/user/sources/jackson
 
 If you add a recipe and the workspace layer does not exist, the command
-creates the layer and populates it as described in "`The Workspace Layer
-Structure <#devtool-the-workspace-layer-structure>`__" section.
+creates the layer and populates it as described in
+":ref:`devtool-the-workspace-layer-structure`" section.
 
 Running ``devtool add`` when the workspace layer exists causes the tool
 to add the recipe, append files, and source files into the existing
@@ -201,8 +198,7 @@ unpacking files from a remote URI. In some cases, you might want to
 specify a source revision by branch, tag, or commit hash. You can
 specify these options when using the ``devtool add`` command:
 
--  To specify a source branch, use the ``--srcbranch`` option:
-   ::
+-  To specify a source branch, use the ``--srcbranch`` option::
 
       $ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson /home/user/sources/jackson
 
@@ -210,8 +206,7 @@ specify these options when using the ``devtool add`` command:
    branch.
 
 -  To specify a specific tag or commit hash, use the ``--srcrev``
-   option:
-   ::
+   option::
 
       $ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/user/sources/jackson
       $ devtool add --srcrev some_commit_hash /home/user/sources/jackson
@@ -269,8 +264,7 @@ The ``devtool modify`` command extracts the source for a recipe, sets it
 up as a Git repository if the source had not already been fetched from
 Git, checks out a branch for development, and applies any patches from
 the recipe as commits on top. You can use the following command to
-checkout the source files:
-::
+checkout the source files::
 
    $ devtool modify recipe
 
@@ -309,8 +303,7 @@ compile, and test the code.
 
 When you are satisfied with the results and you have committed your
 changes to the Git repository, you can then run the
-``devtool update-recipe`` to create the patches and update the recipe:
-::
+``devtool update-recipe`` to create the patches and update the recipe::
 
    $ devtool update-recipe recipe
 
@@ -321,8 +314,7 @@ Often, you might want to apply customizations made to your software in
 your own layer rather than apply them to the original recipe. If so, you
 can use the ``-a`` or ``--append`` option with the
 ``devtool update-recipe`` command. These options allow you to specify
-the layer into which to write an append file:
-::
+the layer into which to write an append file::
 
    $ devtool update-recipe recipe -a base-layer-directory
 
@@ -358,8 +350,7 @@ particular recipe.
       recipe's latest version tag.
 
 As with all ``devtool`` commands, you can get help on the individual
-command:
-::
+command::
 
    $ devtool check-upgrade-status -h
    NOTE: Starting bitbake server...
@@ -462,8 +453,7 @@ files have been modified, the command preserves the modified files in a
 separate "attic" subdirectory under the workspace layer.
 
 Here is an example that resets the workspace directory that contains the
-``mtr`` recipe:
-::
+``mtr`` recipe::
 
    $ devtool reset mtr
    NOTE: Cleaning sysroot for recipe mtr...
@@ -482,8 +472,7 @@ Use the ``devtool build`` command to build your recipe. The
 When you use the ``devtool build`` command, you must supply the root
 name of the recipe (i.e. do not provide versions, paths, or extensions).
 You can use either the "-s" or the "--disable-parallel-make" options to
-disable parallel makes during the build. Here is an example:
-::
+disable parallel makes during the build. Here is an example::
 
    $ devtool build recipe
 
@@ -499,8 +488,7 @@ device for testing. For proper integration into a final image, you need
 to edit your custom image recipe appropriately.
 
 When you use the ``devtool build-image`` command, you must supply the
-name of the image. This command has no command line options:
-::
+name of the image. This command has no command line options::
 
    $ devtool build-image image
 
@@ -510,8 +498,7 @@ Deploying Your Software on the Target Machine
 =============================================
 
 Use the ``devtool deploy-target`` command to deploy the recipe's build
-output to the live target machine:
-::
+output to the live target machine::
 
    $ devtool deploy-target recipe target
 
@@ -582,15 +569,13 @@ new workspace layer, it is populated with the ``README`` file and the
 ``conf`` directory only.
 
 The following example creates a new workspace layer in your current
-working and by default names the workspace layer "workspace":
-::
+working and by default names the workspace layer "workspace"::
 
    $ devtool create-workspace
 
 You can create a workspace layer anywhere by supplying a pathname with
 the command. The following command creates a new workspace layer named
-"new-workspace":
-::
+"new-workspace"::
 
    $ devtool create-workspace /home/scottrif/new-workspace
 
@@ -603,15 +588,13 @@ Use the ``devtool status`` command to list the recipes currently in your
 workspace. Information includes the paths to their respective external
 source trees.
 
-The ``devtool status`` command has no command-line options:
-::
+The ``devtool status`` command has no command-line options::
 
    $ devtool status
 
 Following is sample output after using
 :ref:`devtool add <ref-manual/devtool-reference:adding a new recipe to the workspace layer>`
-to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory:
-::
+to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory::
 
    $ devtool status
    mtr:/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)

documentation/ref-manual/faq.rst

@@ -16,7 +16,7 @@ first before being pulled back into Poky. This practice benefits both
 projects immediately.
 
 **Q:** My development system does not meet the required Git, tar, and
-Python versions. In particular, I do not have Python 3.5.0 or greater.
+Python versions. In particular, I do not have Python &MIN_PYTHON_VERSION; or greater.
 Can I still use the Yocto Project?
 
 **A:** You can get the required tools on your host development system a
@@ -125,7 +125,7 @@ file.
 
 Following is the applicable code for setting various proxy types in the
 ``.wgetrc`` file. By default, these settings are disabled with comments.
-To use them, remove the comments: ::
+To use them, remove the comments::
 
    # You can set the default proxies for Wget to use for http, https, and ftp.
    # They will override the value in the environment.
@@ -209,8 +209,7 @@ section in the Yocto Project Development Tasks Manual.
 **A:** You need to create a form factor file as described in the
 ":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in
 the Yocto Project Board Support Packages (BSP) Developer's Guide. Set
-the ``HAVE_TOUCHSCREEN`` variable equal to one as follows:
-::
+the ``HAVE_TOUCHSCREEN`` variable equal to one as follows::
 
    HAVE_TOUCHSCREEN=1
 
@@ -224,7 +223,7 @@ to add a BSP-specific netbase that includes an interfaces file. See the
 the Yocto Project Board Support Packages (BSP) Developer's Guide for
 information on creating these types of miscellaneous recipe files.
 
-For example, add the following files to your layer: ::
+For example, add the following files to your layer::
 
    meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
    meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
@@ -300,7 +299,7 @@ fail.
 
 As an example, you could add a specific server for the build system to
 attempt before any others by adding something like the following to the
-``local.conf`` configuration file: ::
+``local.conf`` configuration file::
 
    PREMIRRORS_prepend = "\
        git://.*/.* http://www.yoctoproject.org/sources/ \n \
@@ -313,8 +312,7 @@ HTTPS requests and direct them to the ``http://`` sources mirror. You
 can use ``file://`` URLs to point to local directories or network shares
 as well.
 
-Aside from the previous technique, these options also exist:
-::
+Aside from the previous technique, these options also exist::
 
    BB_NO_NETWORK = "1"
 
@@ -322,8 +320,7 @@ This statement tells BitBake to issue an error
 instead of trying to access the Internet. This technique is useful if
 you want to ensure code builds only from local sources.
 
-Here is another technique:
-::
+Here is another technique::
 
    BB_FETCH_PREMIRRORONLY = "1"
 
@@ -331,8 +328,7 @@ This statement
 limits the build system to pulling source from the ``PREMIRRORS`` only.
 Again, this technique is useful for reproducing builds.
 
-Here is another technique:
-::
+Here is another technique::
 
    BB_GENERATE_MIRROR_TARBALLS = "1"
 
@@ -343,7 +339,7 @@ however, the technique can simply waste time during the build.
 
 Finally, consider an example where you are behind an HTTP-only firewall.
 You could make the following changes to the ``local.conf`` configuration
-file as long as the ``PREMIRRORS`` server is current: ::
+file as long as the ``PREMIRRORS`` server is current::
 
    PREMIRRORS_prepend = "\
        ftp://.*/.* http://www.yoctoproject.org/sources/ \n \

documentation/ref-manual/features.rst

@@ -26,8 +26,7 @@ One method you can use to determine which recipes are checking to see if
 a particular feature is contained or not is to ``grep`` through the
 :term:`Metadata` for the feature. Here is an example that
 discovers the recipes whose build is potentially changed based on a
-given feature:
-::
+given feature::
 
    $ cd poky
    $ git grep 'contains.*MACHINE_FEATURES.*feature'
@@ -197,7 +196,7 @@ you can add several different predefined packages such as development
 utilities or packages with debug information needed to investigate
 application problems or profile applications.
 
-The following image features are available for all images:
+Here are the image features available for all images:
 
 -  *allow-empty-password:* Allows Dropbear and OpenSSH to accept root
    logins and logins from accounts having an empty password string.

documentation/ref-manual/images.rst

@@ -18,8 +18,7 @@ image you want.
    are going to build an image using non-GPLv3 and similarly licensed
    components, you must make the following changes in the ``local.conf``
    file before using the BitBake command to build the minimal or base
-   image:
-   ::
+   image::
 
            1. Comment out the EXTRA_IMAGE_FEATURES line
            2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
@@ -27,7 +26,7 @@ image you want.
 
 From within the ``poky`` Git repository, you can use the following
 command to display the list of directories within the :term:`Source Directory`
-that contain image recipe files: ::
+that contain image recipe files::
 
    $ ls meta*/recipes*/images/*.bb
 

documentation/ref-manual/kickstart.rst

@@ -30,8 +30,7 @@ Command: part or partition
 ==========================
 
 Either of these commands creates a partition on the system and uses the
-following syntax:
-::
+following syntax::
 
    part [mntpoint]
    partition [mntpoint]
@@ -59,8 +58,7 @@ must also provide one of the ``--ondrive``, ``--ondisk``, or
    versions of these application are currently excluded.
 
 Here is an example that uses "/" as the mountpoint. The command uses
-``--ondisk`` to force the partition onto the ``sdb`` disk:
-::
+``--ondisk`` to force the partition onto the ``sdb`` disk::
 
       part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
 

documentation/ref-manual/migration-1.3.rst

@@ -1,10 +1,10 @@
 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
 
-Moving to the Yocto Project 1.3 Release
-=======================================
+Moving to the Yocto Project 1.3 Release (danny)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.3 Release from the prior release.
+Project 1.3 Release (codename "danny") from the prior release.
 
 .. _1.3-local-configuration:
 
@@ -29,7 +29,7 @@ location (either local or remote) and then point to it in
 :term:`SSTATE_MIRRORS`, you need to append "PATH"
 to the end of the mirror URL so that the path used by BitBake before the
 mirror substitution is appended to the path used to access the mirror.
-Here is an example: ::
+Here is an example::
 
    SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
 
@@ -181,14 +181,13 @@ Linux Kernel Naming
 -------------------
 
 The naming scheme for kernel output binaries has been changed to now
-include :term:`PE` as part of the filename:
-::
+include :term:`PE` as part of the filename::
 
    KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
 
 Because the ``PE`` variable is not set by default, these binary files
 could result with names that include two dash characters. Here is an
-example: ::
+example::
 
    bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
 

documentation/ref-manual/migration-1.4.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.4 Release
-=======================================
+Moving to the Yocto Project 1.4 Release (dylan)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.4 Release from the prior release.
+Project 1.4 Release (codename "dylan") from the prior release.
 
 .. _migration-1.4-bitbake:
 
@@ -40,8 +40,7 @@ Differences include the following:
 
 -  *Shared State Code:* The shared state code has been optimized to
    avoid running unnecessary tasks. For example, the following no longer
-   populates the target sysroot since that is not necessary:
-   ::
+   populates the target sysroot since that is not necessary::
 
       $ bitbake -c rootfs some-image
 
@@ -136,8 +135,7 @@ Target Package Management with RPM
 If runtime package management is enabled and the RPM backend is
 selected, Smart is now installed for package download, dependency
 resolution, and upgrades instead of Zypper. For more information on how
-to use Smart, run the following command on the target:
-::
+to use Smart, run the following command on the target::
 
    smart --help
 

documentation/ref-manual/migration-1.5.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.5 Release
-=======================================
+Moving to the Yocto Project 1.5 Release (dora)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.5 Release from the prior release.
+Project 1.5 Release (codename "dora") from the prior release.
 
 .. _migration-1.5-host-dependency-changes:
 
@@ -298,7 +298,7 @@ Removed and Renamed Recipes
 -  ``libtool-nativesdk`` has been renamed to ``nativesdk-libtool``.
 
 -  ``tinylogin`` has been removed. It has been replaced by a suid
-   portion of Busybox. See the "`BusyBox <#busybox>`__"
+   portion of Busybox. See the ":ref:`migration-1.5-busybox`"
    section for more information.
 
 -  ``external-python-tarball`` has been renamed to

documentation/ref-manual/migration-1.6.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.6 Release
-=======================================
+Moving to the Yocto Project 1.6 Release (daisy)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.6 Release from the prior release.
+Project 1.6 Release (codename "daisy") from the prior release.
 
 .. _migration-1.6-archiver-class:
 
@@ -53,8 +53,7 @@ Matching Branch Requirement for Git Fetching
 When fetching source from a Git repository using
 :term:`SRC_URI`, BitBake will now validate the
 :term:`SRCREV` value against the branch. You can specify
-the branch using the following form:
-::
+the branch using the following form::
 
       SRC_URI = "git://server.name/repository;branch=branchname"
 
@@ -207,7 +206,7 @@ functions to call and not arbitrary shell commands:
 
 For
 migration purposes, you can simply wrap shell commands in a shell
-function and then call the function. Here is an example: ::
+function and then call the function. Here is an example::
 
    my_postprocess_function() {
       echo "hello" > ${IMAGE_ROOTFS}/hello.txt
@@ -248,8 +247,7 @@ the ``autotools`` or ``autotools_stage``\ classes.
 
 ``qemu-native`` now builds without SDL-based graphical output support by
 default. The following additional lines are needed in your
-``local.conf`` to enable it:
-::
+``local.conf`` to enable it::
 
    PACKAGECONFIG_pn-qemu-native = "sdl"
    ASSUME_PROVIDED += "libsdl-native"

documentation/ref-manual/migration-1.7.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.7 Release
-=======================================
+Moving to the Yocto Project 1.7 Release (dizzy)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.7 Release from the prior release.
+Project 1.7 Release (codename "dizzy") from the prior release.
 
 .. _migration-1.7-changes-to-setting-qemu-packageconfig-options:
 
@@ -15,8 +15,7 @@ optional features. The method used to set defaults for these options
 means that existing ``local.conf`` files will need to be modified to
 append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu``
 instead of setting it. In other words, to enable graphical output for
-QEMU, you should now have these lines in ``local.conf``:
-::
+QEMU, you should now have these lines in ``local.conf``::
 
    PACKAGECONFIG_append_pn-qemu-native = " sdl"
    PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
@@ -80,8 +79,7 @@ disable the scripts due to the scripts previously requiring error-prone
 path substitution. Software that links against these libraries using
 these scripts should use the much more robust ``pkg-config`` instead.
 The list of recipes changed in this version (and their configuration
-scripts) is as follows:
-::
+scripts) is as follows::
 
    directfb (directfb-config)
    freetype (freetype-config)

documentation/ref-manual/migration-1.8.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.8 Release
-=======================================
+Moving to the Yocto Project 1.8 Release (fido)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.8 Release from the prior release.
+Project 1.8 Release (codename "fido") from the prior release.
 
 .. _migration-1.8-removed-recipes:
 
@@ -56,7 +56,7 @@ you can now remove them.
 Additionally, a ``bluetooth`` class has been added to make selection of
 the appropriate bluetooth support within a recipe a little easier. If
 you wish to make use of this class in a recipe, add something such as
-the following: ::
+the following::
 
    inherit bluetooth
    PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}"
@@ -84,7 +84,7 @@ where the ``linux.inc`` file in ``meta-oe`` was updated.
 
 Recipes that rely on the kernel source code and do not inherit the
 module classes might need to add explicit dependencies on the
-``do_shared_workdir`` kernel task, for example: ::
+``do_shared_workdir`` kernel task, for example::
 
    do_configure[depends] += "virtual/kernel:do_shared_workdir"
 
@@ -131,7 +131,7 @@ One of the improvements is to attempt to run "make clean" during the
 ``do_configure`` task if a ``Makefile`` exists. Some software packages
 do not provide a working clean target within their make files. If you
 have such recipes, you need to set
-:term:`CLEANBROKEN` to "1" within the recipe, for example: ::
+:term:`CLEANBROKEN` to "1" within the recipe, for example::
 
    CLEANBROKEN = "1"
 

documentation/ref-manual/migration-2.0.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.0 Release
-=======================================
+Moving to the Yocto Project 2.0 Release (jethro)
+================================================
 
 This section provides migration information for moving to the Yocto
-Project 2.0 Release from the prior release.
+Project 2.0 Release (codename "jethro") from the prior release.
 
 .. _migration-2.0-gcc-5:
 
@@ -25,8 +25,7 @@ and the porting guide at
 https://gcc.gnu.org/gcc-5/porting_to.html.
 
 Alternatively, you can switch back to GCC 4.9 or 4.8 by setting
-``GCCVERSION`` in your configuration, as follows:
-::
+``GCCVERSION`` in your configuration, as follows::
 
    GCCVERSION = "4.9%"
 
@@ -91,8 +90,7 @@ unlikely to require any changes to Metadata. However, these minor
 changes in behavior exist:
 
 -  All potential overrides are now visible in the variable history as
-   seen when you run the following:
-   ::
+   seen when you run the following::
 
       $ bitbake -e
 
@@ -200,8 +198,7 @@ changes.
 
 Additionally, work directories for old versions of recipes are now
 pruned. If you wish to disable pruning old work directories, you can set
-the following variable in your configuration:
-::
+the following variable in your configuration::
 
    SSTATE_PRUNE_OBSOLETEWORKDIR = "0"
 

documentation/ref-manual/migration-2.1.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.1 Release
-=======================================
+Moving to the Yocto Project 2.1 Release (krogoth)
+=================================================
 
 This section provides migration information for moving to the Yocto
-Project 2.1 Release from the prior release.
+Project 2.1 Release (codename "krogoth") from the prior release.
 
 .. _migration-2.1-variable-expansion-in-python-functions:
 
@@ -42,8 +42,7 @@ defaulted to False if not specified. Now, however, no default exists so
 one must be specified. You must change any ``getVar()`` calls that do
 not specify the final expand parameter to calls that do specify the
 parameter. You can run the following ``sed`` command at the base of a
-layer to make this change:
-::
+layer to make this change::
 
    sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
    sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
@@ -179,9 +178,8 @@ The following recipes have been removed in the 2.1 release:
 
 -  ``python-pygtk``: Recipe became obsolete.
 
--  ``adt-installer``: Recipe became obsolete. See the "`ADT
-   Removed <#adt-removed>`__" section for more
-   information.
+-  ``adt-installer``: Recipe became obsolete. See the
+   ":ref:`ref-manual/migration-2.1:adt removed`" section for more information.
 
 .. _migration-2.1-class-changes:
 
@@ -286,8 +284,7 @@ The following changes have been made for the Poky distribution:
    Any recipe that needs to opt-out of having the "--disable-static"
    option specified on the configure command line either because it is
    not a supported option for the configure script or because static
-   libraries are needed should set the following variable:
-   ::
+   libraries are needed should set the following variable::
 
       DISABLE_STATIC = ""
 
@@ -370,8 +367,7 @@ These additional changes exist:
 -  Previously, the following list of packages were removed if
    package-management was not in
    :term:`IMAGE_FEATURES`, regardless of any
-   dependencies:
-   ::
+   dependencies::
 
       update-rc.d
       base-passwd

documentation/ref-manual/migration-2.2.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.2 Release
-=======================================
+Moving to the Yocto Project 2.2 Release (morty)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.2 Release from the prior release.
+Project 2.2 Release (codename "morty") from the prior release.
 
 .. _migration-2.2-minimum-kernel-version:
 
@@ -144,8 +144,7 @@ The new ``runqemu`` is a Python script. Machine knowledge is no longer
 hardcoded into ``runqemu``. You can choose to use the ``qemuboot``
 configuration file to define the BSP's own arguments and to make it
 bootable with ``runqemu``. If you use a configuration file, use the
-following form:
-::
+following form::
 
    image-name-machine.qemuboot.conf
 
@@ -160,8 +159,7 @@ rootfs). QEMU boot arguments can be set in BSP's configuration file and
 the ``qemuboot`` class will save them to ``qemuboot.conf``.
 
 If you want to use ``runqemu`` without a configuration file, use the
-following command form:
-::
+following command form::
 
    $ runqemu machine rootfs kernel [options]
 
@@ -179,7 +177,7 @@ Supported machines are as follows:
 
 Consider the
 following example, which uses the ``qemux86-64`` machine, provides a
-root filesystem, provides an image, and uses the ``nographic`` option: ::
+root filesystem, provides an image, and uses the ``nographic`` option::
 
    $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic
 
@@ -244,8 +242,7 @@ recipes. You need to fix these recipes so that they use the expected
 ``LDFLAGS``. Depending on how the software is built, the build system
 used by the software (e.g. a Makefile) might need to be patched.
 However, sometimes making this fix is as simple as adding the following
-to the recipe:
-::
+to the recipe::
 
    TARGET_CC_ARCH += "${LDFLAGS}"
 
@@ -258,8 +255,7 @@ The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the
 :term:`KERNEL_IMAGETYPE` variable to create the
 image's base name. Because the OpenEmbedded build system can now build
 multiple kernel image types, this part of the kernel image base name as
-been removed leaving only the following:
-::
+been removed leaving only the following::
 
    KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
 
@@ -367,8 +363,8 @@ The following recipes have been removed:
 
 -  ``sato-icon-theme``: Became obsolete.
 
--  ``swabber-native``: Swabber has been removed. See the `entry on
-   Swabber <#swabber-has-been-removed>`__.
+-  ``swabber-native``: Swabber has been removed. See the :ref:`entry on
+   Swabber <ref-manual/migration-2.2:swabber has been removed>`.
 
 -  ``tslib``: No longer needed and has been moved to ``meta-oe``.
 
@@ -393,8 +389,8 @@ The following classes have been removed:
 
 -  ``sip``: Mostly unused.
 
--  ``swabber``: See the `entry on
-   Swabber <#swabber-has-been-removed>`__.
+-  ``swabber``: See the :ref:`entry on
+   Swabber <ref-manual/migration-2.2:swabber has been removed>`.
 
 .. _migration-2.2-minor-packaging-changes:
 
@@ -426,7 +422,7 @@ The following miscellaneous changes have occurred:
    :term:`SRCREV` by default when fetching from a Git
    repository. You can override this in either case to use
    ``${``\ :term:`AUTOREV`\ ``}`` instead by using the
-   ``-a`` or ``DASHDASHautorev`` command-line option
+   ``-a`` or ``--autorev`` command-line option
 
 -  ``distcc``: GTK+ UI is now disabled by default.
 

documentation/ref-manual/migration-2.3.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.3 Release
-=======================================
+Moving to the Yocto Project 2.3 Release (pyro)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.3 Release from the prior release.
+Project 2.3 Release (codename "pyro") from the prior release.
 
 .. _migration-2.3-recipe-specific-sysroots:
 
@@ -114,8 +114,7 @@ Changes to Scripts
 The following changes to scripts took place:
 
 -  ``oe-find-native-sysroot``: The usage for the
-   ``oe-find-native-sysroot`` script has changed to the following:
-   ::
+   ``oe-find-native-sysroot`` script has changed to the following::
 
       $ . oe-find-native-sysroot recipe
 
@@ -124,8 +123,7 @@ The following changes to scripts took place:
    was not necessary to provide the script with the command.
 
 -  ``oe-run-native``: The usage for the ``oe-run-native`` script has
-   changed to the following:
-   ::
+   changed to the following::
 
       $ oe-run-native native_recipe tool
 
@@ -453,14 +451,11 @@ The following miscellaneous changes have occurred:
    tools.
 
 -  The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig"
-   ``DISTRO_FEATURES`` feature. Distributions that previously set:
-   ::
+   ``DISTRO_FEATURES`` feature. Distributions that previously set::
 
       USE_LDCONFIG = "0"
 
-   should now instead use the following:
-
-   ::
+   should now instead use the following::
 
       DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig"
 
@@ -478,8 +473,7 @@ The following miscellaneous changes have occurred:
    order to allow module packages from multiple kernel versions to
    co-exist on a target system. If you wish to return to the previous
    naming scheme that does not include the version suffix, use the
-   following:
-   ::
+   following::
 
       KERNEL_MODULE_PACKAGE_SUFFIX = ""
 

documentation/ref-manual/migration-2.4.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.4 Release
-=======================================
+Moving to the Yocto Project 2.4 Release (rocko)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.4 Release from the prior release.
+Project 2.4 Release (codename "rocko") from the prior release.
 
 .. _migration-2.4-memory-resident-mode:
 

documentation/ref-manual/migration-2.5.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.5 Release
-=======================================
+Moving to the Yocto Project 2.5 Release (sumo)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.5 Release from the prior release.
+Project 2.5 Release (codename "sumo") from the prior release.
 
 .. _migration-2.5-packaging-changes:
 
@@ -138,13 +138,11 @@ The following are BitBake changes:
    tree" tasks have been removed (e.g. ``fetchall``, ``checkuriall``,
    and the ``*all`` tasks provided by the ``distrodata`` and
    ``archiver`` classes). There is a BitBake option to complete this for
-   any arbitrary task. For example:
-   ::
+   any arbitrary task. For example::
 
       bitbake <target> -c fetchall
 
-   should now be replaced with:
-   ::
+   should now be replaced with::
 
       bitbake <target> --runall=fetch
 
@@ -169,7 +167,7 @@ one of the packages provided by the Python recipe. You can no longer run
 ``bitbake python-foo`` or have a
 :term:`DEPENDS` on ``python-foo``,
 but doing either of the following causes the package to work as
-expected: ::
+expected::
 
    IMAGE_INSTALL_append = " python-foo"
 

documentation/ref-manual/migration-2.6.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.6 Release
-=======================================
+Moving to the Yocto Project 2.6 Release (thud)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.6 Release from the prior release.
+Project 2.6 Release (codename "thud") from the prior release.
 
 .. _migration-2.6-gcc-changes:
 
@@ -110,7 +110,7 @@ upon the older ``*proto`` recipes need to be changed to depend on the
 newer ``xorgproto`` recipe instead.
 
 For names of recipes removed because of this repository change, see the
-`Removed Recipes <#removed-recipes>`__ section.
+:ref:`ref-manual/migration-2.6:removed recipes` section.
 
 .. _migration-2.6-distutils-distutils3-fetching-dependencies:
 
@@ -118,7 +118,7 @@ For names of recipes removed because of this repository change, see the
 ---------------------------------------------------------------------------------------------------
 
 Previously, it was possible for Python recipes that inherited the
-:ref:`distutils <ref-classes-distutils>` and
+``distutils`` and
 :ref:`distutils3 <ref-classes-distutils3>` classes to fetch code
 during the :ref:`ref-tasks-configure` task to satisfy
 dependencies mentioned in ``setup.py`` if those dependencies were not
@@ -161,13 +161,11 @@ The following changes have been made:
    allows easier and more direct changes.
 
    The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf``
-   configuration file as follows:
-   ::
+   configuration file as follows::
 
       IMAGE_VERSION_SUFFIX = "-${DATETIME}"
 
--  Several variables have changed names for consistency:
-   ::
+-  Several variables have changed names for consistency::
 
       Old Variable Name             New Variable Name
       ========================================================
@@ -292,8 +290,7 @@ avoids the ``systemd`` recipe from becoming machine-specific for cases
 where machine-specific configurations need to be applied (e.g. for
 ``qemu*`` machines).
 
-Currently, the new recipe packages the following files:
-::
+Currently, the new recipe packages the following files::
 
    ${sysconfdir}/machine-id
    ${sysconfdir}/systemd/coredump.conf
@@ -393,8 +390,7 @@ If you wish to disable Python profile-guided optimization regardless of
 the value of ``MACHINE_FEATURES``, then ensure that
 :term:`PACKAGECONFIG` for the ``python3`` recipe
 does not contain "pgo". You could accomplish the latter using the
-following at the configuration level:
-::
+following at the configuration level::
 
    PACKAGECONFIG_remove_pn-python3 = "pgo"
 
@@ -411,8 +407,7 @@ The following miscellaneous changes occurred:
 -  Default to using the Thumb-2 instruction set for armv7a and above. If
    you have any custom recipes that build software that needs to be
    built with the ARM instruction set, change the recipe to set the
-   instruction set as follows:
-   ::
+   instruction set as follows::
 
       ARM_INSTRUCTION_SET = "arm"
 

documentation/ref-manual/migration-2.7.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.7 Release
-=======================================
+Moving to the Yocto Project 2.7 Release (warrior)
+=================================================
 
 This section provides migration information for moving to the Yocto
-Project 2.7 Release from the prior release.
+Project 2.7 Release (codename "warrior") from the prior release.
 
 .. _migration-2.7-bitbake-changes:
 

documentation/ref-manual/migration-3.0.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 3.0 Release
-=======================================
+Moving to the Yocto Project 3.0 Release (zeus)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 3.0 Release from the prior release.
+Project 3.0 Release (codename "zeus") from the prior release.
 
 .. _migration-3.0-init-system-selection:
 

documentation/ref-manual/migration-3.1.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 3.1 Release
-=======================================
+Moving to the Yocto Project 3.1 Release (dunfell)
+=================================================
 
 This section provides migration information for moving to the Yocto
-Project 3.1 Release from the prior release.
+Project 3.1 Release (codename "dunfell") from the prior release.
 
 .. _migration-3.1-minimum-system-requirements:
 
@@ -71,8 +71,7 @@ when building a simple image such as core-image-minimal. If you do not
 need runtime tests enabled for core components, then it is recommended
 that you remove "ptest" from
 :term:`DISTRO_FEATURES` to save a significant
-amount of build time e.g. by adding the following in your configuration:
-::
+amount of build time e.g. by adding the following in your configuration::
 
    DISTRO_FEATURES_remove = "ptest"
 
@@ -179,12 +178,12 @@ parameter instead of the earlier ``name`` which overlapped with the
 generic ``name`` parameter. All recipes using the npm fetcher will need
 to be changed as a result.
 
-An example of the new scheme: ::
+An example of the new scheme::
 
    SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \
               npmsw://${THISDIR}/npm-shrinkwrap.json"
 
-Another example where the sources are fetched from git rather than an npm repository: ::
+Another example where the sources are fetched from git rather than an npm repository::
 
    SRC_URI = "git://github.com/foo/bar.git;protocol=https \
               npmsw://${THISDIR}/npm-shrinkwrap.json"

documentation/ref-manual/migration-3.2.rst

@@ -1,8 +1,8 @@
-Moving to the Yocto Project 3.2 Release
-=======================================
+Moving to the Yocto Project 3.2 Release (gatesgarth)
+====================================================
 
 This section provides migration information for moving to the Yocto
-Project 3.2 Release from the prior release.
+Project 3.2 Release (codename "gatesgarth") from the prior release.
 
 .. _migration-3.2-minimum-system-requirements:
 
@@ -90,12 +90,12 @@ If you have anonymous python or in-line python conditionally adding
 dependencies in your custom recipes, and you intend for those recipes to
 work with multilib, then you will need to ensure that ``${MLPREFIX}``
 is prefixed on the package names in the dependencies, for example
-(from the ``glibc`` recipe): ::
+(from the ``glibc`` recipe)::
 
     RRECOMMENDS_${PN} = "${@bb.utils.contains('DISTRO_FEATURES', 'ldconfig', '${MLPREFIX}ldconfig', '', d)}"
 
 This also applies when conditionally adding packages to :term:`PACKAGES` where
-those packages have dependencies, for example (from the ``alsa-plugins`` recipe): ::
+those packages have dependencies, for example (from the ``alsa-plugins`` recipe)::
 
     PACKAGES += "${@bb.utils.contains('PACKAGECONFIG', 'pulseaudio', 'alsa-plugins-pulseaudio-conf', '', d)}"
     ...
@@ -229,7 +229,7 @@ needs ``/etc/ld.so.conf`` to be present at image build time:
 
 When some recipe installs libraries to a non-standard location, and
 therefore installs in a file in ``/etc/ld.so.conf.d/foo.conf``, we
-need ``/etc/ld.so.conf`` containing: ::
+need ``/etc/ld.so.conf`` containing::
 
   include /etc/ld.so.conf.d/*.conf
 

documentation/ref-manual/migration-3.3.rst

@@ -0,0 +1,168 @@
+Moving to the Yocto Project 3.3 Release (hardknott)
+===================================================
+
+This section provides migration information for moving to the Yocto
+Project 3.3 Release (codename "hardknott") from the prior release.
+
+
+.. _migration-3.3-minimum-system-requirements:
+
+Minimum system requirements
+---------------------------
+
+You will now need at least Python 3.6 installed on your build host. Most recent
+distributions provide this, but should you be building on a distribution that
+does not have it, you can use the ``buildtools-tarball`` (easily installable
+using ``scripts/install-buildtools``) - see
+:ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`
+for details.
+
+
+.. _migration-3.3-removed-recipes:
+
+Removed recipes
+---------------
+
+The following recipes have been removed:
+
+- ``go-dep``: obsolete with the advent of go modules
+- ``gst-validate``: replaced by ``gst-devtools``
+- ``linux-yocto``: removed 5.8 version recipes (5.4 / 5.10 still provided)
+- ``vulkan-demos``: replaced by ``vulkan-samples``
+
+
+.. _migration-3.3-common-license-only-versions:
+
+Single version common license file naming
+-----------------------------------------
+
+Some license files in ``meta/files/common-licenses`` have been renamed to match
+current SPDX naming conventions:
+
+- AGPL-3.0 -> AGPL-3.0-only
+- GPL-1.0 -> GPL-1.0-only
+- GPL-2.0 -> GPL-2.0-only
+- GPL-3.0 -> GPL-3.0-only
+- LGPL-2.0 -> LGPL-2.0-only
+- LGPL-2.1 -> LGPL-2.1-only
+- LGPL-3.0 -> LGPL-3.0-only
+
+Additionally, corresponding "-or-later" suffixed files have been added e.g.
+``GPL-2.0-or-later``.
+
+It is not required that you change :term:`LICENSE` values as there are mappings
+from the original names in place; however, in rare cases where you have a recipe
+which sets :term:`LIC_FILES_CHKSUM` to point to file(s) in
+``meta/files/common-licenses`` (which in any case is not recommended) you will
+need to update those.
+
+
+.. _migration-3.3-python3targetconfig:
+
+New ``python3targetconfig`` class
+---------------------------------
+
+A new :ref:`python3targetconfig <ref-classes-python3targetconfig>` class has been
+created for situations where you would previously have inherited the
+``python3native`` class but need access to target configuration data (such as
+correct installation directories). Recipes where this situation applies should
+be changed to inherit ``python3targetconfig`` instead of ``python3native``. This
+also adds a dependency on target ``python3``, so it should only be used where
+appropriate in order to avoid unnecessarily lengthening builds.
+
+Some example recipes where this change has been made: ``gpgme``, ``libcap-ng``,
+``python3-pycairo``.
+
+
+.. _migration-3.3-distutils-path:
+
+``setup.py`` path for python modules
+------------------------------------
+
+In a Python module, sometimes ``setup.py`` can be buried deep in the
+source tree. Previously this was handled in recipes by setting :term:`S` to
+point to the subdirectory within the source where ``setup.py`` is located.
+However with the recent :ref:`pseudo <overview-manual/concepts:fakeroot and pseudo>`
+changes, some Python modules make changes to files beneath ``${S}``, for
+example::
+
+   S = "${WORKDIR}/git/python/pythonmodule"
+
+then in ``setup.py`` it works with source code in a relative fashion, such
+as ``../../src``. This causes pseudo to abort as it isn't able to track
+the paths properly. This release introduces a new :term:`DISTUTILS_SETUP_PATH`
+variable so that recipes can specify it explicitly, for example::
+
+   S = "${WORKDIR}/git"
+   DISTUTILS_SETUP_PATH = "${S}/python/pythonmodule"
+
+Recipes that inherit from :ref:`distutils3 <ref-classes-distutils3>` (or
+:ref:`setuptools3 <ref-classes-setuptools3>` which itself inherits
+:ref:`distutils3 <ref-classes-distutils3>`) that also set :term:`S` to
+point to a Python module within a subdirectory in the aforementioned
+manner should be changed to set :term:`DISTUTILS_SETUP_PATH` instead.
+
+
+.. _migration-3.3-bitbake:
+
+BitBake changes
+---------------
+
+- BitBake is now configured to use a default ``umask`` of ``022`` for all tasks
+  (specified via a new :term:`BB_DEFAULT_UMASK` variable). If needed, ``umask`` can
+  still be set on a per-task basis via the ``umask`` varflag on the task
+  function, but that is unlikely to be necessary in most cases.
+
+- If a version specified in :term:`PREFERRED_VERSION` is not available this
+  will now trigger a warning instead of just a note, making such issues more
+  visible.
+
+
+.. _migration-3.3-packaging:
+
+Packaging changes
+-----------------
+
+The following packaging changes have been made; in all cases the main package
+still depends upon the split out packages so you should not need to do anything
+unless you want to take advantage of the improved granularity:
+
+- ``dbus``: ``-common`` and ``-tools`` split out
+- ``iproute2``: split ``ip`` binary to its own package
+- ``net-tools``: split ``mii-tool`` into its own package
+- ``procps``: split ``ps`` and ``sysctl`` into their own packages
+- ``rpm``: split build and extra functionality into separate packages
+- ``sudo``: split ``sudo`` binary into ``sudo-sudo`` and libs into ``sudo-lib``
+- ``systemtap``: examples, python scripts and runtime material split out
+- ``util-linux``: ``libuuid`` has been split out to its own
+  ``util-linux-libuuid`` recipe (and corresponding packages) to avoid circular
+  dependencies if ``libgcrypt`` support is enabled in ``util-linux``.
+  (``util-linux`` depends upon ``util-linux-libuuid``.)
+
+
+.. _migration-3.3-misc:
+
+Miscellaneous changes
+---------------------
+
+- The default poky :term:`DISTRO_VERSION` value now uses the core metadata's
+  git hash (i.e. :term:`METADATA_REVISION`) rather than the date (i.e.
+  :term:`DATE`) to reduce one small source of non-reproducibility. You can
+  of course specify your own :term:`DISTRO_VERSION` value as desired
+  (particularly if you create your own custom distro configuration).
+- ``adwaita-icon-theme`` version 3.34.3 has been added back, and is selected
+  as the default via :term:`PREFERRED_VERSION` in
+  ``meta/conf/distro/include/default-versions.inc`` due to newer versions
+  not working well with ``librsvg`` 2.40. ``librsvg`` is not practically
+  upgradeable at the moment as it has been ported to Rust, and Rust is not
+  (yet) in OE-Core, but this will change in a future release.
+- ``ffmpeg`` is now configured to disable GPL-licensed portions by default
+  to make it harder to accidentally violate the GPL. To explicitly enable GPL
+  licensed portions, add ``gpl`` to :term:`PACKAGECONFIG` for ``ffmpeg``
+  using a bbappend (or use ``PACKAGECONFIG_append_pn-ffmpeg = " gpl"`` in
+  your configuration.)
+- ``connman`` is now set to conflict with ``systemd-networkd`` as they
+  overlap functionally and may interfere with each other at runtime.
+- Canonical SPDX license names are now used in image license manifests in
+  order to avoid aliases of the same license from showing up together (e.g.
+  ``GPLv2`` and ``GPL-2.0``)

documentation/ref-manual/migration.rst

@@ -28,4 +28,5 @@ notes for a given release.
    migration-3.0
    migration-3.1
    migration-3.2
+   migration-3.3
 

documentation/ref-manual/qa-checks.rst

@@ -221,8 +221,7 @@ Errors and Warnings
    Typically, the way to solve this performance issue is to add "-fPIC"
    or "-fpic" to the compiler command-line options. For example, given
    software that reads :term:`CFLAGS` when you build it,
-   you could add the following to your recipe:
-   ::
+   you could add the following to your recipe::
 
       CFLAGS_append = " -fPIC "
 
@@ -240,8 +239,7 @@ Errors and Warnings
    variable is being passed to the linker command. A common workaround
    for this situation is to pass in ``LDFLAGS`` using
    :term:`TARGET_CC_ARCH` within the recipe as
-   follows:
-   ::
+   follows::
 
       TARGET_CC_ARCH += "${LDFLAGS}"
 
@@ -265,8 +263,7 @@ Errors and Warnings
 
    The ``/usr/share/info/dir`` should not be packaged. Add the following
    line to your :ref:`ref-tasks-install` task or to your
-   ``do_install_append`` within the recipe as follows:
-   ::
+   ``do_install_append`` within the recipe as follows::
 
       rm ${D}${infodir}/dir
    
@@ -675,7 +672,7 @@ Errors and Warnings
     task. Patch fuzz is a situation when the ``patch`` tool ignores some of the context
     lines in order to apply the patch. Consider this example:
 
-    Patch to be applied: ::
+    Patch to be applied::
 
         --- filename
         +++ filename
@@ -687,7 +684,7 @@ Errors and Warnings
          context line 5
          context line 6
 
-    Original source code: ::
+    Original source code::
 
         different context line 1
         different context line 2
@@ -696,7 +693,7 @@ Errors and Warnings
         different context line 5
         different context line 6
 
-    Outcome (after applying patch with fuzz): ::
+    Outcome (after applying patch with fuzz)::
 
         different context line 1
         different context line 2
@@ -716,14 +713,14 @@ Errors and Warnings
     *How to eliminate patch fuzz warnings*
 
     Use the ``devtool`` command as explained by the warning. First, unpack the
-    source into devtool workspace: ::
+    source into devtool workspace::
 
             devtool modify <recipe>
 
     This will apply all of the patches, and create new commits out of them in
     the workspace - with the patch context updated.
 
-    Then, replace the patches in the recipe layer: ::
+    Then, replace the patches in the recipe layer::
 
             devtool finish --force-patch-refresh <recipe> <layer_path>
 

documentation/ref-manual/release-process.rst

@@ -15,9 +15,8 @@ Major and Minor Release Cadence
 The Yocto Project delivers major releases (e.g. &DISTRO;) using a six
 month cadence roughly timed each April and October of the year.
 Following are examples of some major YP releases with their codenames
-also shown. See the "`Major Release
-Codenames <#major-release-codenames>`__" section for information on
-codenames used with major releases.
+also shown. See the ":ref:`ref-manual/release-process:major release codenames`"
+section for information on codenames used with major releases.
 
   - 2.2 (Morty) 
   - 2.1 (Krogoth)

documentation/ref-manual/structure.rst

@@ -38,7 +38,7 @@ usually matches the current stable BitBake release from the BitBake
 project. BitBake, a :term:`Metadata` interpreter, reads the
 Yocto Project Metadata and runs the tasks defined by that data. Failures
 are usually caused by errors in your Metadata and not from BitBake
-itself; consequently, most users do not need to worry about BitBake.
+itself.
 
 When you run the ``bitbake`` command, the main BitBake executable (which
 resides in the ``bitbake/bin/`` directory) starts. Sourcing the
@@ -153,8 +153,7 @@ When you run this script, your Yocto Project environment is set up, a
 :term:`Build Directory` is created, your working
 directory becomes the Build Directory, and you are presented with some
 simple suggestions as to what to do next, including a list of some
-possible targets to build. Here is an example:
-::
+possible targets to build. Here is an example::
 
    $ source oe-init-build-env
 
@@ -185,8 +184,7 @@ creates the ``build/`` directory in your current working directory. If
 you provide a Build Directory argument when you ``source`` the script,
 you direct the OpenEmbedded build system to create a Build Directory of
 your choice. For example, the following command creates a Build
-Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:
-::
+Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`::
 
    $ source oe-init-build-env ~/mybuilds
 
@@ -269,8 +267,7 @@ and to ``meta/conf/`` when you are building from the OpenEmbedded-Core
 environment. Because the script variable points to the source of the
 ``local.conf.sample`` file, this implies that you can configure your
 build environment from any layer by setting the variable in the
-top-level build environment setup script as follows:
-::
+top-level build environment setup script as follows::
 
    TEMPLATECONF=your_layer/conf
 
@@ -282,7 +279,7 @@ file, it uses ``sed`` to substitute final
 .. note::
 
    You can see how the ``TEMPLATECONF`` variable is used by looking at the
-   ``scripts/oe-setup-builddir``` script in the :term:`Source Directory`.
+   ``scripts/oe-setup-builddir`` script in the :term:`Source Directory`.
    You can find the Yocto Project version of the ``local.conf.sample`` file in
    the ``meta-poky/conf`` directory.
 
@@ -309,8 +306,7 @@ Project development environment, and to ``meta/conf/`` when you are
 building from the OpenEmbedded-Core environment. Because the script
 variable points to the source of the ``bblayers.conf.sample`` file, this
 implies that you can base your build from any layer by setting the
-variable in the top-level build environment setup script as follows:
-::
+variable in the top-level build environment setup script as follows::
 
    TEMPLATECONF=your_layer/conf
 
@@ -463,8 +459,7 @@ image again.
 If you do accidentally delete files here, you will need to force them to
 be re-created. In order to do that, you will need to know the target
 that produced them. For example, these commands rebuild and re-create
-the kernel files:
-::
+the kernel files::
 
    $ bitbake -c clean virtual/kernel
    $ bitbake virtual/kernel
@@ -535,8 +530,7 @@ recipe-specific :term:`WORKDIR` directories. Thus, the
 This directory holds information that BitBake uses for accounting
 purposes to track what tasks have run and when they have run. The
 directory is sub-divided by architecture, package name, and version.
-Following is an example:
-::
+Following is an example::
 
       stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
 
@@ -789,7 +783,7 @@ system. The tools, however, can also be used on targets.
 
 This directory contains non-essential applications that add features
 compared to the alternatives in core. You might need this directory for
-full tool functionality or for Linux Standard Base (LSB) compliance.
+full tool functionality.
 
 .. _structure-meta-recipes-gnome:
 
@@ -815,14 +809,6 @@ libraries.
 This directory contains the kernel and generic applications and
 libraries that have strong kernel dependencies.
 
-.. _structure-meta-recipes-lsb4:
-
-``meta/recipes-lsb4/``
-----------------------
-
-This directory contains recipes specifically added to support the Linux
-Standard Base (LSB) version 4.x.
-
 .. _structure-meta-recipes-multimedia:
 
 ``meta/recipes-multimedia/``

documentation/ref-manual/system-requirements.rst

@@ -111,7 +111,7 @@ function.
 Ubuntu and Debian
 -----------------
 
-The following list shows the required packages by function given a
+Here are the required packages by function given a
 supported Ubuntu or Debian Linux distribution:
 
 .. note::
@@ -120,8 +120,7 @@ supported Ubuntu or Debian Linux distribution:
       might experience QEMU build failures due to the package installing
       its own custom ``/usr/include/linux/soundcard.h`` on the Debian
       system. If you run into this situation, either of the following
-      solutions exist:
-      ::
+      solutions exist::
 
          $ sudo apt-get build-dep qemu
          $ sudo apt-get remove oss4-dev
@@ -132,14 +131,12 @@ supported Ubuntu or Debian Linux distribution:
 
          $ sudo pip3 install GitPython pylint==1.9.5
 
--  *Essentials:* Packages needed to build an image on a headless system:
-   ::
+-  *Essentials:* Packages needed to build an image on a headless system::
 
       $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
 
 -  *Documentation:* Packages needed if you are going to build out the
-   Yocto Project documentation manuals:
-   ::
+   Yocto Project documentation manuals::
 
       $ sudo apt-get install make python3-pip
       &PIP3_HOST_PACKAGES_DOC;
@@ -153,18 +150,16 @@ supported Ubuntu or Debian Linux distribution:
 Fedora Packages
 ---------------
 
-The following list shows the required packages by function given a
+Here are the required packages by function given a
 supported Fedora Linux distribution:
 
 -  *Essentials:* Packages needed to build an image for a headless
-   system:
-   ::
+   system::
 
       $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
 
 -  *Documentation:* Packages needed if you are going to build out the
-   Yocto Project documentation manuals:
-   ::
+   Yocto Project documentation manuals::
 
       $ sudo dnf install make python3-pip which
       &PIP3_HOST_PACKAGES_DOC;
@@ -172,18 +167,16 @@ supported Fedora Linux distribution:
 openSUSE Packages
 -----------------
 
-The following list shows the required packages by function given a
+Here are the required packages by function given a
 supported openSUSE Linux distribution:
 
 -  *Essentials:* Packages needed to build an image for a headless
-   system:
-   ::
+   system::
 
       $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
 
 -  *Documentation:* Packages needed if you are going to build out the
-   Yocto Project documentation manuals:
-   ::
+   Yocto Project documentation manuals::
 
       $ sudo zypper install make python3-pip which
       &PIP3_HOST_PACKAGES_DOC;
@@ -192,12 +185,11 @@ supported openSUSE Linux distribution:
 CentOS-7 Packages
 -----------------
 
-The following list shows the required packages by function given a
+Here are the required packages by function given a
 supported CentOS-7 Linux distribution:
 
 -  *Essentials:* Packages needed to build an image for a headless
-   system:
-   ::
+   system::
 
       $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL;
 
@@ -212,8 +204,7 @@ supported CentOS-7 Linux distribution:
          ``epel-release``.
 
 -  *Documentation:* Packages needed if you are going to build out the
-   Yocto Project documentation manuals:
-   ::
+   Yocto Project documentation manuals::
 
       $ sudo yum install make python3-pip which
       &PIP3_HOST_PACKAGES_DOC;
@@ -221,12 +212,11 @@ supported CentOS-7 Linux distribution:
 CentOS-8 Packages
 -----------------
 
-The following list shows the required packages by function given a
+Here are the required packages by function given a
 supported CentOS-8 Linux distribution:
 
 -  *Essentials:* Packages needed to build an image for a headless
-   system:
-   ::
+   system::
 
       $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL;
 
@@ -244,8 +234,7 @@ supported CentOS-8 Linux distribution:
          ``epel-release``.
 
 -  *Documentation:* Packages needed if you are going to build out the
-   Yocto Project documentation manuals:
-   ::
+   Yocto Project documentation manuals::
 
       $ sudo dnf install make python3-pip which
       &PIP3_HOST_PACKAGES_DOC;
@@ -256,11 +245,11 @@ Required Git, tar, Python and gcc Versions
 In order to use the build system, your host development system must meet
 the following version requirements for Git, tar, and Python:
 
--  Git 1.8.3.1 or greater
+-  Git &MIN_GIT_VERSION; or greater
 
--  tar 1.28 or greater
+-  tar &MIN_TAR_VERSION; or greater
 
--  Python 3.5.0 or greater
+-  Python &MIN_PYTHON_VERSION; or greater
 
 If your host development system does not meet all these requirements,
 you can resolve this by installing a ``buildtools`` tarball that
@@ -270,11 +259,15 @@ a pre-built tarball or use BitBake to build the tarball.
 In addition, your host development system must meet the following
 version requirement for gcc:
 
--  gcc 5.0 or greater
+-  gcc &MIN_GCC_VERSION; or greater
 
 If your host development system does not meet this requirement, you can
 resolve this by installing a ``buildtools-extended`` tarball that
-contains additional tools, the equivalent of ``buildtools-essential``.
+contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential``
+package.
+
+In the sections that follow, three different methods will be described for
+installing the ``buildtools`` or ``buildtools-extended`` toolset.
 
 Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script
 --------------------------------------------------------------------------------
@@ -283,8 +276,7 @@ The ``install-buildtools`` script is the easiest of the three methods by
 which you can get these tools. It downloads a pre-built buildtools
 installer and automatically installs the tools for you:
 
-1. Execute the ``install-buildtools`` script. Here is an example:
-   ::
+1. Execute the ``install-buildtools`` script. Here is an example::
 
       $ cd poky
       $ scripts/install-buildtools --without-extended-buildtools \
@@ -298,22 +290,19 @@ installer and automatically installs the tools for you:
    installation is functional.
 
    To avoid the need of ``sudo`` privileges, the ``install-buildtools``
-   script will by default tell the installer to install in:
-   ::
+   script will by default tell the installer to install in::
 
       /path/to/poky/buildtools
 
    If your host development system needs the additional tools provided
    in the ``buildtools-extended`` tarball, you can instead execute the
-   ``install-buildtools`` script with the default parameters:
-   ::
+   ``install-buildtools`` script with the default parameters::
 
       $ cd poky
       $ scripts/install-buildtools
 
 2. Source the tools environment setup script by using a command like the
-   following:
-   ::
+   following::
 
       $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux
 
@@ -331,19 +320,18 @@ installer and automatically installs the tools for you:
 Downloading a Pre-Built ``buildtools`` Tarball
 ----------------------------------------------
 
-Downloading and running a pre-built buildtools installer is the easiest
-of the two methods by which you can get these tools:
+If you would prefer not to use the ``install-buildtools`` script, you can instead
+download and run a pre-built buildtools installer yourself with the following
+steps:
 
 1. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/
 
 2. Execute the installation script. Here is an example for the
-   traditional installer:
-   ::
+   traditional installer::
 
       $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
 
-   Here is an example for the extended installer:
-   ::
+   Here is an example for the extended installer::
 
       $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
 
@@ -352,8 +340,7 @@ of the two methods by which you can get these tools:
    ``/home/your-username/buildtools``
 
 3. Source the tools environment setup script by using a command like the
-   following:
-   ::
+   following::
 
       $ source /home/your_username/buildtools/environment-setup-i586-poky-linux
 
@@ -385,13 +372,11 @@ installer:
    your build environment with the setup script
    (:ref:`structure-core-script`).
 
-2. Run the BitBake command to build the tarball:
-   ::
+2. Run the BitBake command to build the tarball::
 
       $ bitbake buildtools-tarball
 
-   or run the BitBake command to build the extended tarball:
-   ::
+   or run the BitBake command to build the extended tarball::
 
       $ bitbake buildtools-extended-tarball
 
@@ -410,13 +395,11 @@ installer:
 
 4. On the machine that does not meet the requirements, run the ``.sh``
    file to install the tools. Here is an example for the traditional
-   installer:
-   ::
+   installer::
 
       $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
 
-   Here is an example for the extended installer:
-   ::
+   Here is an example for the extended installer::
 
       $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
 
@@ -425,8 +408,7 @@ installer:
    ``/home/your_username/buildtools``
 
 5. Source the tools environment setup script by using a command like the
-   following:
-   ::
+   following::
 
       $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux
 

documentation/ref-manual/tasks.rst

@@ -93,8 +93,7 @@ output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``.
 The ``do_deploy`` task is not added as a task by default and
 consequently needs to be added manually. If you want the task to run
 after :ref:`ref-tasks-compile`, you can add it by doing
-the following:
-::
+the following::
 
       addtask deploy after do_compile
 
@@ -103,8 +102,7 @@ Adding ``do_deploy`` after other tasks works the same way.
 .. note::
 
    You do not need to add ``before do_build`` to the ``addtask`` command
-   (though it is harmless), because the ``base`` class contains the following:
-   ::
+   (though it is harmless), because the ``base`` class contains the following::
 
            do_build[recrdeptask] += "do_deploy"
 
@@ -302,13 +300,11 @@ Patch files, by default, are ``*.patch`` and ``*.diff`` files created
 and kept in a subdirectory of the directory holding the recipe file. For
 example, consider the
 :yocto_git:`bluez5 </poky/tree/meta/recipes-connectivity/bluez5>`
-recipe from the OE-Core layer (i.e. ``poky/meta``):
-::
+recipe from the OE-Core layer (i.e. ``poky/meta``)::
 
    poky/meta/recipes-connectivity/bluez5
 
-This recipe has two patch files located here:
-::
+This recipe has two patch files located here::
 
    poky/meta/recipes-connectivity/bluez5/bluez5
 
@@ -323,8 +319,7 @@ and patch files needed to build the package.
 As mentioned earlier, the build system treats files whose file types are
 ``.patch`` and ``.diff`` as patch files. However, you can use the
 "apply=yes" parameter with the ``SRC_URI`` statement to indicate any
-file as a patch file:
-::
+file as a patch file::
 
    SRC_URI = " \
        git://path_to_repo/some_package \
@@ -334,8 +329,7 @@ file as a patch file:
 Conversely, if you have a directory full of patch files and you want to
 exclude some so that the ``do_patch`` task does not apply them during
 the patch phase, you can use the "apply=no" parameter with the
-``SRC_URI`` statement:
-::
+``SRC_URI`` statement::
 
    SRC_URI = " \
        git://path_to_repo/some_package \
@@ -455,8 +449,7 @@ of the recipe exists upstream and a status of not updated, updated, or
 unknown.
 
 To check the upstream version and status of a recipe, use the following
-devtool commands:
-::
+devtool commands::
 
    $ devtool latest-version
    $ devtool check-upgrade-status
@@ -467,8 +460,7 @@ chapter for more information on
 section for information on checking the upgrade status of a recipe.
 
 To build the ``checkpkg`` task, use the ``bitbake`` command with the
-"-c" option and task name:
-::
+"-c" option and task name::
 
    $ bitbake core-image-minimal -c checkpkg
 
@@ -494,8 +486,7 @@ Removes all output files for a target from the
 :ref:`ref-tasks-install`, and
 :ref:`ref-tasks-package`).
 
-You can run this task using BitBake as follows:
-::
+You can run this task using BitBake as follows::
 
    $ bitbake -c clean recipe
 
@@ -519,8 +510,7 @@ downloaded source files for a target (i.e. the contents of
 identical to the :ref:`ref-tasks-cleansstate` task
 with the added removal of downloaded source files.
 
-You can run this task using BitBake as follows:
-::
+You can run this task using BitBake as follows::
 
    $ bitbake -c cleanall recipe
 
@@ -540,8 +530,7 @@ target. Essentially, the ``do_cleansstate`` task is identical to the
 shared state (:ref:`sstate <overview-manual/concepts:shared state cache>`)
 cache.
 
-You can run this task using BitBake as follows:
-::
+You can run this task using BitBake as follows::
 
    $ bitbake -c cleansstate recipe
 
@@ -553,8 +542,7 @@ scratch is guaranteed.
 
    The ``do_cleansstate`` task cannot remove sstate from a remote sstate
    mirror. If you need to build a target from scratch using remote mirrors, use
-   the "-f" option as follows:
-   ::
+   the "-f" option as follows::
 
       $ bitbake -f -c do_cleansstate target
 
@@ -687,8 +675,7 @@ changes made by the user with other methods (i.e. using
 (:ref:`ref-tasks-kernel_menuconfig`). Once the
 file of differences is created, it can be used to create a config
 fragment that only contains the differences. You can invoke this task
-from the command line as follows:
-::
+from the command line as follows::
 
    $ bitbake linux-yocto -c diffconfig
 
@@ -718,8 +705,7 @@ Validates the configuration produced by the
 configuration does not appear in the final ``.config`` file or when you
 override a policy configuration in a hardware configuration fragment.
 You can run this task explicitly and view the output by using the
-following command:
-::
+following command::
 
    $ bitbake linux-yocto -c kernel_configcheck -f
 
@@ -750,8 +736,7 @@ tool, which you then use to modify the kernel configuration.
 
 .. note::
 
-   You can also invoke this tool from the command line as follows:
-   ::
+   You can also invoke this tool from the command line as follows::
 
            $ bitbake linux-yocto -c menuconfig
 
@@ -793,8 +778,7 @@ instead of the default defconfig. The saved defconfig contains the
 differences between the default defconfig and the changes made by the
 user using other methods (i.e. the
 :ref:`ref-tasks-kernel_menuconfig` task. You
-can invoke the task using the following command:
-::
+can invoke the task using the following command::
 
    $ bitbake linux-yocto -c savedefconfig
 

documentation/ref-manual/terms.rst

@@ -26,8 +26,7 @@ universal, the list includes them just in case:
 
       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:
-      ::
+      append file named as follows::
 
          busybox_1.21.%.bbappend
 

documentation/releases.rst

@@ -4,6 +4,12 @@
  Current Release Manuals
 =========================
 
+*******************************
+3.3 'hardknott' Release Series
+*******************************
+
+- :yocto_docs:`3.3 Documentation </3.3>`
+
 *******************************
 3.2 'gatesgarth' Release Series
 *******************************
@@ -12,6 +18,7 @@
 - :yocto_docs:`3.2.1 Documentation </3.2.1>`
 - :yocto_docs:`3.2.2 Documentation </3.2.2>`
 - :yocto_docs:`3.2.3 Documentation </3.2.3>`
+- :yocto_docs:`3.2.4 Documentation </3.2.4>`
 
 ****************************
 3.1 'dunfell' Release Series
@@ -24,6 +31,7 @@
 - :yocto_docs:`3.1.4 Documentation </3.1.4>`
 - :yocto_docs:`3.1.5 Documentation </3.1.5>`
 - :yocto_docs:`3.1.6 Documentation </3.1.6>`
+- :yocto_docs:`3.1.7 Documentation </3.1.7>`
 
 ==========================
  Previous Release Manuals

documentation/sdk-manual/appendix-customizing.rst

@@ -101,17 +101,15 @@ adjustments:
 
 -  Generally, you want to have a shared state mirror set up so users of
    the SDK can add additional items to the SDK after installation
-   without needing to build the items from source. See the "`Providing
-   Additional Installable Extensible SDK
-   Content <#sdk-providing-additional-installable-extensible-sdk-content>`__"
+   without needing to build the items from source. See the
+   ":ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`"
    section for information.
 
 -  If you want users of the SDK to be able to easily update the SDK, you
    need to set the
    :term:`SDK_UPDATE_URL`
-   variable. For more information, see the "`Providing Updates to the
-   Extensible SDK After
-   Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__"
+   variable. For more information, see the
+   ":ref:`sdk-manual/appendix-customizing:providing updates to the extensible sdk after installation`"
    section.
 
 -  If you have adjusted the list of files and directories that appear in
@@ -140,8 +138,8 @@ Changing the Extensible SDK Installer Title
 You can change the displayed title for the SDK installer by setting the
 :term:`SDK_TITLE` variable and then
 rebuilding the SDK installer. For information on how to build an SDK
-installer, see the "`Building an SDK
-Installer <#sdk-building-an-sdk-installer>`__" section.
+installer, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
+section.
 
 By default, this title is derived from
 :term:`DISTRO_NAME` when it is
@@ -151,8 +149,7 @@ from the :term:`DISTRO` variable.
 The
 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
 class defines the default value of the ``SDK_TITLE`` variable as
-follows:
-::
+follows::
 
    SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
 
@@ -164,8 +161,7 @@ an example, assume you have your own layer for your distribution named
 does the default "poky" distribution. If so, you could update the
 ``SDK_TITLE`` variable in the
 ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
-form:
-::
+form::
 
    SDK_TITLE = "your_title"
 
@@ -189,16 +185,14 @@ the installed SDKs to update the installed SDKs by using the
    variable to point to the corresponding HTTP or HTTPS URL. Setting
    this variable causes any SDK built to default to that URL and thus,
    the user does not have to pass the URL to the ``devtool sdk-update``
-   command as described in the "`Applying Updates to an Installed
-   Extensible
-   SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__"
+   command as described in the
+   ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
    section.
 
 3. Build the extensible SDK normally (i.e., use the
    ``bitbake -c populate_sdk_ext`` imagename command).
 
-4. Publish the SDK using the following command:
-   ::
+4. Publish the SDK using the following command::
 
       $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory
 
@@ -208,9 +202,9 @@ the installed SDKs to update the installed SDKs by using the
 
 Completing the above steps allows users of the existing installed SDKs
 to simply run ``devtool sdk-update`` to retrieve and apply the latest
-updates. See the "`Applying Updates to an Installed Extensible
-SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__" section
-for further information.
+updates. See the
+":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`"
+section for further information.
 
 Changing the Default SDK Installation Directory
 ===============================================
@@ -221,8 +215,7 @@ installation directory for the SDK is based on the
 :term:`SDKEXTPATH` variables from
 within the
 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
-class as follows:
-::
+class as follows::
 
    SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
 
@@ -239,8 +232,7 @@ assume you have your own layer for your distribution named
 does the default "poky" distribution. If so, you could update the
 ``SDKEXTPATH`` variable in the
 ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
-form:
-::
+form::
 
    SDKEXTPATH = "some_path_for_your_installed_sdk"
 
@@ -275,8 +267,7 @@ source, you need to do a number of things:
 
 3. Set the appropriate configuration so that the produced SDK knows how
    to find the configuration. The variable you need to set is
-   :term:`SSTATE_MIRRORS`:
-   ::
+   :term:`SSTATE_MIRRORS`::
 
       SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH"
 
@@ -290,8 +281,7 @@ source, you need to do a number of things:
       side, and its contents will not interfere with the build), then
       you can set the variable in your ``local.conf`` or custom distro
       configuration file. You can then "whitelist" the variable through
-      to the SDK by adding the following:
-      ::
+      to the SDK by adding the following::
 
          SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
 
@@ -316,8 +306,7 @@ everything needed to reconstruct the image for which the SDK was built.
 This bundling can lead to an SDK installer file that is a Gigabyte or
 more in size. If the size of this file causes a problem, you can build
 an SDK that has just enough in it to install and provide access to the
-``devtool command`` by setting the following in your configuration:
-::
+``devtool command`` by setting the following in your configuration::
 
    SDK_EXT_TYPE = "minimal"
 
@@ -339,8 +328,7 @@ information enables the ``devtool search`` command to return useful
 results.
 
 To facilitate this wider range of information, you would need to set the
-following:
-::
+following::
 
    SDK_INCLUDE_PKGDATA = "1"
 

documentation/sdk-manual/appendix-obtain.rst

@@ -25,8 +25,7 @@ Follow these steps to locate and hand-install the toolchain:
    download the installer appropriate for your build host, target
    hardware, and image type.
 
-   The installer files (``*.sh``) follow this naming convention:
-   ::
+   The installer files (``*.sh``) follow this naming convention::
 
       poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh
 
@@ -38,7 +37,7 @@ Follow these steps to locate and hand-install the toolchain:
                 "sato" or "minimal"
 
           arch is a string representing the target architecture:
-                 "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2",
+                 "aarch64", "armv5e", "core2-64", "cortexa8hf-neon", "i586", "mips32r2",
                  "mips64", or "ppc7400"
 
           release is the version of Yocto Project.
@@ -55,23 +54,21 @@ Follow these steps to locate and hand-install the toolchain:
 
    For example, if your build host is a 64-bit x86 system and you need
    an extended SDK for a 64-bit core2 target, go into the ``x86_64``
-   folder and download the following installer:
-   ::
+   folder and download the following installer::
 
       poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
 
 4. *Run the Installer:* Be sure you have execution privileges and run
    the installer. Following is an example from the ``Downloads``
-   directory:
-   ::
+   directory::
 
       $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
 
    During execution of the script, you choose the root location for the
-   toolchain. See the "`Installed Standard SDK Directory
-   Structure <#sdk-installed-standard-sdk-directory-structure>`__"
-   section and the "`Installed Extensible SDK Directory
-   Structure <#sdk-installed-extensible-sdk-directory-structure>`__"
+   toolchain. See the
+   ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
+   section and the
+   ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
    section for more information.
 
 Building an SDK Installer
@@ -132,8 +129,7 @@ build the SDK installer. Follow these steps:
       using to build the installer. If
       SDKMACHINE
       is not set appropriately, the build fails and provides an error
-      message similar to the following:
-      ::
+      message similar to the following::
 
               The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is
               set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64).
@@ -142,10 +138,11 @@ build the SDK installer. Follow these steps:
 
 6. *Build the SDK Installer:* To build the SDK installer for a standard
    SDK and populate the SDK image, use the following command form. Be
-   sure to replace image with an image (e.g. "core-image-sato"): $
-   bitbake image -c populate_sdk You can do the same for the extensible
-   SDK using this command form:
-   ::
+   sure to replace ``image`` with an image (e.g. "core-image-sato")::
+
+      $ bitbake image -c populate_sdk
+
+   You can do the same for the extensible SDK using this command form::
 
       $ bitbake image -c populate_sdk_ext
 
@@ -170,17 +167,16 @@ build the SDK installer. Follow these steps:
          libc-staticdev"
 
 7. *Run the Installer:* You can now run the SDK installer from
-   ``tmp/deploy/sdk`` in the Build Directory. Following is an example:
-   ::
+   ``tmp/deploy/sdk`` in the Build Directory. Following is an example::
 
       $ cd poky/build/tmp/deploy/sdk
       $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
 
    During execution of the script, you choose the root location for the
-   toolchain. See the "`Installed Standard SDK Directory
-   Structure <#sdk-installed-standard-sdk-directory-structure>`__"
-   section and the "`Installed Extensible SDK Directory
-   Structure <#sdk-installed-extensible-sdk-directory-structure>`__"
+   toolchain. See the
+   ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
+   section and the
+   ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
    section for more information.
 
 Extracting the Root Filesystem
@@ -211,8 +207,7 @@ Follow these steps to extract the root filesystem:
    which you can use with QEMU directly.
 
    The pre-built root filesystem image files follow these naming
-   conventions:
-   ::
+   conventions::
 
       core-image-profile-arch.tar.bz2
 
@@ -233,8 +228,7 @@ Follow these steps to extract the root filesystem:
 
    For example, if you plan on using a BeagleBone device as your target
    hardware and your image is a ``core-image-sato-sdk`` image, you can
-   download the following file:
-   ::
+   download the following file::
 
       core-image-sato-sdk-beaglebone-yocto.tar.bz2
 
@@ -246,8 +240,7 @@ Follow these steps to extract the root filesystem:
    installed the toolchain (e.g. ``poky_sdk``).
 
    Following is an example based on the toolchain installed in the
-   ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section:
-   ::
+   ":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section::
 
       $ source poky_sdk/environment-setup-core2-64-poky-linux
 
@@ -258,12 +251,11 @@ Follow these steps to extract the root filesystem:
    from a previously built root filesystem image that was downloaded
    from the :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>`.
    This command extracts the root filesystem into the ``core2-64-sato``
-   directory:
-   ::
+   directory::
 
       $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
 
-   You could now point to the target sysroot at ``beablebone-sato``.
+   You could now point to the target sysroot at ``beaglebone-sato``.
 
 Installed Standard SDK Directory Structure
 ==========================================

documentation/sdk-manual/extensible.rst

@@ -21,8 +21,9 @@ hardware, and ease integration into the rest of the
 
 In addition to the functionality available through ``devtool``, you can
 alternatively make use of the toolchain directly, for example from
-Makefile and Autotools. See the "`Using the SDK Toolchain
-Directly <#sdk-working-projects>`__" chapter for more information.
+Makefile and Autotools. See the
+":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter
+for more information.
 
 Why use the Extensible SDK and What is in It?
 =============================================
@@ -58,8 +59,7 @@ 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.
 An extensible SDK has the string "-ext" as part of the name. Following
-is the general form:
-::
+is the general form::
 
    poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh
 
@@ -82,8 +82,7 @@ is the general form:
 
 For example, the following SDK installer is for a 64-bit
 development host system and a i586-tuned target architecture based off
-the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot:
-::
+the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot::
 
    poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh
 
@@ -149,8 +148,7 @@ begin with the string "``environment-setup``" and include as part of
 their name the tuned target architecture. As an example, the following
 commands set the working directory to where the SDK was installed and
 then source the environment setup script. In this example, the setup
-script is for an IA-based target machine using i586 tuning:
-::
+script is for an IA-based target machine using i586 tuning::
 
    $ cd /home/scottrif/poky_sdk
    $ source environment-setup-core2-64-poky-linux
@@ -257,8 +255,7 @@ command:
       to be extracted. In this situation, the source code is extracted
       to the default workspace - you do not want the files in some
       specific location outside of the workspace. Thus, everything you
-      need will be located in the workspace:
-      ::
+      need will be located in the workspace::
 
          $ devtool add recipe fetchuri
 
@@ -282,8 +279,7 @@ command:
       Furthermore, the first positional argument srctree in this case
       identifies where the ``devtool add`` command will locate the
       extracted code outside of the workspace. You need to specify an
-      empty directory:
-      ::
+      empty directory::
 
          $ devtool add recipe srctree fetchuri
 
@@ -299,8 +295,7 @@ command:
       ``devtool`` workspace.
 
       The following command provides a new recipe name and identifies
-      the existing source tree location:
-      ::
+      the existing source tree location::
 
          $ devtool add recipe srctree
 
@@ -316,8 +311,7 @@ command:
 
 2. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the
    editor as defined by the ``$EDITOR`` environment variable and modify
-   the file:
-   ::
+   the file::
 
       $ devtool edit-recipe recipe
 
@@ -337,8 +331,7 @@ command:
    On the other hand, if you want an image to contain the recipe's
    packages from the workspace for immediate deployment onto a device
    (e.g. for testing purposes), you can use the ``devtool build-image``
-   command:
-   ::
+   command::
 
       $ devtool build-image image
 
@@ -434,8 +427,7 @@ command:
       outside the workspace (i.e. ``meta-``\ layername).
 
       The following command identifies the recipe and, by default,
-      extracts the source files:
-      ::
+      extracts the source files::
 
          $ devtool modify recipe
 
@@ -473,8 +465,7 @@ command:
       The following command tells ``devtool`` the recipe with which to
       work and, in this case, identifies a local area for the extracted
       source files that exists outside of the default ``devtool``
-      workspace:
-      ::
+      workspace::
 
          $ devtool modify recipe srctree
 
@@ -507,8 +498,7 @@ command:
       The following command tells ``devtool`` the recipe with which to
       work, uses the "-n" option to indicate source does not need to be
       extracted, and uses srctree to point to the previously extracted
-      source files:
-      ::
+      source files::
 
          $ devtool modify -n recipe srctree
 
@@ -531,8 +521,7 @@ command:
    depends on what you are going to do with the new code.
 
    If you need to eventually move the build output to the target
-   hardware, use the following ``devtool`` command:
-   ::
+   hardware, use the following ``devtool`` command::
 
       $ devtool build recipe
 
@@ -555,8 +544,7 @@ command:
       development machine.
 
    You can deploy your build output to that target hardware by using the
-   ``devtool deploy-target`` command:
-   ::
+   ``devtool deploy-target`` command::
 
       $ devtool deploy-target recipe target
 
@@ -650,8 +638,7 @@ The following diagram shows the common development flow used with the
    A common situation is where third-party software has undergone a
    revision so that it has been upgraded. The recipe you have access to
    is likely in your own layer. Thus, you need to upgrade the recipe to
-   use the newer version of the software:
-   ::
+   use the newer version of the software::
 
       $ devtool upgrade -V version recipe
 
@@ -702,16 +689,14 @@ The following diagram shows the common development flow used with the
    depends on what you are going to do with the new code.
 
    If you need to eventually move the build output to the target
-   hardware, use the following ``devtool`` command:
-   ::
+   hardware, use the following ``devtool`` command::
 
       $ devtool build recipe
 
    On the other hand, if you want an image to contain the recipe's
    packages from the workspace for immediate deployment onto a device
    (e.g. for testing purposes), you can use the ``devtool build-image``
-   command:
-   ::
+   command::
 
       $ devtool build-image image
 
@@ -827,8 +812,7 @@ name and version, just the name, or just the version as part of the
 command line.
 
 Sometimes the name or version determined from the source tree might be
-incorrect. For such a case, you must reset the recipe:
-::
+incorrect. For such a case, you must reset the recipe::
 
    $ devtool reset -n recipename
 
@@ -852,8 +836,7 @@ the ``DEPENDS`` variable in the original recipe to include the new
 recipe.
 
 If you need to add runtime dependencies, you can do so by adding the
-following to your recipe:
-::
+following to your recipe::
 
    RDEPENDS_${PN} += "dependency1 dependency2 ..."
 
@@ -937,8 +920,7 @@ mind:
    the command line, add the variable setting to
    :term:`EXTRA_OEMAKE` or
    :term:`PACKAGECONFIG_CONFARGS`
-   within the recipe. Here is an example using ``EXTRA_OEMAKE``:
-   ::
+   within the recipe. Here is an example using ``EXTRA_OEMAKE``::
 
       EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
 
@@ -971,7 +953,7 @@ following methods when you run ``devtool add``:
    Specifying the name like this produces a recipe that only builds for
    the build host.
 
--  Specify the "DASHDASHalso-native" option with the ``devtool add``
+-  Specify the "--also-native" option with the ``devtool add``
    command. Specifying this option creates a recipe file that still
    builds for the target but also creates a variant with a "-native"
    suffix that builds for the build host.
@@ -982,7 +964,7 @@ following methods when you run ``devtool add``:
    that builds code for the target, you can typically accomplish this by
    building the native and target parts separately rather than within
    the same compilation process. Realize though that with the
-   "DASHDASHalso-native" option, you can add the tool using just one
+   "--also-native" option, you can add the tool using just one
    recipe file.
 
 Adding Node.js Modules
@@ -992,8 +974,7 @@ You can use the ``devtool add`` command two different ways to add
 Node.js modules: 1) Through ``npm`` and, 2) from a repository or local
 source.
 
-Use the following form to add Node.js modules through ``npm``:
-::
+Use the following form to add Node.js modules through ``npm``::
 
    $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
 
@@ -1017,8 +998,7 @@ these behaviors ensure the reproducibility and integrity of the build.
 
 As mentioned earlier, you can also add Node.js modules directly from a
 repository or local source tree. To add modules this way, use
-``devtool add`` in the following form:
-::
+``devtool add`` in the following form::
 
    $ devtool add https://github.com/diversario/node-ssdp
 
@@ -1087,12 +1067,12 @@ links created within the source tree:
 
    -  ``sysroot-destdir/``: Contains a subset of files installed within
       ``do_install`` that have been put into the shared sysroot. For
-      more information, see the "`Sharing Files Between
-      Recipes <#sdk-sharing-files-between-recipes>`__" section.
+      more information, see the
+      ":ref:`dev-manual/common-tasks:sharing files between recipes`" section.
 
    -  ``packages-split/``: Contains subdirectories for each package
       produced by the recipe. For more information, see the
-      "`Packaging <#sdk-packaging>`__" section.
+      ":ref:`sdk-manual/extensible:packaging`" section.
 
 You can use these links to get more information on what is happening at
 each build step.
@@ -1120,7 +1100,7 @@ arguments listed in the previous paragraph. The command determines the
 exact options being passed, and shows them to you along with any custom
 arguments specified through ``EXTRA_OECONF`` or
 ``PACKAGECONFIG_CONFARGS``. If applicable, the command also shows you
-the output of the configure script's "DASHDASHhelp" option as a
+the output of the configure script's "--help" option as a
 reference.
 
 Sharing Files Between Recipes
@@ -1195,15 +1175,13 @@ need to restore the original files that existed prior to running the
 ``devtool deploy-target`` command. Because the ``devtool deploy-target``
 command backs up any files it overwrites, you can use the
 ``devtool undeploy-target`` command to restore those files and remove
-any other files the recipe deployed. Consider the following example:
-::
+any other files the recipe deployed. Consider the following example::
 
    $ devtool undeploy-target lighttpd root@192.168.7.2
 
 If you have deployed
 multiple applications, you can remove them all using the "-a" option
-thus restoring the target device to its original state:
-::
+thus restoring the target device to its original state::
 
    $ devtool undeploy-target -a root@192.168.7.2
 
@@ -1234,22 +1212,19 @@ populated on-demand. Sometimes you must explicitly install extra items
 into the SDK. If you need these extra items, you can first search for
 the items using the ``devtool search`` command. For example, suppose you
 need to link to libGL but you are not sure which recipe provides libGL.
-You can use the following command to find out:
-::
+You can use the following command to find out::
 
    $ devtool search libGL mesa
 
 A free implementation of the OpenGL API Once you know the recipe
-(i.e. ``mesa`` in this example), you can install it:
-::
+(i.e. ``mesa`` in this example), you can install it::
 
    $ devtool sdk-install mesa
 
 By default, the ``devtool sdk-install`` command assumes
 the item is available in pre-built form from your SDK provider. If the
 item is not available and it is acceptable to build the item from
-source, you can add the "-s" option as follows:
-::
+source, you can add the "-s" option as follows::
 
    $ devtool sdk-install -s mesa
 
@@ -1265,8 +1240,7 @@ If you are working with an installed extensible SDK that gets
 occasionally updated (e.g. a third-party SDK), then you will need to
 manually "pull down" the updates into the installed SDK.
 
-To update your installed SDK, use ``devtool`` as follows:
-::
+To update your installed SDK, use ``devtool`` as follows::
 
    $ devtool sdk-update
 

documentation/sdk-manual/intro.rst

@@ -8,8 +8,8 @@ eSDK Introduction
 =================
 
 Welcome to the Yocto Project Application Development and the Extensible
-Software Development Kit (eSDK) manual. This manual provides information
-that explains how to use both the Yocto Project extensible and standard
+Software Development Kit (eSDK) manual. This manual
+explains how to use both the Yocto Project extensible and standard
 SDKs to develop applications and images.
 
 .. note::
@@ -25,12 +25,13 @@ SDKs to develop applications and images.
 All SDKs consist of the following:
 
 -  *Cross-Development Toolchain*: This toolchain contains a compiler,
-   debugger, and various miscellaneous tools.
+   debugger, and various associated tools.
 
 -  *Libraries, Headers, and Symbols*: The libraries, headers, and
-   symbols are specific to the image (i.e. they match the image).
+   symbols are specific to the image (i.e. they match the image
+   against which the SDK was built).
 
--  *Environment Setup Script*: This ``*.sh`` file, once run, sets up the
+-  *Environment Setup Script*: This ``*.sh`` file, once sourced, sets up the
    cross-development environment by defining variables and preparing for
    SDK use.
 
@@ -48,14 +49,14 @@ time since that path cannot be dynamically altered. This is the reason
 for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext``
 archives.
 
-Another feature for the SDKs is that only one set of cross-compiler
+Another feature of the SDKs is that only one set of cross-compiler
 toolchain binaries are produced for any given architecture. This feature
 takes advantage of the fact that the target hardware can be passed to
 ``gcc`` as a set of compiler options. Those options are set up by the
 environment script and contained in variables such as
 :term:`CC` and
 :term:`LD`. This reduces the space needed
-for the tools. Understand, however, that every target still needs a
+for the tools. Understand, however, that every target still needs its own
 sysroot because those binaries are target-specific.
 
 The SDK development environment consists of the following:
@@ -118,8 +119,8 @@ The Cross-Development Toolchain
 
 The :term:`Cross-Development Toolchain` consists
 of a cross-compiler, cross-linker, and cross-debugger that are used to
-develop user-space applications for targeted hardware. Additionally, for
-an extensible SDK, the toolchain also has built-in ``devtool``
+develop user-space applications for targeted hardware; in addition,
+the extensible SDK comes with built-in ``devtool``
 functionality. This toolchain is created by running a SDK installer
 script or through a :term:`Build Directory` that is based on
 your metadata configuration or extension for your targeted device. The
@@ -138,21 +139,19 @@ The QEMU Emulator
 -----------------
 
 The QEMU emulator allows you to simulate your hardware while running
-your application or image. QEMU is not part of the SDK but is made
-available a number of different ways:
+your application or image. QEMU is not part of the SDK but is
+automatically installed and available if you have done any one of
+the following:
 
--  If you have cloned the ``poky`` Git repository to create a
-   :term:`Source Directory` and you have
-   sourced the environment setup script, QEMU is installed and
-   automatically available.
+-  cloned the ``poky`` Git repository to create a
+   :term:`Source Directory` and sourced the environment setup script.
 
--  If you have downloaded a Yocto Project release and unpacked it to
-   create a Source Directory and you have sourced the environment setup
-   script, QEMU is installed and automatically available.
+-  downloaded a Yocto Project release and unpacked it to
+   create a Source Directory and sourced the environment setup
+   script.
 
--  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.
+-  installed the cross-toolchain tarball and
+   sourced the toolchain's setup environment script.
 
 SDK Development Model
 =====================
@@ -176,8 +175,8 @@ image.
 You just need to follow these general steps:
 
 1. *Install the SDK for your target hardware:* For information on how to
-   install the SDK, see the "`Installing the
-   SDK <#sdk-installing-the-sdk>`__" section.
+   install the SDK, see the ":ref:`sdk-manual/using:installing the sdk`"
+   section.
 
 2. *Download or Build the Target Image:* The Yocto Project supports
    several target architectures and has many pre-built kernel images and
@@ -202,10 +201,9 @@ You just need to follow these general steps:
 
    .. note::
 
-      To use the root filesystem in QEMU, you need to extract it. See
-      the "
-      Extracting the Root Filesystem
-      " section for information on how to extract the root filesystem.
+      To use the root filesystem in QEMU, you need to extract it. See the
+      ":ref:`sdk-manual/appendix-obtain:extracting the root filesystem`"
+      section for information on how to do this extraction.
 
 3. *Develop and Test your Application:* At this point, you have the
    tools to develop your application. If you need to separately install

documentation/sdk-manual/using.rst

@@ -11,13 +11,13 @@ standard SDK.
 .. note::
 
    For a side-by-side comparison of main features supported for a
-   standard SDK as compared to an extensible SDK, see the "
-   Introduction
-   " section.
+   standard SDK as compared to an extensible SDK, see the
+   ":ref:`sdk-manual/intro:introduction`" section.
 
 You can use a standard SDK to work on Makefile and Autotools-based
-projects. See the "`Using the SDK Toolchain
-Directly <#sdk-working-projects>`__" chapter for more information.
+projects. See the
+":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter
+for more information.
 
 Why use the Standard SDK and What is in It?
 ===========================================
@@ -31,9 +31,9 @@ the extensible SDK, which provides an internal build system and the
 The installed Standard SDK consists of several files and directories.
 Basically, it contains an SDK environment setup script, some
 configuration files, and host and target root filesystems to support
-usage. You can see the directory structure in the "`Installed Standard
-SDK Directory
-Structure <#sdk-installed-standard-sdk-directory-structure>`__" section.
+usage. You can see the directory structure in the
+":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
+section.
 
 Installing the SDK
 ==================
@@ -48,7 +48,7 @@ the Index of Releases. Toolchains are available for several 32-bit and
 64-bit architectures with the ``x86_64`` directories, respectively. The
 toolchains the Yocto Project provides are based off the
 ``core-image-sato`` and ``core-image-minimal`` images and contain
-libraries appropriate for developing against that image.
+libraries appropriate for developing against the corresponding image.
 
 The names of the tarball installer scripts are such that a string
 representing the host system appears first in the filename and then is
@@ -76,17 +76,16 @@ immediately followed by a string representing the target architecture.
 
 For example, the following SDK installer is for a 64-bit
 development host system and a i586-tuned target architecture based off
-the SDK for ``core-image-sato`` and using the current DISTRO snapshot:
-::
+the SDK for ``core-image-sato`` and using the current DISTRO snapshot::
 
    poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh
 
 .. note::
 
    As an alternative to downloading an SDK, you can build the SDK
-   installer. For information on building the installer, see the "
-   Building an SDK Installer
-   " section.
+   installer. For information on building the installer, see the
+   ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
+   section.
 
 The SDK and toolchains are self-contained and by default are installed
 into the ``poky_sdk`` folder in your home directory. You can choose to
@@ -120,9 +119,9 @@ architecture. The example assumes the SDK installer is located in
    Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
     $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
 
-Again, reference the "`Installed Standard SDK Directory
-Structure <#sdk-installed-standard-sdk-directory-structure>`__" section
-for more details on the resulting directory structure of the installed
+Again, reference the
+":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`"
+section for more details on the resulting directory structure of the installed
 SDK.
 
 Running the SDK Environment Setup Script
@@ -140,14 +139,12 @@ begin with the string "``environment-setup``" and include as part of
 their name the tuned target architecture. As an example, the following
 commands set the working directory to where the SDK was installed and
 then source the environment setup script. In this example, the setup
-script is for an IA-based target machine using i586 tuning:
-::
+script is for an IA-based target machine using i586 tuning::
 
    $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
 
 When you run the
 setup script, the same environment variables are defined as are when you
-run the setup script for an extensible SDK. See the "`Running the
-Extensible SDK Environment Setup
-Script <#sdk-running-the-extensible-sdk-environment-setup-script>`__"
+run the setup script for an extensible SDK. See the
+":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`"
 section for more information.

documentation/sdk-manual/working-projects.rst

@@ -45,16 +45,14 @@ project:
    respectively.
 
    Use the following command to create an empty README file, which is
-   required by GNU Coding Standards:
-   ::
+   required by GNU Coding Standards::
 
       $ touch README
 
    Create the remaining
    three files as follows:
 
-   -  ``hello.c``:
-      ::
+   -  ``hello.c``::
 
          #include <stdio.h>
 
@@ -63,8 +61,7 @@ project:
                  printf("Hello World!\n");
              }
 
-   -  ``configure.ac``:
-      ::
+   -  ``configure.ac``::
 
          AC_INIT(hello,0.1)
          AM_INIT_AUTOMAKE([foreign])
@@ -72,8 +69,7 @@ project:
          AC_CONFIG_FILES(Makefile)
          AC_OUTPUT
 
-   -  ``Makefile.am``:
-      ::
+   -  ``Makefile.am``::
 
          bin_PROGRAMS = hello
          hello_SOURCES = hello.c
@@ -87,8 +83,7 @@ project:
    which is followed by the string "poky-linux". For this example, the
    command sources a script from the default SDK installation directory
    that uses the 32-bit Intel x86 Architecture and the &DISTRO; Yocto
-   Project release:
-   ::
+   Project release::
 
       $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
 
@@ -113,8 +108,7 @@ project:
    the cross-compiler. The
    :term:`CONFIGURE_FLAGS`
    environment variable provides the minimal arguments for GNU
-   configure:
-   ::
+   configure::
 
       $ ./configure ${CONFIGURE_FLAGS}
 
@@ -127,14 +121,12 @@ project:
    ``armv5te-poky-linux-gnueabi``. You will notice that the name of the
    script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the
    following command works to update your project and rebuild it using
-   the appropriate cross-toolchain tools:
-   ::
+   the appropriate cross-toolchain tools::
 
      $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
 
 5. *Make and Install the Project:* These two commands generate and
-   install the project into the destination directory:
-   ::
+   install the project into the destination directory::
 
       $ make
       $ make install DESTDIR=./tmp
@@ -157,8 +149,7 @@ project:
 
 6. *Execute Your Project:* To execute the project, you would need to run
    it on your target hardware. If your target hardware happens to be
-   your build host, you could run the project as follows:
-   ::
+   your build host, you could run the project as follows::
 
       $ ./tmp/usr/local/bin/hello
 
@@ -203,8 +194,7 @@ regarding variable behavior:
 .. note::
 
    Regardless of how you set your variables, if you use the "-e" option
-   with ``make``, the variables from the SDK setup script take precedence:
-   ::
+   with ``make``, the variables from the SDK setup script take precedence::
 
       $ make -e target
 
@@ -226,8 +216,7 @@ Running the
 SDK setup script for a 64-bit build host and an i586-tuned target
 architecture for a ``core-image-sato`` image using the current &DISTRO;
 Yocto Project release and then echoing that variable shows the value
-established through the script:
-::
+established through the script::
 
    $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
    $ echo ${CC}
@@ -252,8 +241,7 @@ example:
 
    Create the three files as follows:
 
-   -  ``main.c``:
-      ::
+   -  ``main.c``::
 
          #include "module.h"
          void sample_func();
@@ -263,14 +251,12 @@ example:
              return 0;
          }
 
-   -  ``module.h``:
-      ::
+   -  ``module.h``::
 
          #include <stdio.h>
          void sample_func();
 
-   -  ``module.c``:
-      ::
+   -  ``module.c``::
 
          #include "module.h"
          void sample_func()
@@ -288,8 +274,7 @@ example:
    which is followed by the string "poky-linux". For this example, the
    command sources a script from the default SDK installation directory
    that uses the 32-bit Intel x86 Architecture and the &DISTRO_NAME; Yocto
-   Project release:
-   ::
+   Project release::
 
       $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
 
@@ -297,8 +282,7 @@ example:
    two lines that can be used to set the ``CC`` variable. One line is
    identical to the value that is set when you run the SDK environment
    setup script, and the other line sets ``CC`` to "gcc", the default
-   GNU compiler on the build host:
-   ::
+   GNU compiler on the build host::
 
       # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
       # CC="gcc"
@@ -315,8 +299,7 @@ example:
 4. *Make the Project:* Use the ``make`` command to create the binary
    output file. Because variables are commented out in the Makefile, the
    value used for ``CC`` is the value set when the SDK environment setup
-   file was run:
-   ::
+   file was run::
 
       $ make
       i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
@@ -351,8 +334,7 @@ example:
    variable as part of the command line. Go into the Makefile and
    re-insert the comment character so that running ``make`` uses the
    established SDK compiler. However, when you run ``make``, use a
-   command-line argument to set ``CC`` to "gcc":
-   ::
+   command-line argument to set ``CC`` to "gcc"::
 
       $ make clean
       rm -rf *.o
@@ -376,8 +358,7 @@ example:
    environment variable.
 
    In this last case, edit Makefile again to use the "gcc" compiler but
-   then use the "-e" option on the ``make`` command line:
-   ::
+   then use the "-e" option on the ``make`` command line::
 
       $ make clean
       rm -rf *.o
@@ -402,8 +383,7 @@ example:
    Makefile.
 
 5. *Execute Your Project:* To execute the project (i.e. ``target_bin``),
-   use the following command:
-   ::
+   use the following command::
 
       $ ./target_bin
       Hello World!

documentation/sphinx-static/switchers.js

@@ -2,9 +2,10 @@
   'use strict';
 
   var all_versions = {
-    'dev': 'dev (3.3)',
-    '3.2.3': '3.2.3',
-    '3.1.6': '3.1.6',
+    'dev': 'dev (3.4)',
+    '3.3': '3.3',
+    '3.2.4': '3.2.4',
+    '3.1.7': '3.1.7',
     '3.0.4': '3.0.4',
     '2.7.4': '2.7.4',
   };

documentation/test-manual/test-process.rst

@@ -63,7 +63,7 @@ milestone releases (usually four) with the final one being stabilization
 only along with point releases of our stable branches.
 
 The build and release process for these project releases is similar to
-that in `Day to Day Development <#test-daily-devel>`__, in that the
+that in :ref:`test-manual/test-process:day to day development`, in that the
 a-full target of the Autobuilder is used but in addition the form is
 configured to generate and publish artifacts and the milestone number,
 version, release candidate number and other information is entered. The

documentation/toaster-manual/reference.rst

@@ -32,9 +32,8 @@ through a
 `REST <https://en.wikipedia.org/wiki/Representational_state_transfer>`__
 API, store the information about the layers in the Toaster database, and
 then show the information to users. Users are then able to view that
-information and build layers from Toaster itself without worrying about
-cloning or editing the BitBake layers configuration file
-``bblayers.conf``.
+information and build layers from Toaster itself without having to
+clone or edit the BitBake layers configuration file ``bblayers.conf``.
 
 Tying a layer source into Toaster is convenient when you have many
 custom layers that need to be built on a regular basis by a community of
@@ -187,7 +186,7 @@ Configuring the Workflow
 ------------------------
 
 The ``bldcontrol/management/commands/checksettings.py`` file controls
-workflow configuration. The following steps outline the process to
+workflow configuration. Here is the process to
 initially populate this database.
 
 1. The default project settings are set from
@@ -238,7 +237,7 @@ The following example sets "name" to "CUSTOM_XML_ONLY" and its value to
 Understanding Fixture File Format
 ---------------------------------
 
-The following is an overview of the file format used by the
+Here is an overview of the file format used by the
 ``oe-core.xml``, ``poky.xml``, and ``custom.xml`` files.
 
 The following subsections describe each of the sections in the fixture
@@ -408,7 +407,7 @@ To get the status of pending builds, use the following call::
 Be sure to provide values for host and port. The output is a JSON file that
 itemizes all builds in progress. This file includes the time in seconds since
 each respective build started as well as the progress of the cloning, parsing,
-and task execution. The following is sample output for a build in progress:
+and task execution. Here is sample output for a build in progress:
 
 .. code-block:: JSON
 
@@ -441,8 +440,8 @@ call::
    http://host:port/toastergui/api/builds
 
 Be sure to provide values for host and port. The output is a JSON file that
-itemizes all complete builds, and includes build summary information. The
-following is sample output for a completed build:
+itemizes all complete builds, and includes build summary information. Here
+is sample output for a completed build:
 
 .. code-block:: JSON
 
@@ -480,7 +479,7 @@ Completed query. See the ":ref:`toaster-manual/reference:checking status of buil
 section for more information.
 
 The output is a JSON file that itemizes the specific build and includes
-build summary information. The following is sample output for a specific
+build summary information. Here is sample output for a specific
 build:
 
 .. code-block:: JSON

meta-poky/conf/distro/poky.conf

@@ -1,7 +1,7 @@
 DISTRO = "poky"
 DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
-DISTRO_VERSION = "3.3"
-DISTRO_CODENAME = "hardknott"
+DISTRO_VERSION = "3.3+snapshot-${METADATA_REVISION}"
+DISTRO_CODENAME = "master"
 SDK_VENDOR = "-pokysdk"
 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}"
 SDK_VERSION[vardepvalue] = "${SDK_VERSION}"

meta-poky/conf/local.conf.sample

@@ -148,11 +148,8 @@ EXTRA_IMAGE_FEATURES ?= "debug-tweaks"
 # enable extra features. Some available options which can be included in this variable
 # are:
 #   - 'buildstats' collect build statistics
-#   - 'image-mklibs' to reduce shared library files size for an image
 #   - 'image-prelink' in order to prelink the filesystem image
-# NOTE: if listing mklibs & prelink both, then make sure mklibs is before prelink
-# NOTE: mklibs also needs to be explicitly enabled for a given image, see local.conf.extended
-USER_CLASSES ?= "buildstats image-mklibs image-prelink"
+USER_CLASSES ?= "buildstats image-prelink"
 
 #
 # Runtime testing of images
@@ -188,7 +185,7 @@ PATCHRESOLVE = "noop"
 #
 # Monitor the disk space during the build. If there is less that 1GB of space or less
 # than 100K inodes in any key build location (TMPDIR, DL_DIR, SSTATE_DIR), gracefully
-# shutdown the build. If there is less that 100MB or 1K inodes, perform a hard abort
+# shutdown the build. If there is less than 100MB or 1K inodes, perform a hard abort
 # of the build. The reason for this is that running completely out of space can corrupt
 # files and damages the build in ways which may not be easily recoverable.
 # It's necessary to monitor /tmp, if there is no space left the build will fail

meta-poky/conf/local.conf.sample.extended

@@ -119,15 +119,6 @@ DISTRO_FEATURES_remove = "x11"
 #
 # TCMODE ?= "external-sourcery"
 
-# mklibs library size optimization is more useful to smaller images,
-# and less useful for bigger images. Also mklibs library optimization
-# can break the ABI compatibility, so should not be applied to the
-# images which are to be extended or upgraded later.
-#This enabled mklibs library size optimization just for the specified image.
-#MKLIBS_OPTIMIZED_IMAGES ?= "core-image-minimal"
-#This enable mklibs library size optimization will be for all the images.
-#MKLIBS_OPTIMIZED_IMAGES ?= "all"
-
 # This value is currently used by pseudo to determine if the recipe should
 # build both the 32-bit and 64-bit wrapper libraries on a 64-bit build system.
 #

meta-selftest/conf/layer.conf

@@ -9,4 +9,4 @@ BBFILE_COLLECTIONS += "selftest"
 BBFILE_PATTERN_selftest = "^${LAYERDIR}/"
 BBFILE_PRIORITY_selftest = "5"
 
-LAYERSERIES_COMPAT_selftest = "hardknott"
+LAYERSERIES_COMPAT_selftest = "honister"

meta-skeleton/conf/layer.conf

@@ -14,4 +14,4 @@ LAYERVERSION_skeleton = "1"
 
 LAYERDEPENDS_skeleton = "core"
 
-LAYERSERIES_COMPAT_skeleton = "hardknott"
+LAYERSERIES_COMPAT_skeleton = "honister"

meta-skeleton/recipes-baremetal/baremetal-examples/baremetal-helloworld_git.bb

@@ -4,7 +4,7 @@ DESCRIPTION = "These are introductory examples to showcase the use of QEMU to ru
 LICENSE = "MIT"
 LIC_FILES_CHKSUM = "file://LICENSE;md5=39346640a23c701e4f459e05f56f4449"
 
-SRCREV = "99f4fa4a3b266b42b52af302610b0f4f429ba5e3"
+SRCREV = "0bf9ea216e6f76be50726a3a74e527b7bbb0ad93"
 PV = "0.1+git${SRCPV}"
 
 SRC_URI = "git://github.com/aehs29/baremetal-helloqemu.git;protocol=https;branch=master"
@@ -28,12 +28,13 @@ inherit baremetal-image
 # machine that QEMU uses on OE, e.g. -machine virt -cpu cortex-a57
 # but the examples can also be run on other architectures/machines
 # such as vexpress-a15 by overriding the setting on the machine.conf
-COMPATIBLE_MACHINE = "qemuarmv5|qemuarm|qemuarm64"
+COMPATIBLE_MACHINE = "qemuarmv5|qemuarm|qemuarm64|qemuriscv64"
 
 BAREMETAL_QEMUARCH ?= ""
 BAREMETAL_QEMUARCH_qemuarmv5 = "versatile"
 BAREMETAL_QEMUARCH_qemuarm = "arm"
 BAREMETAL_QEMUARCH_qemuarm64 = "aarch64"
+BAREMETAL_QEMUARCH_qemuriscv64 = "riscv64"
 
 EXTRA_OEMAKE_append = " QEMUARCH=${BAREMETAL_QEMUARCH} V=1"