build-appliance-image: Update to master head revision

(From OE-Core rev: c4fc226c2e3856b942bb4f57ead21a64c3dc8c0d)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

README.hardware

@@ -1 +0,0 @@
-meta-yocto-bsp/README.hardware

README.hardware.md

@@ -0,0 +1 @@
+meta-yocto-bsp/README.hardware.md

README.md

@@ -0,0 +1 @@
+README.poky.md

README.poky

@@ -1 +0,0 @@
-meta-poky/README.poky

README.poky.md

@@ -0,0 +1 @@
+meta-poky/README.poky.md

bitbake/bin/bitbake-selftest

@@ -29,6 +29,7 @@ tests = ["bb.tests.codeparser",
          "bb.tests.runqueue",
          "bb.tests.siggen",
          "bb.tests.utils",
+         "bb.tests.compression",
          "hashserv.tests",
          "layerindexlib.tests.layerindexobj",
          "layerindexlib.tests.restapi",

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

@@ -648,13 +648,6 @@ compiled binary. To handle this, BitBake calls the
 each successful setscene task to know whether or not it needs to obtain
 the dependencies of that task.
 
-Finally, after all the setscene tasks have executed, BitBake calls the
-function listed in
-:term:`BB_SETSCENE_VERIFY_FUNCTION2`
-with the list of tasks BitBake thinks has been "covered". The metadata
-can then ensure that this list is correct and can inform BitBake that it
-wants specific tasks to be run regardless of the setscene result.
-
 You can find more information on setscene metadata in the
 :ref:`bitbake-user-manual/bitbake-user-manual-metadata:task checksums and setscene`
 section.

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

@@ -1650,10 +1650,15 @@ user interfaces:
 Variants - Class Extension Mechanism
 ====================================
 
-BitBake supports two features that facilitate creating from a single
-recipe file multiple incarnations of that recipe file where all
-incarnations are buildable. These features are enabled through the
-:term:`BBCLASSEXTEND` and :term:`BBVERSIONS` variables.
+BitBake supports multiple incarnations of a recipe file via the
+:term:`BBCLASSEXTEND` variable.
+
+The :term:`BBCLASSEXTEND` variable is a space separated list of classes used
+to "extend" the recipe for each variant. Here is an example that results in a
+second incarnation of the current recipe being available. This second
+incarnation will have the "native" class inherited. ::
+
+      BBCLASSEXTEND = "native"
 
 .. note::
 
@@ -1663,34 +1668,6 @@ incarnations are buildable. These features are enabled through the
    class. For specific examples, see the OE-Core native , nativesdk , and
    multilib classes.
 
--  ``BBCLASSEXTEND``: This variable is a space separated list of
-   classes used to "extend" the recipe for each variant. Here is an
-   example that results in a second incarnation of the current recipe
-   being available. This second incarnation will have the "native" class
-   inherited. ::
-
-      BBCLASSEXTEND = "native"
-
--  ``BBVERSIONS``: This variable allows a single recipe to build
-   multiple versions of a project from a single recipe file. You can
-   also specify conditional metadata (using the
-   :term:`OVERRIDES` mechanism) for a single
-   version, or an optionally named range of versions. Here is an
-   example::
-
-      BBVERSIONS = "1.0 2.0 git"
-      SRC_URI_git = "git://someurl/somepath.git"
-
-      BBVERSIONS = "1.0.[0-6]:1.0.0+ 1.0.[7-9]:1.0.7+"
-      SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"
-
-   The name of the range defaults to the original version of the recipe. For
-   example, in OpenEmbedded, the recipe file ``foo_1.0.0+.bb`` creates a default
-   name range of ``1.0.0+``. This is useful because the range name is not only
-   placed into overrides, but it is also made available for the metadata to use
-   in the variable that defines the base recipe versions for use in ``file://``
-   search paths (:term:`FILESPATH`).
-
 Dependencies
 ============
 
@@ -1943,10 +1920,6 @@ The following list describes related variables:
    Specifies a function BitBake calls that determines whether BitBake
    requires a setscene dependency to be met.
 
--  :term:`BB_SETSCENE_VERIFY_FUNCTION2`:
-   Specifies a function to call that verifies the list of planned task
-   execution before the main task execution happens.
-
 -  :term:`BB_STAMP_POLICY`: Defines the mode
    for comparing timestamps of stamp files.
 

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

@@ -23,10 +23,6 @@ overview of their function and contents.
       systems extend the functionality of the variable as it is
       described here in this glossary.
 
-   -  Finally, there are variables mentioned in this glossary that do
-      not appear in the BitBake glossary. These other variables are
-      variables used in systems that use BitBake.
-
 .. glossary::
 
    :term:`ASSUME_PROVIDED`
@@ -313,6 +309,16 @@ overview of their function and contents.
       However, the more accurate the data returned, the more efficient the
       build will be.
 
+   :term:`BB_HASHSERVE`
+      Specifies the Hash Equivalence server to use.
+
+      If set to ``auto``, BitBake automatically starts its own server
+      over a UNIX domain socket.
+
+      If set to ``host:port``, BitBake will use a remote server on the
+      specified host. This allows multiple clients to share the same
+      hash equivalence data.
+
    :term:`BB_INVALIDCONF`
       Used in combination with the ``ConfigParsed`` event to trigger
       re-parsing the base metadata (i.e. all the recipes). The
@@ -426,17 +432,6 @@ overview of their function and contents.
       The function specified by this variable returns a "True" or "False"
       depending on whether the dependency needs to be met.
 
-   :term:`BB_SETSCENE_VERIFY_FUNCTION2`
-      Specifies a function to call that verifies the list of planned task
-      execution before the main task execution happens. The function is
-      called once BitBake has a list of setscene tasks that have run and
-      either succeeded or failed.
-
-      The function allows for a task list check to see if they make sense.
-      Even if BitBake was planning to skip a task, the returned value of
-      the function can force BitBake to run the task, which is necessary
-      under certain metadata defined circumstances.
-
    :term:`BB_SIGNATURE_EXCLUDE_FLAGS`
       Lists variable flags (varflags) that can be safely excluded from
       checksum and dependency data for keys in the datastore. When
@@ -797,16 +792,6 @@ overview of their function and contents.
       Allows you to use a configuration file to add to the list of
       command-line target recipes you want to build.
 
-   :term:`BBVERSIONS`
-      Allows a single recipe to build multiple versions of a project from a
-      single recipe file. You also able to specify conditional metadata
-      using the :term:`OVERRIDES` mechanism for a
-      single version or for an optionally named range of versions.
-
-      For more information on ``BBVERSIONS``, see the
-      ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variants - class extension mechanism`"
-      section.
-
    :term:`BITBAKE_UI`
       Used to specify the UI module to use when running BitBake. Using this
       variable is equivalent to using the ``-u`` command-line option.

bitbake/lib/bb/asyncrpc/client.py

@@ -103,13 +103,18 @@ class AsyncClient(object):
 
         return await self._send_wrapper(proc)
 
+    async def ping(self):
+        return await self.send_message(
+            {'ping': {}}
+        )
+
 
 class Client(object):
     def __init__(self):
         self.client = self._get_async_client()
         self.loop = asyncio.new_event_loop()
 
-        self._add_methods('connect_tcp', 'close')
+        self._add_methods('connect_tcp', 'close', 'ping')
 
     @abc.abstractmethod
     def _get_async_client(self):

bitbake/lib/bb/asyncrpc/serv.py

@@ -28,6 +28,7 @@ class AsyncServerConnection(object):
         self.max_chunk = DEFAULT_MAX_CHUNK
         self.handlers = {
             'chunk-stream': self.handle_chunk,
+            'ping': self.handle_ping,
         }
         self.logger = logger
 
@@ -123,6 +124,10 @@ class AsyncServerConnection(object):
 
         await self.dispatch_message(msg)
 
+    async def handle_ping(self, request):
+        response = {'alive': True}
+        self.write_message(response)
+
 
 class AsyncServer(object):
     def __init__(self, logger, loop=None):
@@ -142,7 +147,7 @@ class AsyncServer(object):
         )
 
         for s in self.server.sockets:
-            self.logger.info('Listening on %r' % (s.getsockname(),))
+            self.logger.debug('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)
@@ -168,7 +173,7 @@ class AsyncServer(object):
         finally:
             os.chdir(cwd)
 
-        self.logger.info('Listening on %r' % path)
+        self.logger.debug('Listening on %r' % path)
 
         self._cleanup_socket = cleanup
         self.address = "unix://%s" % os.path.abspath(path)
@@ -187,7 +192,7 @@ class AsyncServer(object):
             self.logger.error('Error from client: %s' % str(e), exc_info=True)
             traceback.print_exc()
             writer.close()
-        self.logger.info('Client disconnected')
+        self.logger.debug('Client disconnected')
 
     def run_loop_forever(self):
         try:
@@ -207,7 +212,7 @@ class AsyncServer(object):
             self.server.close()
 
             self.loop.run_until_complete(self.server.wait_closed())
-            self.logger.info('Server shutting down')
+            self.logger.debug('Server shutting down')
         finally:
             if self.close_loop:
                 if sys.version_info >= (3, 6):

bitbake/lib/bb/build.py

@@ -927,6 +927,11 @@ def add_tasks(tasklist, d):
                 task_deps[name] = {}
             if name in flags:
                 deptask = d.expand(flags[name])
+                if name in ['noexec', 'fakeroot', 'nostamp']:
+                    if deptask != '1':
+                        bb.warn("In a future version of BitBake, setting the '{}' flag to something other than '1' "
+                                "will result in the flag not being set. See YP bug #13808.".format(name))
+
                 task_deps[name][task] = deptask
         getTask('mcdepends')
         getTask('depends')

bitbake/lib/bb/compress/_pipecompress.py

@@ -0,0 +1,194 @@
+#
+# SPDX-License-Identifier: GPL-2.0-only
+#
+# Helper library to implement streaming compression and decompression using an
+# external process
+#
+# This library should be used directly by end users; a wrapper library for the
+# specific compression tool should be created
+
+import builtins
+import io
+import os
+import subprocess
+
+
+def open_wrap(
+    cls, filename, mode="rb", *, encoding=None, errors=None, newline=None, **kwargs
+):
+    """
+    Open a compressed file in binary or text mode.
+
+    Users should not call this directly. A specific compression library can use
+    this helper to provide it's own "open" command
+
+    The filename argument can be an actual filename (a str or bytes object), or
+    an existing file object to read from or write to.
+
+    The mode argument can be "r", "rb", "w", "wb", "x", "xb", "a" or "ab" for
+    binary mode, or "rt", "wt", "xt" or "at" for text mode. The default mode is
+    "rb".
+
+    For binary mode, this function is equivalent to the cls constructor:
+    cls(filename, mode). In this case, the encoding, errors and newline
+    arguments must not be provided.
+
+    For text mode, a cls object is created, and wrapped in an
+    io.TextIOWrapper instance with the specified encoding, error handling
+    behavior, and line ending(s).
+    """
+    if "t" in mode:
+        if "b" in mode:
+            raise ValueError("Invalid mode: %r" % (mode,))
+    else:
+        if encoding is not None:
+            raise ValueError("Argument 'encoding' not supported in binary mode")
+        if errors is not None:
+            raise ValueError("Argument 'errors' not supported in binary mode")
+        if newline is not None:
+            raise ValueError("Argument 'newline' not supported in binary mode")
+
+    file_mode = mode.replace("t", "")
+    if isinstance(filename, (str, bytes, os.PathLike)):
+        binary_file = cls(filename, file_mode, **kwargs)
+    elif hasattr(filename, "read") or hasattr(filename, "write"):
+        binary_file = cls(None, file_mode, fileobj=filename, **kwargs)
+    else:
+        raise TypeError("filename must be a str or bytes object, or a file")
+
+    if "t" in mode:
+        return io.TextIOWrapper(
+            binary_file, encoding, errors, newline, write_through=True
+        )
+    else:
+        return binary_file
+
+
+class CompressionError(OSError):
+    pass
+
+
+class PipeFile(io.RawIOBase):
+    """
+    Class that implements generically piping to/from a compression program
+
+    Derived classes should add the function get_compress() and get_decompress()
+    that return the required commands. Input will be piped into stdin and the
+    (de)compressed output should be written to stdout, e.g.:
+
+        class FooFile(PipeCompressionFile):
+            def get_decompress(self):
+                return ["fooc", "--decompress", "--stdout"]
+
+            def get_compress(self):
+                return ["fooc", "--compress", "--stdout"]
+
+    """
+
+    READ = 0
+    WRITE = 1
+
+    def __init__(self, filename=None, mode="rb", *, stderr=None, fileobj=None):
+        if "t" in mode or "U" in mode:
+            raise ValueError("Invalid mode: {!r}".format(mode))
+
+        if not "b" in mode:
+            mode += "b"
+
+        if mode.startswith("r"):
+            self.mode = self.READ
+        elif mode.startswith("w"):
+            self.mode = self.WRITE
+        else:
+            raise ValueError("Invalid mode %r" % mode)
+
+        if fileobj is not None:
+            self.fileobj = fileobj
+        else:
+            self.fileobj = builtins.open(filename, mode or "rb")
+
+        if self.mode == self.READ:
+            self.p = subprocess.Popen(
+                self.get_decompress(),
+                stdin=self.fileobj,
+                stdout=subprocess.PIPE,
+                stderr=stderr,
+                close_fds=True,
+            )
+            self.pipe = self.p.stdout
+        else:
+            self.p = subprocess.Popen(
+                self.get_compress(),
+                stdin=subprocess.PIPE,
+                stdout=self.fileobj,
+                stderr=stderr,
+                close_fds=True,
+            )
+            self.pipe = self.p.stdin
+
+        self.__closed = False
+
+    def _check_process(self):
+        if self.p is None:
+            return
+
+        returncode = self.p.wait()
+        if returncode:
+            raise CompressionError("Process died with %d" % returncode)
+        self.p = None
+
+    def close(self):
+        if self.closed:
+            return
+
+        self.pipe.close()
+        if self.p is not None:
+            self._check_process()
+        self.fileobj.close()
+
+        self.__closed = True
+
+    @property
+    def closed(self):
+        return self.__closed
+
+    def fileno(self):
+        return self.pipe.fileno()
+
+    def flush(self):
+        self.pipe.flush()
+
+    def isatty(self):
+        return self.pipe.isatty()
+
+    def readable(self):
+        return self.mode == self.READ
+
+    def writable(self):
+        return self.mode == self.WRITE
+
+    def readinto(self, b):
+        if self.mode != self.READ:
+            import errno
+
+            raise OSError(
+                errno.EBADF, "read() on write-only %s object" % self.__class__.__name__
+            )
+        size = self.pipe.readinto(b)
+        if size == 0:
+            self._check_process()
+        return size
+
+    def write(self, data):
+        if self.mode != self.WRITE:
+            import errno
+
+            raise OSError(
+                errno.EBADF, "write() on read-only %s object" % self.__class__.__name__
+            )
+        data = self.pipe.write(data)
+
+        if not data:
+            self._check_process()
+
+        return data

bitbake/lib/bb/compress/lz4.py

@@ -0,0 +1,17 @@
+#
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+import bb.compress._pipecompress
+
+
+def open(*args, **kwargs):
+    return bb.compress._pipecompress.open_wrap(LZ4File, *args, **kwargs)
+
+
+class LZ4File(bb.compress._pipecompress.PipeFile):
+    def get_compress(self):
+        return ["lz4c", "-z", "-c"]
+
+    def get_decompress(self):
+        return ["lz4c", "-d", "-c"]

bitbake/lib/bb/compress/zstd.py

@@ -0,0 +1,28 @@
+#
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+import bb.compress._pipecompress
+import shutil
+
+
+def open(*args, **kwargs):
+    return bb.compress._pipecompress.open_wrap(ZstdFile, *args, **kwargs)
+
+
+class ZstdFile(bb.compress._pipecompress.PipeFile):
+    def __init__(self, *args, num_threads=1, compresslevel=3, **kwargs):
+        self.num_threads = num_threads
+        self.compresslevel = compresslevel
+        super().__init__(*args, **kwargs)
+
+    def _get_zstd(self):
+        if self.num_threads == 1 or not shutil.which("pzstd"):
+            return ["zstd"]
+        return ["pzstd", "-p", "%d" % self.num_threads]
+
+    def get_compress(self):
+        return self._get_zstd() + ["-c", "-%d" % self.compresslevel]
+
+    def get_decompress(self):
+        return self._get_zstd() + ["-d", "-c"]

bitbake/lib/bb/data_smart.py

@@ -481,6 +481,7 @@ class DataSmart(MutableMapping):
 
     def setVar(self, var, value, **loginfo):
         #print("var=" + str(var) + "  val=" + str(value))
+        var = var.replace(":", "_")
         self.expand_cache = {}
         parsing=False
         if 'parsing' in loginfo:
@@ -589,6 +590,8 @@ class DataSmart(MutableMapping):
         """
         Rename the variable key to newkey
         """
+        key = key.replace(":", "_")
+        newkey = newkey.replace(":", "_")
         if key == newkey:
             bb.warn("Calling renameVar with equivalent keys (%s) is invalid" % key)
             return
@@ -637,6 +640,7 @@ class DataSmart(MutableMapping):
         self.setVar(var + "_prepend", value, ignore=True, parsing=True)
 
     def delVar(self, var, **loginfo):
+        var = var.replace(":", "_")
         self.expand_cache = {}
 
         loginfo['detail'] = ""
@@ -664,6 +668,7 @@ class DataSmart(MutableMapping):
                          override = None
 
     def setVarFlag(self, var, flag, value, **loginfo):
+        var = var.replace(":", "_")
         self.expand_cache = {}
 
         if 'op' not in loginfo:
@@ -687,6 +692,7 @@ class DataSmart(MutableMapping):
             self.dict["__exportlist"]["_content"].add(var)
 
     def getVarFlag(self, var, flag, expand=True, noweakdefault=False, parsing=False, retparser=False):
+        var = var.replace(":", "_")
         if flag == "_content":
             cachename = var
         else:
@@ -814,6 +820,7 @@ class DataSmart(MutableMapping):
         return value
 
     def delVarFlag(self, var, flag, **loginfo):
+        var = var.replace(":", "_")
         self.expand_cache = {}
 
         local_var, _ = self._findVar(var)
@@ -831,6 +838,7 @@ class DataSmart(MutableMapping):
             del self.dict[var][flag]
 
     def appendVarFlag(self, var, flag, value, **loginfo):
+        var = var.replace(":", "_")
         loginfo['op'] = 'append'
         loginfo['flag'] = flag
         self.varhistory.record(**loginfo)
@@ -838,6 +846,7 @@ class DataSmart(MutableMapping):
         self.setVarFlag(var, flag, newvalue, ignore=True)
 
     def prependVarFlag(self, var, flag, value, **loginfo):
+        var = var.replace(":", "_")
         loginfo['op'] = 'prepend'
         loginfo['flag'] = flag
         self.varhistory.record(**loginfo)
@@ -845,6 +854,7 @@ class DataSmart(MutableMapping):
         self.setVarFlag(var, flag, newvalue, ignore=True)
 
     def setVarFlags(self, var, flags, **loginfo):
+        var = var.replace(":", "_")
         self.expand_cache = {}
         infer_caller_details(loginfo)
         if not var in self.dict:
@@ -859,6 +869,7 @@ class DataSmart(MutableMapping):
             self.dict[var][i] = flags[i]
 
     def getVarFlags(self, var, expand = False, internalflags=False):
+        var = var.replace(":", "_")
         local_var, _ = self._findVar(var)
         flags = {}
 
@@ -875,6 +886,7 @@ class DataSmart(MutableMapping):
 
 
     def delVarFlags(self, var, **loginfo):
+        var = var.replace(":", "_")
         self.expand_cache = {}
         if not var in self.dict:
             self._makeShadowCopy(var)

bitbake/lib/bb/fetch2/__init__.py

@@ -562,6 +562,9 @@ def verify_checksum(ud, d, precomputed={}):
 
         checksum_expected = getattr(ud, "%s_expected" % checksum_id)
 
+        if checksum_expected == '':
+            checksum_expected = None
+
         return {
             "id": checksum_id,
             "name": checksum_name,
@@ -612,7 +615,7 @@ def verify_checksum(ud, d, precomputed={}):
 
     for ci in checksum_infos:
         if ci["expected"] and ci["expected"] != ci["data"]:
-            messages.append("File: '%s' has %s checksum %s when %s was " \
+            messages.append("File: '%s' has %s checksum '%s' when '%s' was " \
                             "expected" % (ud.localpath, ci["id"], ci["data"], ci["expected"]))
             bad_checksum = ci["data"]
 
@@ -831,7 +834,10 @@ def runfetchcmd(cmd, d, quiet=False, cleanup=None, log=None, workdir=None):
                   'SSH_AUTH_SOCK', 'SSH_AGENT_PID',
                   'SOCKS5_USER', 'SOCKS5_PASSWD',
                   'DBUS_SESSION_BUS_ADDRESS',
-                  'P4CONFIG']
+                  'P4CONFIG',
+                  'AWS_ACCESS_KEY_ID',
+                  'AWS_SECRET_ACCESS_KEY',
+                  'AWS_DEFAULT_REGION']
 
     if not cleanup:
         cleanup = []

bitbake/lib/bb/fetch2/git.py

@@ -231,7 +231,7 @@ class Git(FetchMethod):
             for name in ud.names:
                 ud.unresolvedrev[name] = 'HEAD'
 
-        ud.basecmd = d.getVar("FETCHCMD_git") or "git -c core.fsyncobjectfiles=0"
+        ud.basecmd = d.getVar("FETCHCMD_git") or "git -c core.fsyncobjectfiles=0 -c gc.autoDetach=false"
 
         write_tarballs = d.getVar("BB_GENERATE_MIRROR_TARBALLS") or "0"
         ud.write_tarballs = write_tarballs != "0" or ud.rebaseable

bitbake/lib/bb/parse/ast.py

@@ -97,6 +97,7 @@ class DataNode(AstNode):
     def eval(self, data):
         groupd = self.groupd
         key = groupd["var"]
+        key = key.replace(":", "_")
         loginfo = {
             'variable': key,
             'file': self.filename,
@@ -207,6 +208,7 @@ class ExportFuncsNode(AstNode):
     def eval(self, data):
 
         for func in self.n:
+            func = func.replace(":", "_")
             calledfunc = self.classname + "_" + func
 
             if data.getVar(func, False) and not data.getVarFlag(func, 'export_func', False):

bitbake/lib/bb/parse/parse_py/BBHandler.py

@@ -22,7 +22,7 @@ from .ConfHandler import include, init
 # For compatibility
 bb.deprecate_import(__name__, "bb.parse", ["vars_from_file"])
 
-__func_start_regexp__    = re.compile(r"(((?P<py>python(?=(\s|\()))|(?P<fr>fakeroot(?=\s)))\s*)*(?P<func>[\w\.\-\+\{\}\$]+)?\s*\(\s*\)\s*{$" )
+__func_start_regexp__    = re.compile(r"(((?P<py>python(?=(\s|\()))|(?P<fr>fakeroot(?=\s)))\s*)*(?P<func>[\w\.\-\+\{\}\$:]+)?\s*\(\s*\)\s*{$" )
 __inherit_regexp__       = re.compile(r"inherit\s+(.+)" )
 __export_func_regexp__   = re.compile(r"EXPORT_FUNCTIONS\s+(.+)" )
 __addtask_regexp__       = re.compile(r"addtask\s+(?P<func>\w+)\s*((before\s*(?P<before>((.*(?=after))|(.*))))|(after\s*(?P<after>((.*(?=before))|(.*)))))*")

bitbake/lib/bb/parse/parse_py/ConfHandler.py

@@ -20,7 +20,7 @@ from bb.parse import ParseError, resolve_file, ast, logger, handle
 __config_regexp__  = re.compile( r"""
     ^
     (?P<exp>export\s+)?
-    (?P<var>[a-zA-Z0-9\-_+.${}/~]+?)
+    (?P<var>[a-zA-Z0-9\-_+.${}/~:]+?)
     (\[(?P<flag>[a-zA-Z0-9\-_+.]+)\])?
 
     \s* (

bitbake/lib/bb/providers.py

@@ -133,7 +133,7 @@ def findPreferredProvider(pn, cfgData, dataCache, pkg_pn = None, item = None):
 
     if required_v is not None:
         if preferred_v is not None:
-            logger.warn("REQUIRED_VERSION and PREFERRED_VERSION for package %s%s are both set using REQUIRED_VERSION %s", pn, itemstr, required_v)
+            logger.warning("REQUIRED_VERSION and PREFERRED_VERSION for package %s%s are both set using REQUIRED_VERSION %s", pn, itemstr, required_v)
         else:
             logger.debug("REQUIRED_VERSION is set for package %s%s", pn, itemstr)
         # REQUIRED_VERSION always takes precedence over PREFERRED_VERSION
@@ -173,7 +173,7 @@ def findPreferredProvider(pn, cfgData, dataCache, pkg_pn = None, item = None):
             pv_str = '%s:%s' % (preferred_e, pv_str)
         if preferred_file is None:
             if not required:
-                logger.warn("preferred version %s of %s not available%s", pv_str, pn, itemstr)
+                logger.warning("preferred version %s of %s not available%s", pv_str, pn, itemstr)
             available_vers = []
             for file_set in pkg_pn:
                 for f in file_set:
@@ -185,7 +185,7 @@ def findPreferredProvider(pn, cfgData, dataCache, pkg_pn = None, item = None):
                         available_vers.append(ver_str)
             if available_vers:
                 available_vers.sort()
-                logger.warn("versions of %s available: %s", pn, ' '.join(available_vers))
+                logger.warning("versions of %s available: %s", pn, ' '.join(available_vers))
             if required:
                 logger.error("required version %s of %s not available%s", pv_str, pn, itemstr)
         else:

bitbake/lib/bb/server/process.py

@@ -147,7 +147,7 @@ class ProcessServer():
                 conn = newconnections.pop(-1)
                 fds.append(conn)
                 self.controllersock = conn
-            elif self.timeout is None and not ready:
+            elif not self.timeout and not ready:
                 serverlog("No timeout, exiting.")
                 self.quit = True
 

bitbake/lib/bb/tests/compression.py

@@ -0,0 +1,98 @@
+#
+# SPDX-License-Identifier: GPL-2.0-only
+#
+
+from pathlib import Path
+import bb.compress.lz4
+import bb.compress.zstd
+import contextlib
+import os
+import shutil
+import tempfile
+import unittest
+import subprocess
+
+
+class CompressionTests(object):
+    def setUp(self):
+        self._t = tempfile.TemporaryDirectory()
+        self.tmpdir = Path(self._t.name)
+        self.addCleanup(self._t.cleanup)
+
+    def _file_helper(self, mode_suffix, data):
+        tmp_file = self.tmpdir / "compressed"
+
+        with self.do_open(tmp_file, mode="w" + mode_suffix) as f:
+            f.write(data)
+
+        with self.do_open(tmp_file, mode="r" + mode_suffix) as f:
+            read_data = f.read()
+
+        self.assertEqual(read_data, data)
+
+    def test_text_file(self):
+        self._file_helper("t", "Hello")
+
+    def test_binary_file(self):
+        self._file_helper("b", "Hello".encode("utf-8"))
+
+    def _pipe_helper(self, mode_suffix, data):
+        rfd, wfd = os.pipe()
+        with open(rfd, "rb") as r, open(wfd, "wb") as w:
+            with self.do_open(r, mode="r" + mode_suffix) as decompress:
+                with self.do_open(w, mode="w" + mode_suffix) as compress:
+                    compress.write(data)
+                read_data = decompress.read()
+
+        self.assertEqual(read_data, data)
+
+    def test_text_pipe(self):
+        self._pipe_helper("t", "Hello")
+
+    def test_binary_pipe(self):
+        self._pipe_helper("b", "Hello".encode("utf-8"))
+
+    def test_bad_decompress(self):
+        tmp_file = self.tmpdir / "compressed"
+        with tmp_file.open("wb") as f:
+            f.write(b"\x00")
+
+        with self.assertRaises(OSError):
+            with self.do_open(tmp_file, mode="rb", stderr=subprocess.DEVNULL) as f:
+                data = f.read()
+
+
+class LZ4Tests(CompressionTests, unittest.TestCase):
+    def setUp(self):
+        if shutil.which("lz4c") is None:
+            self.skipTest("'lz4c' not found")
+        super().setUp()
+
+    @contextlib.contextmanager
+    def do_open(self, *args, **kwargs):
+        with bb.compress.lz4.open(*args, **kwargs) as f:
+            yield f
+
+
+class ZStdTests(CompressionTests, unittest.TestCase):
+    def setUp(self):
+        if shutil.which("zstd") is None:
+            self.skipTest("'zstd' not found")
+        super().setUp()
+
+    @contextlib.contextmanager
+    def do_open(self, *args, **kwargs):
+        with bb.compress.zstd.open(*args, **kwargs) as f:
+            yield f
+
+
+class PZStdTests(CompressionTests, unittest.TestCase):
+    def setUp(self):
+        if shutil.which("pzstd") is None:
+            self.skipTest("'pzstd' not found")
+        super().setUp()
+
+    @contextlib.contextmanager
+    def do_open(self, *args, **kwargs):
+        with bb.compress.zstd.open(*args, num_threads=2, **kwargs) as f:
+            yield f

documentation/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?= -j auto
+SPHINXOPTS    ?= -W --keep-going -j auto
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

documentation/README

@@ -32,7 +32,7 @@ these instances.
 Manual Organization
 ===================
 
-Folders exist for individual manuals as follows:
+Here the folders corresponding to individual manuals:
 
 * sdk-manual           - The Yocto Project Software Development Kit (SDK) Developer's Guide.
 * bsp-guide            - The Yocto Project Board Support Package (BSP) Developer's Guide
@@ -88,8 +88,8 @@ documentation.
 Yocto Project documentation website
 ===================================
 
-A new website has been created to host the Yocto Project
-documentation, it can be found at: https://docs.yoctoproject.org/.
+The website hosting the Yocto Project documentation, can be found
+at: https://docs.yoctoproject.org/.
 
 The entire Yocto Project documentation, as well as the BitBake manual,
 is published on this website, including all previously released

documentation/brief-yoctoprojectqs/index.rst

@@ -297,7 +297,7 @@ modular development and makes it easier to reuse the layer metadata.
 
 Follow these steps to add a hardware layer:
 
-#. **Find a Layer:** Lots of hardware layers exist. The Yocto Project
+#. **Find a Layer:** Many hardware layers are available. The Yocto Project
    :yocto_git:`Source Repositories <>` has many hardware layers.
    This example adds the
    `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer.
@@ -318,8 +318,8 @@ Follow these steps to add a hardware layer:
       Resolving deltas: 100% (13385/13385), done.
       Checking connectivity... done.
 
-   The hardware layer now exists
-   with other layers inside the Poky reference repository on your build
+   The hardware layer is now available
+   next to other layers inside the Poky reference repository on your build
    host as ``meta-altera`` and contains all the metadata needed to
    support hardware from Altera, which is owned by Intel.
 
@@ -332,7 +332,7 @@ Follow these steps to add a hardware layer:
 #. **Change the Configuration to Build for a Specific Machine:** The
    :term:`MACHINE` variable in the
    ``local.conf`` file specifies the machine for the build. For this
-   example, set the ``MACHINE`` variable to ``cyclone5``. These
+   example, set the :term:`MACHINE` variable to ``cyclone5``. These
    configurations are used:
    https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf.
 
@@ -431,8 +431,8 @@ information including the website, wiki pages, and user manuals:
    information.
 
 -  **Yocto Project Mailing Lists:** Related mailing lists provide a forum
-   for discussion, patch submission and announcements. Several mailing
-   lists exist and are grouped according to areas of concern. See the
+   for discussion, patch submission and announcements. There are several
+   mailing lists grouped by topic. See the
    :ref:`ref-manual/resources:mailing lists`
    section in the Yocto Project Reference Manual for a complete list of
    Yocto Project mailing lists.

documentation/bsp-guide/bsp.rst

@@ -95,11 +95,11 @@ layer and from it build an image. Here is an example::
 
 .. note::
 
-   Ordering and :term:`BBFILE_PRIORITY` for the layers listed in ``BBLAYERS``
+   Ordering and :term:`BBFILE_PRIORITY` for the layers listed in :term:`BBLAYERS`
    matter. For example, if multiple layers define a machine configuration, the
    OpenEmbedded build system uses the last layer searched given similar layer
    priorities. The build system works from the top-down through the layers
-   listed in ``BBLAYERS``.
+   listed in :term:`BBLAYERS`.
 
 Some BSPs require or depend on additional layers beyond the BSP's root
 layer in order to be functional. In this case, you need to specify these
@@ -267,7 +267,7 @@ maintain the distinction that the BSP layer, a build system, and tools
 are separate components that could be combined in certain end products.
 
 Before looking at the recommended form for the directory structure
-inside a BSP layer, you should be aware that some requirements do exist
+inside a BSP layer, you should be aware that there are some requirements
 in order for a BSP layer to be considered compliant with the Yocto
 Project. For that list of requirements, see the
 ":ref:`bsp-guide/bsp:released bsp requirements`" section.
@@ -685,7 +685,7 @@ statements as follows::
 
 .. note::
 
-   When the preferred provider is assumed by default, the ``PREFERRED_PROVIDER``
+   When the preferred provider is assumed by default, the :term:`PREFERRED_PROVIDER`
    statement does not appear in the ``"bsp_root_name".conf`` file.
 
 You would use the ``linux-yocto_4.4.bbappend`` file to append specific
@@ -763,8 +763,8 @@ workflow.
 
    .. note::
 
-      -  Four hardware reference BSPs exist that are part of the Yocto
-         Project release and are located in the ``poky/meta-yocto-bsp``
+      -  There are four hardware reference BSPs in the Yocto
+         Project release, located in the ``poky/meta-yocto-bsp``
          BSP layer:
 
          -  Texas Instruments Beaglebone (``beaglebone-yocto``)
@@ -773,8 +773,8 @@ workflow.
 
          -  Two general IA platforms (``genericx86`` and ``genericx86-64``)
 
-      -  Three core Intel BSPs exist as part of the Yocto Project
-         release in the ``meta-intel`` layer:
+      -  There are three core Intel BSPs in the Yocto Project
+         release, in the ``meta-intel`` layer:
 
          -  ``intel-core2-32``, which is a BSP optimized for the Core2
             family of CPUs as well as all CPUs prior to the Silvermont
@@ -832,10 +832,8 @@ workflow.
 Requirements and Recommendations for Released BSPs
 ==================================================
 
-Certain requirements exist for a released BSP to be considered compliant
-with the Yocto Project. Additionally, recommendations also exist. This
-section describes the requirements and recommendations for released
-BSPs.
+This section describes requirements and recommendations for a released
+BSP to be considered compliant with the Yocto Project.
 
 Released BSP Requirements
 -------------------------
@@ -864,7 +862,7 @@ Before looking at BSP requirements, you should consider the following:
 
 -  It is not required that specific packages or package modifications
    exist in the BSP layer, beyond the requirements for general
-   compliance with the Yocto Project. For example, no requirement exists
+   compliance with the Yocto Project. For example, there is no requirement
    dictating that a specific kernel or kernel version be used in a given
    BSP.
 
@@ -900,7 +898,7 @@ Yocto Project:
 -  *License File:* You must include a license file in the
    ``meta-bsp_root_name`` directory. This license covers the BSP
    Metadata as a whole. You must specify which license to use since no
-   default license exists when one is not specified. See the
+   default license exists. See the
    :yocto_git:`COPYING.MIT </meta-raspberrypi/tree/COPYING.MIT>`
    file for the Raspberry Pi BSP in the ``meta-raspberrypi`` BSP layer
    as an example.
@@ -1107,7 +1105,7 @@ system requirements.
    unsuitable functionality or quality, you can use an encumbered
    version.
 
-A couple different methods exist within the OpenEmbedded build system to
+There are two different methods within the OpenEmbedded build system to
 satisfy the licensing requirements for an encumbered BSP. The following
 list describes them in order of preference:
 
@@ -1123,15 +1121,15 @@ list describes them in order of preference:
    how to use these variables.
 
    If you build as you normally would, without specifying any recipes in
-   the ``LICENSE_FLAGS_WHITELIST``, the build stops and provides you
+   the :term:`LICENSE_FLAGS_WHITELIST`, the build stops and provides you
    with the list of recipes that you have tried to include in the image
-   that need entries in the ``LICENSE_FLAGS_WHITELIST``. Once you enter
+   that need entries in the :term:`LICENSE_FLAGS_WHITELIST`. Once you enter
    the appropriate license flags into the whitelist, restart the build
    to continue where it left off. During the build, the prompt will not
    appear again since you have satisfied the requirement.
 
    Once the appropriate license flags are on the white list in the
-   ``LICENSE_FLAGS_WHITELIST`` variable, you can build the encumbered
+   :term:`LICENSE_FLAGS_WHITELIST` variable, you can build the encumbered
    image with no change at all to the normal build process.
 
 #. *Get a Pre-Built Version of the BSP:* You can get this type of BSP by
@@ -1144,7 +1142,7 @@ list describes them in order of preference:
    click-through license agreements presented by the website. If you
    want to build the image yourself using the recipes contained within
    the BSP tarball, you will still need to create an appropriate
-   ``LICENSE_FLAGS_WHITELIST`` to match the encumbered recipes in the
+   :term:`LICENSE_FLAGS_WHITELIST` to match the encumbered recipes in the
    BSP.
 
 .. note::
@@ -1186,11 +1184,11 @@ Use these steps to create a BSP layer:
 -  *Create a Machine Configuration File:* Create a
    ``conf/machine/bsp_root_name.conf`` file. See
    :yocto_git:`meta-yocto-bsp/conf/machine </poky/tree/meta-yocto-bsp/conf/machine>`
-   for sample ``bsp_root_name.conf`` files. Other samples such as
+   for sample ``bsp_root_name.conf`` files. There are other samples such as
    :yocto_git:`meta-ti </meta-ti/tree/conf/machine>`
    and
    :yocto_git:`meta-freescale </meta-freescale/tree/conf/machine>`
-   exist from other vendors that have more specific machine and tuning
+   from other vendors that have more specific machine and tuning
    examples.
 
 -  *Create a Kernel Recipe:* Create a kernel recipe in
@@ -1241,7 +1239,7 @@ As mentioned earlier in this section, the existence of a machine
 configuration file is what makes a layer a BSP layer as compared to a
 general or kernel layer.
 
-One or more machine configuration files exist in the
+There are one or more machine configuration files in the
 ``bsp_layer/conf/machine/`` directory of the layer::
 
    bsp_layer/conf/machine/machine1\.conf
@@ -1311,7 +1309,7 @@ Project Reference Manual.
 -  :term:`PREFERRED_PROVIDER_virtual/xserver <PREFERRED_PROVIDER>`:
    The recipe that provides "virtual/xserver" when more than one
    provider is found. In this case, the recipe that provides
-   "virtual/xserver" is "xserver-xorg", which exists in
+   "virtual/xserver" is "xserver-xorg", available in
    ``poky/meta/recipes-graphics/xorg-xserver``.
 
 -  :term:`XSERVER`: The packages that
@@ -1326,7 +1324,7 @@ Project Reference Manual.
 
    .. tip::
 
-      Many ``MACHINE*`` variables exist that help you configure a particular piece
+      There are many ``MACHINE*`` variables that help you configure a particular piece
       of hardware.
 
 -  :term:`EXTRA_IMAGEDEPENDS`:
@@ -1339,9 +1337,9 @@ Project Reference Manual.
 -  :term:`DEFAULTTUNE`: Machines
    use tunings to optimize machine, CPU, and application performance.
    These features, which are collectively known as "tuning features",
-   exist in the :term:`OpenEmbedded-Core (OE-Core)` layer (e.g.
+   are set in the :term:`OpenEmbedded-Core (OE-Core)` layer (e.g.
    ``poky/meta/conf/machine/include``). In this example, the default
-   tuning file is "cortexa8hf-neon".
+   tuning file is ``cortexa8hf-neon``.
 
    .. note::
 
@@ -1367,7 +1365,7 @@ Project Reference Manual.
 -  :term:`IMAGE_INSTALL`:
    Specifies packages to install into an image through the
    :ref:`image <ref-classes-image>` class. Recipes
-   use the ``IMAGE_INSTALL`` variable.
+   use the :term:`IMAGE_INSTALL` variable.
 
 -  ``do_image_wic[depends]``: A task that is constructed during the
    build. In this example, the task depends on specific tools in order
@@ -1407,7 +1405,7 @@ Project Reference Manual.
 
    The BeagleBone development board requires an SPL to boot and that SPL
    file type must be MLO. Consequently, the machine configuration needs
-   to define ``SPL_BINARY`` as ``MLO``.
+   to define :term:`SPL_BINARY` as ``MLO``.
 
    .. note::
 

documentation/conf.py

@@ -92,6 +92,9 @@ intersphinx_mapping = {
     'bitbake': ('https://docs.yoctoproject.org/bitbake/', None)
 }
 
+# Suppress "WARNING: unknown mimetype for ..."
+suppress_warnings = ['epub.unknown_project_files']
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

documentation/dev-manual/qemu.rst

@@ -275,7 +275,7 @@ present, the toolchain is also automatically used.
 
 .. note::
 
-   Several mechanisms exist that let you connect to the system running
+   There are several mechanisms to connect to the system running
    on the QEMU emulator:
 
    -  QEMU provides a framebuffer interface that makes standard consoles
@@ -286,7 +286,7 @@ present, the toolchain is also automatically used.
       that port to run a console. The connection uses standard IP
       networking.
 
-   -  SSH servers exist in some QEMU images. The ``core-image-sato``
+   -  SSH servers are available in some QEMU images. The ``core-image-sato``
       QEMU image has a Dropbear secure shell (SSH) server that runs with
       the root password disabled. The ``core-image-full-cmdline`` and
       ``core-image-lsb`` QEMU images have OpenSSH instead of Dropbear.

documentation/dev-manual/start.rst

@@ -36,7 +36,7 @@ particular working environment and set of practices.
     equipment together and set up your development environment's
     hardware topology.
 
-    The following roles exist:
+    Here are possible roles:
 
     -  *Application Developer:* This type of developer does application
        level work on top of an existing software stack.
@@ -99,8 +99,7 @@ particular working environment and set of practices.
     .. note::
 
        The setup of these services is beyond the scope of this manual.
-       However, sites such as the following exist that describe how to
-       perform setup:
+       However, here are sites describing how to perform setup:
 
        -  `Gitolite <https://gitolite.com>`__: Information for
           ``gitolite``.
@@ -190,7 +189,7 @@ particular working environment and set of practices.
     develop locally using their primary development system.
 
 9.  *Document Policies and Change Flow:* The Yocto Project uses a
-    hierarchical structure and a pull model. Scripts exist to create and
+    hierarchical structure and a pull model. There are scripts to create and
     send pull requests (i.e. ``create-pull-request`` and
     ``send-pull-request``). This model is in line with other open source
     projects where maintainers are responsible for specific areas of the
@@ -215,8 +214,8 @@ particular working environment and set of practices.
     someone else in the community needs them also.
 
 10. *Development Environment Summary:* Aside from the previous steps,
-    some best practices exist within the Yocto Project development
-    environment. Consider the following:
+    here are best practices within the Yocto Project development
+    environment:
 
     -  Use :ref:`overview-manual/development-environment:git` as the source control
        system.
@@ -607,8 +606,8 @@ of a given component.
 
    The recommended method for accessing Yocto Project components is to
    use Git to clone the upstream repository and work from within that
-   locally cloned repository. The procedure in this section exists
-   should you desire a tarball snapshot of any given component.
+   locally cloned repository. However, this section documents how to
+   use a tarball snapshot of any given component.
 
 Follow these steps to locate and download a particular tarball:
 
@@ -645,13 +644,6 @@ release. Rather than Git repositories, these files represent snapshot
 tarballs similar to the tarballs located in the Index of Releases
 described in the ":ref:`dev-manual/start:accessing index of releases`" section.
 
-.. note::
-
-   The recommended method for accessing Yocto Project components is to
-   use Git to clone a repository and work from within that local
-   repository. The procedure in this section exists should you desire a
-   tarball snapshot of any given component.
-
 1. *Go to the Yocto Project Website:* Open The
    :yocto_home:`Yocto Project Website <>` in your browser.
 
@@ -750,8 +742,8 @@ Follow these steps to create a local version of the upstream
    ":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::
+   directory and check its status. The ``master`` branch is checked out
+   by default::
 
       $ cd poky
       $ git status

documentation/index.rst

@@ -38,16 +38,15 @@ Welcome to the Yocto Project Documentation
 
 .. toctree::
    :maxdepth: 1
-   :caption: 'Mega' Manual
+   :caption: Releases manual
+   :hidden:
 
-   All-in-one 'Mega' Manual <https://docs.yoctoproject.org/singleindex.html>
+   Release Migration Guides <migration-guides/index>
+   releases
 
 .. toctree::
    :maxdepth: 1
-   :caption: Manuals/Variable Index
+   :caption: Documentation Index
+   :hidden:
 
    genindex
-   Current/Previous Version Specific Manuals <releases>
-
-
-

documentation/kernel-dev/advanced.rst

@@ -21,7 +21,7 @@ is the ``yocto-kernel-cache`` Git repository. You can find this repository
 grouped under the "Yocto Linux Kernel" heading in the
 :yocto_git:`Yocto Project Source Repositories <>`.
 
-Kernel development tools ("kern-tools") exist also in the Yocto Project
+Kernel development tools ("kern-tools") are also available in the Yocto Project
 Source Repositories under the "Yocto Linux Kernel" heading in the
 ``yocto-kernel-tools`` Git repository. The recipe that builds these
 tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in
@@ -46,15 +46,15 @@ linux-yocto recipe.
 
 Every linux-yocto style recipe must define the
 :term:`KMACHINE` variable. This
-variable is typically set to the same value as the ``MACHINE`` variable,
+variable is typically set to the same value as the :term:`MACHINE` variable,
 which is used by :term:`BitBake`.
 However, in some cases, the variable might instead refer to the
-underlying platform of the ``MACHINE``.
+underlying platform of the :term:`MACHINE`.
 
-Multiple BSPs can reuse the same ``KMACHINE`` name if they are built
+Multiple BSPs can reuse the same :term:`KMACHINE` name if they are built
 using the same BSP description. Multiple Corei7-based BSPs could share
-the same "intel-corei7-64" value for ``KMACHINE``. It is important to
-realize that ``KMACHINE`` is just for kernel mapping, while ``MACHINE``
+the same "intel-corei7-64" value for :term:`KMACHINE`. It is important to
+realize that :term:`KMACHINE` is just for kernel mapping, while :term:`MACHINE`
 is the machine type within a BSP Layer. Even with this distinction,
 however, these two variables can hold the same value. See the
 ":ref:`kernel-dev/advanced:bsp descriptions`" section for more information.
@@ -66,7 +66,7 @@ to indicate the branch.
 
 .. note::
 
-   You can use the ``KBRANCH`` value to define an alternate branch typically
+   You can use the :term:`KBRANCH` value to define an alternate branch typically
    with a machine override as shown here from the ``meta-yocto-bsp`` layer::
 
            KBRANCH_edgerouter = "standard/edgerouter"
@@ -81,8 +81,8 @@ variables:
 
 :term:`LINUX_KERNEL_TYPE`
 defines the kernel type to be used in assembling the configuration. If
-you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard".
-Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search
+you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to "standard".
+Together with :term:`KMACHINE`, :term:`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
@@ -90,21 +90,21 @@ configuration. The linux-yocto recipes define "standard", "tiny", and
 section for more information on kernel types.
 
 During the build, the kern-tools search for the BSP description file
-that most closely matches the ``KMACHINE`` and ``LINUX_KERNEL_TYPE``
+that most closely matches the :term:`KMACHINE` and :term:`LINUX_KERNEL_TYPE`
 variables passed in from the recipe. The tools use the first BSP
 description they find that matches both variables. If the tools cannot find
 a match, they issue a warning.
 
-The tools first search for the ``KMACHINE`` and then for the
-``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they
-will use the sources from the ``KBRANCH`` and any configuration
+The tools first search for the :term:`KMACHINE` and then for the
+:term:`LINUX_KERNEL_TYPE`. If the tools cannot find a partial match, they
+will use the sources from the :term:`KBRANCH` and any configuration
 specified in the :term:`SRC_URI`.
 
 You can use the
 :term:`KERNEL_FEATURES`
 variable to include features (configuration fragments, patches, or both)
-that are not already included by the ``KMACHINE`` and
-``LINUX_KERNEL_TYPE`` variable combination. For example, to include a
+that are not already included by the :term:`KMACHINE` and
+:term:`LINUX_KERNEL_TYPE` variable combination. For example, to include a
 feature specified as "features/netfilter/netfilter.scc", specify::
 
    KERNEL_FEATURES += "features/netfilter/netfilter.scc"
@@ -116,7 +116,7 @@ specify::
    KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc"
 
 The value of
-the entries in ``KERNEL_FEATURES`` are dependent on their location
+the entries in :term:`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
@@ -313,7 +313,7 @@ The following listings show the ``build.scc`` file and part of the
 
 The description file can
 include multiple patch statements where each statement handles a single
-patch. In the example ``build.scc`` file, five patch statements exist
+patch. In the example ``build.scc`` file, there are five patch statements
 for the five patches in the directory.
 
 You can create a typical ``.patch`` file using ``diff -Nurp`` or
@@ -344,7 +344,7 @@ 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
+of things you want to specify in the :term:`KERNEL_FEATURES` variable of the
 Linux kernel recipe. See the
 ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier
 in the manual.
@@ -509,12 +509,12 @@ description as meeting the criteria set by the recipe being built. This
 example supports the "beaglebone" machine for the "standard" kernel and
 the "arm" architecture.
 
-Be aware that a hard link between the ``KTYPE`` variable and a kernel
-type description file does not exist. Thus, if you do not have the
+Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel
+type description file. Thus, if you do not have the
 kernel type defined in your kernel Metadata as it is here, you only need
 to ensure that the
 :term:`LINUX_KERNEL_TYPE`
-variable in the kernel recipe and the ``KTYPE`` variable in the BSP
+variable in the kernel recipe and the :term:`KTYPE` variable in the BSP
 description file match.
 
 To separate your kernel policy from your hardware configuration, you
@@ -657,7 +657,7 @@ Notice again the three critical variables:
 :term:`KMACHINE`,
 :term:`KTYPE`, and
 :term:`KARCH`. Of these variables, only
-``KTYPE`` has changed to specify the "tiny" kernel type.
+:term:`KTYPE` has changed to specify the "tiny" kernel type.
 
 Kernel Metadata Location
 ========================
@@ -693,7 +693,7 @@ directory hierarchy below
 a linux-yocto recipe or for a Linux kernel recipe derived by copying and
 modifying
 ``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to
-a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to
+a recipe in your layer, :term:`FILESEXTRAPATHS` is typically set to
 ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``.
 See the ":ref:`kernel-dev/common:modifying an existing recipe`"
 section for more information.
@@ -718,10 +718,10 @@ and fetches any files referenced in the ``.scc`` files by the
 ``include``, ``patch``, or ``kconf`` commands. Because of this, it is
 necessary to bump the recipe :term:`PR`
 value when changing the content of files not explicitly listed in the
-``SRC_URI``.
+:term:`SRC_URI`.
 
 If the BSP description is in recipe space, you cannot simply list the
-``*.scc`` in the ``SRC_URI`` statement. You need to use the following
+``*.scc`` in the :term:`SRC_URI` statement. You need to use the following
 form from your kernel append file::
 
    SRC_URI_append_myplatform = " \
@@ -735,7 +735,7 @@ When stored outside of the recipe-space, the kernel Metadata files
 reside in a separate repository. The OpenEmbedded build system adds the
 Metadata to the build as a "type=kmeta" repository through the
 :term:`SRC_URI` variable. As an
-example, consider the following ``SRC_URI`` statement from the
+example, consider the following :term:`SRC_URI` statement from the
 ``linux-yocto_4.12.bb`` kernel recipe::
 
    SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \
@@ -744,20 +744,20 @@ example, consider the following ``SRC_URI`` statement from the
 
 ``${KMETA}``, in this context, is simply used to name the directory into
 which the Git fetcher places the Metadata. This behavior is no different
-than any multi-repository ``SRC_URI`` statement used in a recipe (e.g.
+than any multi-repository :term:`SRC_URI` statement used in a recipe (e.g.
 see the previous section).
 
 You can keep kernel Metadata in a "kernel-cache", which is a directory
 containing configuration fragments. As with any Metadata kept outside
-the recipe-space, you simply need to use the ``SRC_URI`` statement with
+the recipe-space, you simply need to use the :term:`SRC_URI` statement with
 the "type=kmeta" attribute. Doing so makes the kernel Metadata available
 during the configuration phase.
 
-If you modify the Metadata, you must not forget to update the ``SRCREV``
+If you modify the Metadata, you must not forget to update the :term:`SRCREV`
 statements in the kernel's recipe. In particular, you need to update the
 ``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you
 wish to use. Changing the data in these branches and not updating the
-``SRCREV`` statements to match will cause the build to fetch an older
+:term:`SRCREV` statements to match will cause the build to fetch an older
 commit.
 
 Organizing Your Source
@@ -776,8 +776,8 @@ patches in every kernel you build (i.e. have the patches as part of the
 lone "master" branch). It is situations like these that give rise to
 multiple branches used within a Linux kernel sources Git repository.
 
-Repository organization strategies exist that maximize source reuse,
-remove redundancy, and logically order your changes. This section
+Here are repository organization strategies maximizing source reuse,
+removing redundancy, and logically ordering your changes. This section
 presents strategies for the following cases:
 
 -  Encapsulating patches in a feature description and only including the
@@ -820,7 +820,7 @@ 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 :term:`KBRANCH` to use for the board as follows::
 
    KBRANCH = "mynewbranch"
 

documentation/kernel-dev/common.rst

@@ -70,7 +70,7 @@ section:
    :term:`MACHINE` variable is set to
    "qemux86-64", which is fine if you are building for the QEMU emulator
    in 64-bit mode. However, if you are not, you need to set the
-   ``MACHINE`` variable appropriately in your ``conf/local.conf`` file
+   :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file
    found in the
    :term:`Build Directory` (i.e.
    ``poky/build`` in this example).
@@ -81,7 +81,7 @@ section:
    variable to include kernel modules.
 
    In this example we wish to build for qemux86 so we must set the
-   ``MACHINE`` variable to "qemux86" and also add the "kernel-modules".
+   :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
    As described we do this by appending to ``conf/local.conf``::
 
       MACHINE = "qemux86"
@@ -248,7 +248,7 @@ section:
    :term:`MACHINE` variable is set to
    "qemux86-64", which is fine if you are building for the QEMU emulator
    in 64-bit mode. However, if you are not, you need to set the
-   ``MACHINE`` variable appropriately in your ``conf/local.conf`` file
+   :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file
    found in the
    :term:`Build Directory` (i.e.
    ``poky/build`` in this example).
@@ -259,7 +259,7 @@ section:
    variable to include kernel modules.
 
    In this example we wish to build for qemux86 so we must set the
-   ``MACHINE`` variable to "qemux86" and also add the "kernel-modules".
+   :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
    As described we do this by appending to ``conf/local.conf``::
 
       MACHINE = "qemux86"
@@ -474,7 +474,7 @@ variable as follows::
 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
+extended :term:`FILESPATH` as described above, you must place the files in
 your layer in the following area::
 
    your-layer/recipes-kernel/linux/linux-yocto/
@@ -553,7 +553,7 @@ the append file.
 
 For example, suppose you had some configuration options in a file called
 ``network_configs.cfg``. You can place that file inside a directory
-named ``linux-yocto`` and then add a ``SRC_URI`` statement such as the
+named ``linux-yocto`` and then add a :term:`SRC_URI` statement such as the
 following to the append file. When the OpenEmbedded build system builds
 the kernel, the configuration options are picked up and applied.
 ::
@@ -563,7 +563,7 @@ the kernel, the configuration options are picked up and applied.
 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
+files and adds the configurations by using a :term:`SRC_URI` statement like
 the following in your append file::
 
    SRC_URI += "file://myconfig.cfg \
@@ -578,7 +578,7 @@ recipe is processed.
 
 .. note::
 
-   Other methods exist to accomplish grouping and defining configuration
+   There are other ways of grouping and defining configuration
    options. For example, if you are working with a local clone of the
    kernel repository, you could checkout the kernel's ``meta`` branch,
    make your changes, and then push the changes to the local bare clone
@@ -588,7 +588,7 @@ recipe is processed.
    added to the Yocto Project.
 
    In general, however, the Yocto Project maintainers take care of
-   moving the ``SRC_URI``-specified configuration options to the
+   moving the :term:`SRC_URI`-specified configuration options to the
    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'
@@ -643,7 +643,7 @@ following lines to the linux-yocto ``.bbappend`` file in your layer::
    FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
    SRC_URI += "file://defconfig"
 
-The ``SRC_URI`` tells the build system how to search
+The :term:`SRC_URI` tells the build system how to search
 for the file, while the
 :term:`FILESEXTRAPATHS`
 extends the :term:`FILESPATH`
@@ -684,7 +684,7 @@ with the following content (without indentation)::
    CONFIG_SERIAL_CORE_CONSOLE=y
 
 Next, include this
-configuration fragment and extend the ``FILESPATH`` variable in your
+configuration fragment and extend the :term:`FILESPATH` variable in your
 ``.bbappend`` file::
 
    FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
@@ -722,7 +722,7 @@ form::
    KBUILD_DEFCONFIG_KMACHINE ?= "defconfig_file"
 
 Here is an example
-that assigns the ``KBUILD_DEFCONFIG`` variable based on "raspberrypi2"
+that assigns the :term:`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::
 
@@ -730,11 +730,11 @@ a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset::
 
 Aside from modifying your kernel recipe and providing your own
 ``defconfig`` file, you need to be sure no files or statements set
-``SRC_URI`` to use a ``defconfig`` other than your "in-tree" file (e.g.
+:term:`SRC_URI` to use a ``defconfig`` other than your "in-tree" file (e.g.
 a kernel's ``linux-``\ `machine`\ ``.inc`` file). In other words, if the
 build system detects a statement that identifies an "out-of-tree"
 ``defconfig`` file, that statement will override your
-``KBUILD_DEFCONFIG`` variable.
+:term:`KBUILD_DEFCONFIG` variable.
 
 See the
 :term:`KBUILD_DEFCONFIG`
@@ -781,8 +781,8 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
 
    .. note::
 
-      During the checkout operation, a bug exists that could cause
-      errors such as the following to appear:
+      During the checkout operation, there is a bug that could cause
+      errors such as the following:
 
       .. code-block:: none
 
@@ -1306,7 +1306,7 @@ steps:
       $ bitbake linux-yocto -c kernel_configme -f
 
    This step ensures that you create a
-   ``.config`` file from a known state. Because situations exist where
+   ``.config`` file from a known state. Because there are situations where
    your build state might become unknown, it is best to run this task
    prior to starting ``menuconfig``.
 
@@ -1349,10 +1349,10 @@ be picked up and applied when the kernel is built::
    SRC_URI += "file://myconfig.cfg"
 
 As mentioned earlier, you can group related configurations into multiple
-files and name them all in the ``SRC_URI`` statement as well. For
+files and name them all in the :term:`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::
+:term:`SRC_URI` statement like the following in your append file::
 
    SRC_URI += "file://myconfig.cfg \
                file://eth.cfg \
@@ -1536,7 +1536,7 @@ Working with a "Dirty" Kernel Version String
 ============================================
 
 If you build a kernel image and the version string has a "+" or a
-"-dirty" at the end, uncommitted modifications exist in the kernel's
+"-dirty" at the end, it means there are uncommitted modifications in the kernel's
 source directory. Follow these steps to clean up the version string:
 
 1. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned
@@ -1615,7 +1615,7 @@ Here are some basic steps you can use to work with your own sources:
 
    Running the ``make defconfig`` command results in the default
    configuration for your architecture as defined by your kernel.
-   However, no guarantee exists that this configuration is valid for
+   However, there is no guarantee that this configuration is valid for
    your use case, or that your board will even boot. This is
    particularly true for non-x86 architectures.
 
@@ -1628,11 +1628,11 @@ Here are some basic steps you can use to work with your own sources:
    appropriate for your project:
 
    -  :term:`SRC_URI`: The
-      ``SRC_URI`` should specify a Git repository that uses one of the
+      :term:`SRC_URI` should specify a Git repository that uses one of the
       supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``,
-      and so forth). The ``SRC_URI`` variable should also specify either
+      and so forth). The :term:`SRC_URI` variable should also specify either
       a ``defconfig`` file or some configuration fragment files. The
-      skeleton recipe provides an example ``SRC_URI`` as a syntax
+      skeleton recipe provides an example :term:`SRC_URI` as a syntax
       reference.
 
    -  :term:`LINUX_VERSION`:
@@ -1650,16 +1650,16 @@ Here are some basic steps you can use to work with your own sources:
       indicate to the OpenEmbedded build system that the recipe has
       changed.
 
-   -  :term:`PV`: The default ``PV``
+   -  :term:`PV`: The default :term:`PV`
       assignment is typically adequate. It combines the
-      ``LINUX_VERSION`` with the Source Control Manager (SCM) revision
+      :term:`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::
 
          3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
 
-      While lengthy, the extra verbosity in ``PV`` helps ensure you are
+      While lengthy, the extra verbosity in :term:`PV` helps ensure you are
       using the exact sources from which you intend to build.
 
    -  :term:`COMPATIBLE_MACHINE`:
@@ -1773,7 +1773,7 @@ information to build modules. If your module ``Makefile`` uses a
 different variable, you might want to override the
 :ref:`ref-tasks-compile` step, or
 create a patch to the ``Makefile`` to work with the more typical
-``KERNEL_SRC`` or ``KERNEL_PATH`` variables.
+:term:`KERNEL_SRC` or :term:`KERNEL_PATH` variables.
 
 After you have prepared your recipe, you will likely want to include the
 module in your images. To do this, see the documentation for the
@@ -1886,23 +1886,23 @@ build stops. Kernel features are the last elements processed for
 configuring and patching the kernel. Therefore, adding features in this
 manner is a way to enforce specific features are present and enabled
 without needing to do a full audit of any other layer's additions to the
-``SRC_URI`` statement.
+:term:`SRC_URI` statement.
 
 You add a kernel feature by providing the feature as part of the
-``KERNEL_FEATURES`` variable and by providing the path to the feature's
+:term:`KERNEL_FEATURES` variable and by providing the path to the feature's
 ``.scc`` file, which is relative to the root of the kernel Metadata. The
 OpenEmbedded build system searches all forms of kernel Metadata on the
-``SRC_URI`` statement regardless of whether the Metadata is in the
+:term:`SRC_URI` statement regardless of whether the Metadata is in the
 "kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e.
 part of the kernel recipe). See the
 ":ref:`kernel-dev/advanced:kernel metadata location`" section for
 additional information.
 
-When you specify the feature's ``.scc`` file on the ``SRC_URI``
+When you specify the feature's ``.scc`` file on the :term:`SRC_URI`
 statement, the OpenEmbedded build system adds the directory of that
 ``.scc`` file along with all its subdirectories to the kernel feature
 search path. Because subdirectories are searched, you can reference a
-single ``.scc`` file in the ``SRC_URI`` statement to reference multiple
+single ``.scc`` file in the :term:`SRC_URI` statement to reference multiple
 kernel features.
 
 Consider the following example that adds the "test.scc" feature to the
@@ -1910,7 +1910,7 @@ build.
 
 1. *Create the Feature File:* Create a ``.scc`` file and locate it just
    as you would any other patch file, ``.cfg`` file, or fetcher item you
-   specify in the ``SRC_URI`` statement.
+   specify in the :term:`SRC_URI` statement.
 
    .. note::
 
@@ -1937,7 +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 :term:`SRC_URI` statement::
 
       SRC_URI_append = " file://test.scc"
 
@@ -1945,7 +1945,7 @@ build.
    appended to the existing path.
 
 3. *Specify the Feature as a Kernel Feature:* Use the
-   ``KERNEL_FEATURES`` statement to specify the feature as a kernel
+   :term:`KERNEL_FEATURES` statement to specify the feature as a kernel
    feature::
 
       KERNEL_FEATURES_append = " test.scc"

documentation/kernel-dev/concepts-appx.rst

@@ -213,7 +213,7 @@ BSP-specific commits. In other words, the divisions of the kernel are
 transparent and are not relevant to the developer on a day-to-day basis.
 From the developer's perspective, this path is the "master" branch in
 Git terms. The developer does not need to be aware of the existence of
-any other branches at all. Of course, value exists in the having these
+any other branches at all. Of course, it can make sense to have these
 branches in the tree, should a person decide to explore them. For
 example, a comparison between two BSPs at either the commit level or at
 the line-by-line code ``diff`` level is now a trivial operation.

documentation/kernel-dev/faq.rst

@@ -68,7 +68,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.
+typically specified in the machine config using the :term:`APPEND` variable.
 For example, you can add some helpful debug information doing the
 following::
 

documentation/kernel-dev/intro.rst

@@ -66,9 +66,9 @@ from the continual kernel integration and testing performed during
 development of the Yocto Project.
 
 If, instead, you have a very specific Linux kernel source tree and are
-unable to align with one of the official Yocto Linux kernel recipes, an
-alternative exists by which you can use the Yocto Project Linux kernel
-tools with your own kernel sources.
+unable to align with one of the official Yocto Linux kernel recipes,
+you have a way to use the Yocto Project Linux kernel tools with your
+own kernel sources.
 
 The remainder of this manual provides instructions for completing
 specific Linux kernel development tasks. These instructions assume you

documentation/kernel-dev/maint-appx.rst

@@ -104,7 +104,7 @@ patch, or BSP:
       repository organized under the "Yocto Linux Kernel" heading in the
       :yocto_git:`Yocto Project Source Repositories <>`.
 
-   -  Areas pointed to by ``SRC_URI`` statements found in kernel recipes.
+   -  Areas pointed to by :term:`SRC_URI` statements found in kernel recipes.
 
    For a typical build, the target of the search is a feature
    description in an ``.scc`` file whose name follows this format (e.g.
@@ -175,7 +175,7 @@ Build Strategy
 Once you have cloned a Yocto Linux kernel repository and the cache
 repository (``yocto-kernel-cache``) onto your development system, you
 can consider the compilation phase of kernel development, which is
-building a kernel image. Some prerequisites exist that are validated by
+building a kernel image. Some prerequisites are validated by
 the build process before compilation starts:
 
 -  The :term:`SRC_URI` points to the
@@ -194,7 +194,7 @@ the build process before compilation starts:
       In the previous example, the "yocto-4.12" branch is checked out in
       the ``yocto-kernel-cache`` repository.
 
-The OpenEmbedded build system makes sure these conditions exist before
+The OpenEmbedded build system makes sure these conditions are satisfied before
 attempting compilation. Other means, however, do exist, such as
 bootstrapping a BSP.
 

documentation/migration-guides/index.rst

@@ -1,32 +1,34 @@
 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
 
-******************************************
-Migrating to a Newer Yocto Project Release
-******************************************
+==========================
+ Release Migration Guides
+==========================
 
-This chapter provides information you can use to migrate work to a newer
-Yocto Project release. You can find the same information in the release
-notes for a given release.
+|
+
+Each document in this chapter provides information about how
+to move to one release of the Yocto Project from the previous one.
 
 .. toctree::
 
    migration-general
-   migration-1.3
-   migration-1.4
-   migration-1.5
-   migration-1.6
-   migration-1.7
-   migration-1.8
-   migration-2.0
-   migration-2.1
-   migration-2.2
-   migration-2.3
-   migration-2.4
-   migration-2.5
-   migration-2.6
-   migration-2.7
-   migration-3.0
-   migration-3.1
-   migration-3.2
    migration-3.3
+   migration-3.2
+   migration-3.1
+   migration-3.0
+   migration-2.7
+   migration-2.6
+   migration-2.5
+   migration-2.4
+   migration-2.3
+   migration-2.2
+   migration-2.1
+   migration-2.0
+   migration-1.8
+   migration-1.7
+   migration-1.6
+   migration-1.5
+   migration-1.4
+   migration-1.3
 
+.. include:: /boilerplate.rst

documentation/migration-guides/migration-1.3.rst

@@ -1,7 +1,7 @@
 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
 
-Moving to the Yocto Project 1.3 Release (danny)
-===============================================
+Release 1.3 (danny)
+===================
 
 This section provides migration information for moving to the Yocto
 Project 1.3 Release (codename "danny") from the prior release.
@@ -125,7 +125,7 @@ Image recipes that previously included ``apps-console-core`` in
 :term:`IMAGE_FEATURES` should now include ``splash``
 instead to enable the boot-up splash screen. Retaining
 ``apps-console-core`` will still include the splash screen but generates a
-warning. The ``apps-x11-core`` and ``apps-x11-games`` ``IMAGE_FEATURES``
+warning. The ``apps-x11-core`` and ``apps-x11-games`` :term:`IMAGE_FEATURES`
 features have been removed.
 
 .. _migration-1.3-removed-recipes:
@@ -185,7 +185,7 @@ 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
+Because the :term:`PE` variable is not set by default, these binary files
 could result with names that include two dash characters. Here is an
 example::
 

documentation/migration-guides/migration-1.4.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 1.4 Release (dylan)
-===============================================
+Release 1.4 (dylan)
+===================
 
 This section provides migration information for moving to the Yocto
 Project 1.4 Release (codename "dylan") from the prior release.
@@ -28,7 +28,7 @@ Differences include the following:
    and uninstall script functions ``pkg_preinst``, ``pkg_postinst``,
    ``pkg_prerm``, and ``pkg_postrm`` should always have a package name
    override. For example, use ``RDEPENDS_${PN}`` for the main package
-   instead of ``RDEPENDS``. BitBake uses more strict checks when it
+   instead of :term:`RDEPENDS`. BitBake uses more strict checks when it
    parses recipes.
 
 .. _migration-1.4-build-behavior:
@@ -53,14 +53,14 @@ Differences include the following:
    :term:`SRC_URI`, the build system now uses
    :term:`FILESOVERRIDES` instead of
    :term:`OVERRIDES` for the directory names. In
-   general, the values previously in ``OVERRIDES`` are now in
-   ``FILESOVERRIDES`` as well. However, if you relied upon an additional
-   value you previously added to ``OVERRIDES``, you might now need to
-   add it to ``FILESOVERRIDES`` unless you are already adding it through
+   general, the values previously in :term:`OVERRIDES` are now in
+   :term:`FILESOVERRIDES` as well. However, if you relied upon an additional
+   value you previously added to :term:`OVERRIDES`, you might now need to
+   add it to :term:`FILESOVERRIDES` unless you are already adding it through
    the :term:`MACHINEOVERRIDES` or
    :term:`DISTROOVERRIDES` variables, as
    appropriate. For more related changes, see the
-   ":ref:`ref-manual/migration-1.4:variables`" section.
+   ":ref:`migration-guides/migration-1.4:variables`" section.
 
 .. _migration-1.4-proxies-and-fetching-source:
 
@@ -105,7 +105,7 @@ Variables
 
 The following variables have changed:
 
--  ``SANITY_TESTED_DISTROS``: This variable now uses a distribution
+-  :term:`SANITY_TESTED_DISTROS`: This variable now uses a distribution
    ID, which is composed of the host distributor ID followed by the
    release. Previously,
    :term:`SANITY_TESTED_DISTROS` was
@@ -114,7 +114,7 @@ The following variables have changed:
    you are not specifically setting this variable, or if you are
    specifically setting it to "".
 
--  ``SRC_URI``: The ``${``\ :term:`PN`\ ``}``,
+-  :term:`SRC_URI`: The ``${``\ :term:`PN`\ ``}``,
    ``${``\ :term:`PF`\ ``}``,
    ``${``\ :term:`P`\ ``}``, and ``FILE_DIRNAME`` directories
    have been dropped from the default value of the

documentation/migration-guides/migration-1.5.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 1.5 Release (dora)
-==============================================
+Release 1.5 (dora)
+==================
 
 This section provides migration information for moving to the Yocto
 Project 1.5 Release (codename "dora") from the prior release.
@@ -68,7 +68,7 @@ The following changes have been made that relate to BitBake:
 -  ``${``\ :term:`P`\ ``}`` and
    ``${``\ :term:`PF`\ ``}`` are no longer added to
    :term:`PROVIDES` by default in ``bitbake.conf``.
-   These version-specific ``PROVIDES`` items were seldom used.
+   These version-specific :term:`PROVIDES` items were seldom used.
    Attempting to use them could result in two versions being built
    simultaneously rather than just one version due to the way BitBake
    resolves dependencies.
@@ -84,9 +84,9 @@ The following changes have been made to the package QA checks:
    :term:`WARN_QA` values in your configuration, check
    that they contain all of the issues that you wish to be reported.
    Previous Yocto Project versions contained a bug that meant that any
-   item not mentioned in ``ERROR_QA`` or ``WARN_QA`` would be treated as
+   item not mentioned in :term:`ERROR_QA` or :term:`WARN_QA` would be treated as
    a warning. Consequently, several important items were not already in
-   the default value of ``WARN_QA``. All of the possible QA checks are
+   the default value of :term:`WARN_QA`. All of the possible QA checks are
    now documented in the ":ref:`insane.bbclass <ref-classes-insane>`"
    section.
 
@@ -97,7 +97,7 @@ The following changes have been made to the package QA checks:
 
 -  If you are using the ``buildhistory`` class, the check for the package
    version going backwards is now controlled using a standard QA check.
-   Thus, if you have customized your ``ERROR_QA`` or ``WARN_QA`` values
+   Thus, if you have customized your :term:`ERROR_QA` or :term:`WARN_QA` values
    and still wish to have this check performed, you should add
    "version-going-backwards" to your value for one or the other
    variables depending on how you wish it to be handled. See the
@@ -124,12 +124,12 @@ The following directory changes exist:
    need to refer to this directory. The ``runqemu`` script now uses this
    variable to find images and kernel binaries and will use BitBake to
    determine the directory. Alternatively, you can set the
-   ``DEPLOY_DIR_IMAGE`` variable in the external environment.
+   :term:`DEPLOY_DIR_IMAGE` variable in the external environment.
 
 -  When buildhistory is enabled, its output is now written under the
    :term:`Build Directory` rather than
    :term:`TMPDIR`. Doing so makes it easier to delete
-   ``TMPDIR`` and preserve the build history. Additionally, data for
+   :term:`TMPDIR` and preserve the build history. Additionally, data for
    produced SDKs is now split by :term:`IMAGE_NAME`.
 
 -  The ``pkgdata`` directory produced as part of the packaging process
@@ -157,20 +157,20 @@ major issue in the way the values are used.
 The following changes have been made that relate to
 :term:`IMAGE_FEATURES`:
 
--  The value of ``IMAGE_FEATURES`` is now validated to ensure invalid
+-  The value of :term:`IMAGE_FEATURES` is now validated to ensure invalid
    feature items are not added. Some users mistakenly add package names
    to this variable instead of using
    :term:`IMAGE_INSTALL` in order to have the
    package added to the image, which does not work. This change is
-   intended to catch those kinds of situations. Valid ``IMAGE_FEATURES``
+   intended to catch those kinds of situations. Valid :term:`IMAGE_FEATURES`
    are drawn from ``PACKAGE_GROUP`` definitions,
    :term:`COMPLEMENTARY_GLOB` and a new
-   "validitems" varflag on ``IMAGE_FEATURES``. The "validitems" varflag
+   "validitems" varflag on :term:`IMAGE_FEATURES`. The "validitems" varflag
    change allows additional features to be added if they are not
    provided using the previous two mechanisms.
 
--  The previously deprecated "apps-console-core" ``IMAGE_FEATURES`` item
-   is no longer supported. Add "splash" to ``IMAGE_FEATURES`` if you
+-  The previously deprecated "apps-console-core" :term:`IMAGE_FEATURES` item
+   is no longer supported. Add "splash" to :term:`IMAGE_FEATURES` if you
    wish to have the splash screen enabled, since this is all that
    apps-console-core was doing.
 
@@ -285,7 +285,7 @@ Following are changes to ``udev``:
    ``udev-extraconf`` to your image.
 
 -  ``udev`` no longer brings in ``pciutils-ids`` or ``usbutils-ids``
-   through ``RRECOMMENDS``. These are not needed by ``udev`` itself and
+   through :term:`RRECOMMENDS`. These are not needed by ``udev`` itself and
    removing them saves around 350KB.
 
 .. _migration-1.5-removed-renamed-recipes:
@@ -333,7 +333,7 @@ Following is a list of short entries describing other changes:
    :term:`BAD_RECOMMENDATIONS` supports
    pre-renamed package names.
 
--  ``classes/rootfs_rpm``: Implement ``BAD_RECOMMENDATIONS`` for RPM.
+-  ``classes/rootfs_rpm``: Implement :term:`BAD_RECOMMENDATIONS` for RPM.
 
 -  ``systemd``: Remove ``systemd_unitdir`` if ``systemd`` is not in
    :term:`DISTRO_FEATURES`.

documentation/migration-guides/migration-1.6.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 1.6 Release (daisy)
-===============================================
+Release 1.6 (daisy)
+===================
 
 This section provides migration information for moving to the Yocto
 Project 1.6 Release (codename "daisy") from the prior release.
@@ -61,7 +61,7 @@ If you do not specify a branch, BitBake looks in the default "master" branch.
 
 Alternatively, if you need to bypass this check (e.g. if you are
 fetching a revision corresponding to a tag that is not on any branch),
-you can add ";nobranch=1" to the end of the URL within ``SRC_URI``.
+you can add ";nobranch=1" to the end of the URL within :term:`SRC_URI`.
 
 .. _migration-1.6-bitbake-deps:
 
@@ -134,9 +134,9 @@ OpenEmbedded build system variables, see the ":doc:`/ref-manual/variables`" Chap
 
 :term:`TMPDIR` can no longer be on an NFS mount. NFS does
 not offer full POSIX locking and inode consistency and can cause
-unexpected issues if used to store ``TMPDIR``.
+unexpected issues if used to store :term:`TMPDIR`.
 
-The check for this occurs on startup. If ``TMPDIR`` is detected on an
+The check for this occurs on startup. If :term:`TMPDIR` is detected on an
 NFS mount, an error occurs.
 
 .. _migration-1.6-variable-changes-PRINC:
@@ -274,7 +274,7 @@ In addition to ``core-image-basic`` being renamed,
 Licensing
 ---------
 
-The top-level ``LICENSE`` file has been changed to better describe the
+The top-level :term:`LICENSE` file has been changed to better describe the
 license of the various components of :term:`OpenEmbedded-Core (OE-Core)`. However,
 the licensing itself remains unchanged.
 
@@ -284,7 +284,7 @@ recipes point to this file within
 ``${COREBASE}/LICENSE``) and thus the accompanying checksum must be
 changed from 3f40d7994397109285ec7b81fdeb3b58 to
 4d92cd373abda3937c2bc47fbc49d690. A better alternative is to have
-``LIC_FILES_CHKSUM`` point to a file describing the license that is
+:term:`LIC_FILES_CHKSUM` point to a file describing the license that is
 distributed with the source that the recipe is building, if possible,
 rather than pointing to ``${COREBASE}/LICENSE``.
 
@@ -297,7 +297,7 @@ The "-fpermissive" option has been removed from the default
 :term:`CFLAGS` value. You need to take action on
 individual recipes that fail when building with this option. You need to
 either patch the recipes to fix the issues reported by the compiler, or
-you need to add "-fpermissive" to ``CFLAGS`` in the recipes.
+you need to add "-fpermissive" to :term:`CFLAGS` in the recipes.
 
 .. _migration-1.6-custom-images:
 

documentation/migration-guides/migration-1.7.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 1.7 Release (dizzy)
-===============================================
+Release 1.7 (dizzy)
+===================
 
 This section provides migration information for moving to the Yocto
 Project 1.7 Release (codename "dizzy") from the prior release.
@@ -13,7 +13,7 @@ The QEMU recipe now uses a number of
 :term:`PACKAGECONFIG` options to enable various
 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``
+append to :term:`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``::
 
@@ -140,9 +140,9 @@ part of the variable name. This change not only simplifies usage but
 also allows the values of these variables to be appropriately
 incorporated into task signatures and thus trigger the appropriate tasks
 to re-execute when changed. You should replace any references to
-``module_autoload_*`` with ``KERNEL_MODULE_AUTOLOAD``, and add any
+``module_autoload_*`` with :term:`KERNEL_MODULE_AUTOLOAD`, and add any
 modules for which ``module_conf_*`` is specified to
-``KERNEL_MODULE_PROBECONF``.
+:term:`KERNEL_MODULE_PROBECONF`.
 
 .. _migration-1.7-qa-check-changes:
 

documentation/migration-guides/migration-1.8.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 1.8 Release (fido)
-==============================================
+Release 1.8 (fido)
+==================
 
 This section provides migration information for moving to the Yocto
 Project 1.8 Release (codename "fido") from the prior release.
@@ -153,8 +153,8 @@ The following QA Check and Validation Changes have occurred:
    instead of ``${D}``.
 
 -  :term:`S` now needs to be set to a valid value within a
-   recipe. If ``S`` is not set in the recipe, the directory is not
-   automatically created. If ``S`` does not point to a directory that
+   recipe. If :term:`S` is not set in the recipe, the directory is not
+   automatically created. If :term:`S` does not point to a directory that
    exists at the time the :ref:`ref-tasks-unpack` task
    finishes, a warning will be shown.
 

documentation/migration-guides/migration-2.0.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 2.0 Release (jethro)
-================================================
+Release 2.0 (jethro)
+====================
 
 This section provides migration information for moving to the Yocto
 Project 2.0 Release (codename "jethro") from the prior release.
@@ -25,7 +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::
+:term:`GCCVERSION` in your configuration, as follows::
 
    GCCVERSION = "4.9%"
 
@@ -244,7 +244,7 @@ The following QA checks have been added:
 
 -  Added an "invalid-packageconfig" check for any options specified in
    :term:`PACKAGECONFIG` that do not match any
-   ``PACKAGECONFIG`` option defined for the recipe.
+   :term:`PACKAGECONFIG` option defined for the recipe.
 
 .. _migration-2.0-miscellaneous:
 

documentation/migration-guides/migration-2.1.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 2.1 Release (krogoth)
-=================================================
+Release 2.1 (krogoth)
+=====================
 
 This section provides migration information for moving to the Yocto
 Project 2.1 Release (codename "krogoth") from the prior release.
@@ -28,8 +28,8 @@ characters. This practice is now a requirement as BitBake's datastore
 now assumes lower-case characters in order to give a slight performance
 boost during parsing. In practical terms, this requirement means that
 anything that ends up in :term:`OVERRIDES` must now
-appear in lower-case characters (e.g. values for ``MACHINE``,
-``TARGET_ARCH``, ``DISTRO``, and also recipe names if
+appear in lower-case characters (e.g. values for :term:`MACHINE`,
+:term:`TARGET_ARCH`, :term:`DISTRO`, and also recipe names if
 ``_pn-``\ recipename overrides are to be effective).
 
 .. _migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory:
@@ -62,13 +62,13 @@ Makefile Environment Changes
 ----------------------------
 
 :term:`EXTRA_OEMAKE` now defaults to "" instead of
-"-e MAKEFLAGS=". Setting ``EXTRA_OEMAKE`` to "-e MAKEFLAGS=" by default
+"-e MAKEFLAGS=". Setting :term:`EXTRA_OEMAKE` to "-e MAKEFLAGS=" by default
 was a historical accident that has required many classes (e.g.
 ``autotools``, ``module``) and recipes to override this default in order
 to work with sensible build systems. When upgrading to the release, you
 must edit any recipe that relies upon this old default by either setting
-``EXTRA_OEMAKE`` back to "-e MAKEFLAGS=" or by explicitly setting any
-required variable value overrides using ``EXTRA_OEMAKE``, which is
+:term:`EXTRA_OEMAKE` back to "-e MAKEFLAGS=" or by explicitly setting any
+required variable value overrides using :term:`EXTRA_OEMAKE`, which is
 typically only needed when a Makefile sets a default value for a
 variable that is inappropriate for cross-compilation using the "="
 operator rather than the "?=" operator.
@@ -179,7 +179,7 @@ The following recipes have been removed in the 2.1 release:
 -  ``python-pygtk``: Recipe became obsolete.
 
 -  ``adt-installer``: Recipe became obsolete. See the
-   ":ref:`ref-manual/migration-2.1:adt removed`" section for more information.
+   ":ref:`migration-guides/migration-2.1:adt removed`" section for more information.
 
 .. _migration-2.1-class-changes:
 
@@ -376,7 +376,7 @@ These additional changes exist:
       run-postinsts
 
    With the Yocto Project 2.1 release, these packages are
-   only removed if "read-only-rootfs" is in ``IMAGE_FEATURES``, since
+   only removed if "read-only-rootfs" is in :term:`IMAGE_FEATURES`, since
    they might still be needed for a read-write image even in the absence
    of a package manager (e.g. if users need to be added, modified, or
    removed at runtime).

documentation/migration-guides/migration-2.2.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 2.2 Release (morty)
-===============================================
+Release 2.2 (morty)
+===================
 
 This section provides migration information for moving to the Yocto
 Project 2.2 Release (codename "morty") from the prior release.
@@ -239,7 +239,7 @@ to catch recipes that are building software without using the
 OpenEmbedded :term:`LDFLAGS`. This change could result in
 seeing some "No GNU_HASH in the elf binary" QA issues when building such
 recipes. You need to fix these recipes so that they use the expected
-``LDFLAGS``. Depending on how the software is built, the build system
+:term:`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::
@@ -263,6 +263,17 @@ If you have recipes or
 classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to
 update the references to ensure they continue to work.
 
+.. _migration-2.2-imgdeploydir-replaces-deploy-dir-image-for-most-use-cases:
+
+``IMGDEPLOYDIR`` Replaces ``DEPLOY_DIR_IMAGE`` for Most Use Cases
+-----------------------------------------------------------------
+
+The :term:`IMGDEPLOYDIR` variable was introduced to allow sstate caching of
+image creation results. Image recipes defining custom :term:`IMAGE_CMD` or
+doing postprocessing on the generated images need to be adapted to use
+:term:`IMGDEPLOYDIR` instead of :term:`DEPLOY_DIR_IMAGE`. :term:`IMAGE_MANIFEST`
+creation and symlinking of the most recent image file will fail otherwise.
+
 .. _migration-2.2-bitbake-changes:
 
 BitBake Changes
@@ -280,8 +291,8 @@ The following changes took place for BitBake:
    :term:`SRC_URI` parameters to specify these. This
    change is more in-line with how the other fetchers work for source
    control systems. Recipes that fetch from Perforce will need to be
-   updated to use ``SRCREV`` in place of specifying the source revision
-   within ``SRC_URI``.
+   updated to use :term:`SRCREV` in place of specifying the source revision
+   within :term:`SRC_URI`.
 
 -  Some of BitBake's internal code structures for accessing the recipe
    cache needed to be changed to support the new multi-configuration
@@ -364,7 +375,7 @@ The following recipes have been removed:
 -  ``sato-icon-theme``: Became obsolete.
 
 -  ``swabber-native``: Swabber has been removed. See the :ref:`entry on
-   Swabber <ref-manual/migration-2.2:swabber has been removed>`.
+   Swabber <migration-guides/migration-2.2:swabber has been removed>`.
 
 -  ``tslib``: No longer needed and has been moved to ``meta-oe``.
 
@@ -390,7 +401,7 @@ The following classes have been removed:
 -  ``sip``: Mostly unused.
 
 -  ``swabber``: See the :ref:`entry on
-   Swabber <ref-manual/migration-2.2:swabber has been removed>`.
+   Swabber <migration-guides/migration-2.2:swabber has been removed>`.
 
 .. _migration-2.2-minor-packaging-changes:
 

documentation/migration-guides/migration-2.3.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 2.3 Release (pyro)
-==============================================
+Release 2.3 (pyro)
+==================
 
 This section provides migration information for moving to the Yocto
 Project 2.3 Release (codename "pyro") from the prior release.
@@ -35,8 +35,8 @@ Consider the following:
    As an example, see the ``dbus`` recipe. You will see that this recipe
    has a ``pkg_postinst`` that calls ``systemctl`` if "systemd" is in
    :term:`DISTRO_FEATURES`. In the example,
-   ``systemd-systemctl-native`` is added to ``PACKAGE_WRITE_DEPS``,
-   which is also conditional on "systemd" being in ``DISTRO_FEATURES``.
+   ``systemd-systemctl-native`` is added to :term:`PACKAGE_WRITE_DEPS`,
+   which is also conditional on "systemd" being in :term:`DISTRO_FEATURES`.
 
 -  Examine Recipes that Use ``SSTATEPOSTINSTFUNCS``: You need to
    examine any recipe that uses ``SSTATEPOSTINSTFUNCS`` and determine
@@ -136,7 +136,7 @@ The following changes to scripts took place:
    removed because the script was found to be deleting files it should
    not have, which lead to broken build trees. Rather than trying to
    delete portions of :term:`TMPDIR` and getting it wrong,
-   it is recommended that you delete ``TMPDIR`` and have it restored
+   it is recommended that you delete :term:`TMPDIR` and have it restored
    from shared state (sstate) on subsequent builds.
 
 -  ``wipe-sysroot``: The ``wipe-sysroot`` script has been removed as
@@ -426,10 +426,10 @@ The following miscellaneous changes have occurred:
 
 -  If the :term:`DISTRO_VERSION` value contains
    the value of the :term:`DATE` variable, which is the
-   default between Poky releases, the ``DATE`` value is explicitly
+   default between Poky releases, the :term:`DATE` value is explicitly
    excluded from ``/etc/issue`` and ``/etc/issue.net``, which is
    displayed at the login prompt, in order to avoid conflicts with
-   Multilib enabled. Regardless, the ``DATE`` value is inaccurate if the
+   Multilib enabled. Regardless, the :term:`DATE` value is inaccurate if the
    ``base-files`` recipe is restored from shared state (sstate) rather
    than rebuilt.
 
@@ -451,7 +451,7 @@ The following miscellaneous changes have occurred:
    tools.
 
 -  The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig"
-   ``DISTRO_FEATURES`` feature. Distributions that previously set::
+   :term:`DISTRO_FEATURES` feature. Distributions that previously set::
 
       USE_LDCONFIG = "0"
 
@@ -494,12 +494,12 @@ The following miscellaneous changes have occurred:
    information.
 
 -  All native and nativesdk recipes now use a separate
-   ``DISTRO_FEATURES`` value instead of sharing the value used by
+   :term:`DISTRO_FEATURES` value instead of sharing the value used by
    recipes for the target, in order to avoid unnecessary rebuilds.
 
-   The ``DISTRO_FEATURES`` for ``native`` recipes is
+   The :term:`DISTRO_FEATURES` for ``native`` recipes is
    :term:`DISTRO_FEATURES_NATIVE` added to
-   an intersection of ``DISTRO_FEATURES`` and
+   an intersection of :term:`DISTRO_FEATURES` and
    :term:`DISTRO_FEATURES_FILTER_NATIVE`.
 
    For nativesdk recipes, the corresponding variables are

documentation/migration-guides/migration-2.4.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 2.4 Release (rocko)
-===============================================
+Release 2.4 (rocko)
+===================
 
 This section provides migration information for moving to the Yocto
 Project 2.4 Release (codename "rocko") from the prior release.
@@ -51,7 +51,7 @@ occurred:
       ``su`` is normally provided through the shadow file format. The
       main ``util-linux`` package has runtime dependencies (i.e.
       :term:`RDEPENDS`) on the ``util-linux-su`` package
-      when "pam" is in ``DISTRO_FEATURES``.
+      when "pam" is in :term:`DISTRO_FEATURES`.
 
    -  The ``switch_root`` program is now packaged in a separate
       "util-linux-switch-root" package for small initramfs images that
@@ -63,7 +63,7 @@ occurred:
 
    -  The ``ionice`` program is now packaged in a separate
       "util-linux-ionice" package. The main ``util-linux`` package has a
-      recommended runtime dependency (i.e. ``RRECOMMENDS``) on the
+      recommended runtime dependency (i.e. :term:`RRECOMMENDS`) on the
       ``util-linux-ionice`` package.
 
 -  ``initscripts``: The ``sushell`` program is now packaged in a
@@ -71,11 +71,11 @@ occurred:
    systems to pull ``sushell`` in when ``selinux`` is enabled. The
    change also eliminates needing to pull in the entire ``initscripts``
    package. The main ``initscripts`` package has a runtime dependency
-   (i.e. ``RDEPENDS``) on the ``sushell`` package when "selinux" is in
-   ``DISTRO_FEATURES``.
+   (i.e. :term:`RDEPENDS`) on the ``sushell`` package when "selinux" is in
+   :term:`DISTRO_FEATURES`.
 
 -  ``glib-2.0``: The ``glib-2.0`` package now has a recommended
-   runtime dependency (i.e. ``RRECOMMENDS``) on the ``shared-mime-info``
+   runtime dependency (i.e. :term:`RRECOMMENDS`) on the ``shared-mime-info``
    package, since large portions of GIO are not useful without the MIME
    database. You can remove the dependency by using the
    :term:`BAD_RECOMMENDATIONS` variable if

documentation/migration-guides/migration-2.5.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 2.5 Release (sumo)
-==============================================
+Release 2.5 (sumo)
+==================
 
 This section provides migration information for moving to the Yocto
 Project 2.5 Release (codename "sumo") from the prior release.
@@ -278,12 +278,12 @@ The following are additional changes:
    performance and compression. In order to build a live image with
    squashfs+lz4 compression enabled you should now set
    ``LIVE_ROOTFS_TYPE = "squashfs-lz4"`` and ensure that ``live`` is in
-   ``IMAGE_FSTYPES``.
+   :term:`IMAGE_FSTYPES`.
 
 -  Recipes with an unconditional dependency on ``libpam`` are only
-   buildable with ``pam`` in ``DISTRO_FEATURES``. If the dependency is
+   buildable with ``pam`` in :term:`DISTRO_FEATURES`. If the dependency is
    truly optional then it is recommended that the dependency be
-   conditional upon ``pam`` being in ``DISTRO_FEATURES``.
+   conditional upon ``pam`` being in :term:`DISTRO_FEATURES`.
 
 -  For EFI-based machines, the bootloader (``grub-efi`` by default) is
    installed into the image at /boot. Wic can be used to split the

documentation/migration-guides/migration-2.6.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 2.6 Release (thud)
-==============================================
+Release 2.6 (thud)
+==================
 
 This section provides migration information for moving to the Yocto
 Project 2.6 Release (codename "thud") from the prior release.
@@ -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
-:ref:`ref-manual/migration-2.6:removed recipes` section.
+:ref:`migration-guides/migration-2.6:removed recipes` section.
 
 .. _migration-2.6-distutils-distutils3-fetching-dependencies:
 
@@ -156,11 +156,11 @@ Image/Kernel Artifact Naming Changes
 The following changes have been made:
 
 -  Name variables (e.g. :term:`IMAGE_NAME`) use a new
-   ``IMAGE_VERSION_SUFFIX`` variable instead of
-   :term:`DATETIME`. Using ``IMAGE_VERSION_SUFFIX``
+   :term:`IMAGE_VERSION_SUFFIX` variable instead of
+   :term:`DATETIME`. Using :term:`IMAGE_VERSION_SUFFIX`
    allows easier and more direct changes.
 
-   The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf``
+   The :term:`IMAGE_VERSION_SUFFIX` variable is set in the ``bitbake.conf``
    configuration file as follows::
 
       IMAGE_VERSION_SUFFIX = "-${DATETIME}"
@@ -212,19 +212,19 @@ The following changes have been made:
 The :term:`SERIAL_CONSOLE` variable has been
 functionally replaced by the
 :term:`SERIAL_CONSOLES` variable for some time.
-With the Yocto Project 2.6 release, ``SERIAL_CONSOLE`` has been
+With the Yocto Project 2.6 release, :term:`SERIAL_CONSOLE` has been
 officially deprecated.
 
-``SERIAL_CONSOLE`` will continue to work as before for the 2.6 release.
+:term:`SERIAL_CONSOLE` will continue to work as before for the 2.6 release.
 However, for the sake of future compatibility, it is recommended that
-you replace all instances of ``SERIAL_CONSOLE`` with
-``SERIAL_CONSOLES``.
+you replace all instances of :term:`SERIAL_CONSOLE` with
+:term:`SERIAL_CONSOLES`.
 
 .. note::
 
-   The only difference in usage is that ``SERIAL_CONSOLES``
+   The only difference in usage is that :term:`SERIAL_CONSOLES`
    expects entries to be separated using semicolons as compared to
-   ``SERIAL_CONSOLE``, which expects spaces.
+   :term:`SERIAL_CONSOLE`, which expects spaces.
 
 .. _migration-2.6-poky-sets-unknown-configure-option-to-qa-error:
 
@@ -387,14 +387,14 @@ QEMU (i.e. "qemu-usermode" is in
 default).
 
 If you wish to disable Python profile-guided optimization regardless of
-the value of ``MACHINE_FEATURES``, then ensure that
+the value of :term:`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::
 
    PACKAGECONFIG_remove_pn-python3 = "pgo"
 
-Alternatively, you can set ``PACKAGECONFIG`` using an append file
+Alternatively, you can set :term:`PACKAGECONFIG` using an append file
 for the ``python3`` recipe.
 
 .. _migration-2.6-miscellaneous-changes:
@@ -430,7 +430,7 @@ The following miscellaneous changes occurred:
    .. note::
 
       ``genericx86`` and ``genericx86-64`` retain ``kernel-modules`` as part of
-      the ``RRECOMMENDS`` variable setting.
+      the :term:`RRECOMMENDS` variable setting.
 
 -  The ``LGPLv2_WHITELIST_GPL-3.0`` variable has been removed. If you
    are setting this variable in your configuration, set or append it to

documentation/migration-guides/migration-2.7.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 2.7 Release (warrior)
-=================================================
+Release 2.7 (warrior)
+=====================
 
 This section provides migration information for moving to the Yocto
 Project 2.7 Release (codename "warrior") from the prior release.
@@ -72,7 +72,7 @@ License Value Corrections
 The following corrections have been made to the
 :term:`LICENSE` values set by recipes:
 
-- *socat*: Corrected ``LICENSE`` to be "GPLv2" rather than "GPLv2+".
+- *socat*: Corrected :term:`LICENSE` to be "GPLv2" rather than "GPLv2+".
 - *libgfortran*: Set license to "GPL-3.0-with-GCC-exception".
 - *elfutils*: Removed "Elfutils-Exception" and set to "GPLv2" for shared libraries
 
@@ -91,7 +91,7 @@ This section provides information about packaging changes.
    package_name\ ``-src``). If you are currently using ``dbg-pkgs`` in
    :term:`IMAGE_FEATURES` to bring in debug
    symbols and you still need the sources, you must now also add
-   ``src-pkgs`` to ``IMAGE_FEATURES``. Source packages remain in the
+   ``src-pkgs`` to :term:`IMAGE_FEATURES`. Source packages remain in the
    target portion of the SDK by default, unless you have set your own
    value for :term:`SDKIMAGE_FEATURES` that
    does not include ``src-pkgs``.

documentation/migration-guides/migration-3.0.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 3.0 Release (zeus)
-==============================================
+Release 3.0 (zeus)
+==================
 
 This section provides migration information for moving to the Yocto
 Project 3.0 Release (codename "zeus") from the prior release.
@@ -184,10 +184,9 @@ The following BitBake changes have occurred.
    exceptions. Remove this argument in any calls to
    ``bb.build.exec_func()`` in custom classes or scripts.
 
--  The
-   :term:`bitbake:BB_SETSCENE_VERIFY_FUNCTION2`
-   is no longer used. In the unlikely event that you have any references
-   to it, they should be removed.
+-  The ``BB_SETSCENE_VERIFY_FUNCTION2`` variable is no longer used. In
+   the unlikely event that you have any references to it, they should be
+   removed.
 
 -  The ``RunQueueExecuteScenequeue`` and ``RunQueueExecuteTasks`` events
    have been removed since setscene tasks are now executed as part of
@@ -244,7 +243,7 @@ The following sanity check changes occurred.
 -  Setting ``DEPENDS_${PN}`` anywhere (i.e. typically in a recipe) now
    triggers an error. The error is triggered because
    :term:`DEPENDS` is not a package-specific variable
-   unlike RDEPENDS. You should set ``DEPENDS`` instead.
+   unlike RDEPENDS. You should set :term:`DEPENDS` instead.
 
 -  systemd currently does not work well with the musl C library because
    only upstream officially supports linking the library with glibc.

documentation/migration-guides/migration-3.1.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 3.1 Release (dunfell)
-=================================================
+Release 3.1 (dunfell)
+=====================
 
 This section provides migration information for moving to the Yocto
 Project 3.1 Release (codename "dunfell") from the prior release.
@@ -260,7 +260,7 @@ Miscellaneous changes
 ---------------------
 
 -  The undocumented ``SRC_DISTRIBUTE_LICENSES`` variable has now been
-   removed in favour of a new ``AVAILABLE_LICENSES`` variable which is
+   removed in favour of a new :term:`AVAILABLE_LICENSES` variable which is
    dynamically set based upon license files found in
    ``${COMMON_LICENSE_DIR}`` and ``${LICENSE_PATH}``.
 

documentation/migration-guides/migration-3.2.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 3.2 Release (gatesgarth)
-====================================================
+Release 3.2 (gatesgarth)
+========================
 
 This section provides migration information for moving to the Yocto
 Project 3.2 Release (codename "gatesgarth") from the prior release.
@@ -62,10 +62,10 @@ There is a possible complication where some existing recipe may break, for
 example, a recipe was found to be writing to ``${B}/install`` for
 ``make install`` in ``do_install`` and since ``${B}`` is listed as not to be tracked,
 there were errors trying to ``chown root`` for files in this location. Another
-example was the ``tcl`` recipe where the source directory ``S`` is set to a
+example was the ``tcl`` recipe where the source directory :term:`S` is set to a
 subdirectory of the source tree but files were written out to the directory
 structure above that subdirectory. For these types of cases in your own recipes,
-extend ``PSEUDO_IGNORE_PATHS`` to cover additional paths that pseudo should not
+extend :term:`PSEUDO_IGNORE_PATHS` to cover additional paths that pseudo should not
 be monitoring.
 
 In addition, pseudo's behaviour on mismatches has now been changed - rather
@@ -207,7 +207,7 @@ files into a subdirectory and reference that instead.
 deploy class now cleans ``DEPLOYDIR`` before ``do_deploy``
 ----------------------------------------------------------
 
-``do_deploy`` as implemented in the :ref:`deploy <ref-classes-deploy>` class now cleans up ${:term:`DEPLOYDIR`} before running, just as ``do_install`` cleans up ${:term:`D`} before running. This reduces the risk of ``DEPLOYDIR`` being accidentally contaminated by files from previous runs, possibly even with different config, in case of incremental builds.
+``do_deploy`` as implemented in the :ref:`deploy <ref-classes-deploy>` class now cleans up ${:term:`DEPLOYDIR`} before running, just as ``do_install`` cleans up ${:term:`D`} before running. This reduces the risk of :term:`DEPLOYDIR` being accidentally contaminated by files from previous runs, possibly even with different config, in case of incremental builds.
 
 Most recipes and classes that inherit the ``deploy`` class or interact with ``do_deploy`` are unlikely to be affected by this unless they add ``prefuncs`` to ``do_deploy`` *which also* put files into ``${DEPLOYDIR}`` - these should be refactored to use ``do_deploy_prepend`` instead.
 

documentation/migration-guides/migration-3.3.rst

@@ -1,5 +1,5 @@
-Moving to the Yocto Project 3.3 Release (hardknott)
-===================================================
+Release 3.3 (hardknott)
+=======================
 
 This section provides migration information for moving to the Yocto
 Project 3.3 Release (codename "hardknott") from the prior release.

documentation/overview-manual/concepts.rst

@@ -139,7 +139,7 @@ hardware-specific configurations allows you to share other metadata by
 using a different layer where that metadata might be common across
 several pieces of hardware.
 
-Many layers exist that work in the Yocto Project development environment. The
+There are many layers working in the Yocto Project development environment. The
 :yocto_home:`Yocto Project Curated Layer Index </software-overview/layers/>`
 and :oe_layerindex:`OpenEmbedded Layer Index <>` both contain layers from
 which you can use or leverage.
@@ -332,7 +332,7 @@ created by an autobuilder:
    One useful scenario for using the ``conf/site.conf`` file is to
    extend your :term:`BBPATH` variable
    to include the path to a ``conf/site.conf``. Then, when BitBake looks
-   for Metadata using ``BBPATH``, it finds the ``conf/site.conf`` file
+   for Metadata using :term:`BBPATH`, it finds the ``conf/site.conf`` file
    and applies your common configurations found in the file. To override
    configurations in a particular build directory, alter the similar
    configurations within that build directory's ``conf/local.conf``
@@ -370,7 +370,7 @@ BitBake's global behavior. This section takes a closer look at the
 layers the build system uses to further control the build. These layers
 provide Metadata for the software, machine, and policies.
 
-In general, three types of layer input exists. You can see them below
+In general, there are three types of layer input. You can see them below
 the "User Configuration" box in the `general workflow
 figure <overview-manual/concepts:openembedded build system concepts>`:
 
@@ -427,8 +427,8 @@ Repositories <>` also shows layers categorized under "Yocto Metadata Layers."
 
 .. note::
 
-   Layers exist in the Yocto Project Source Repositories that cannot be
-   found in the OpenEmbedded Layer Index. These layers are either
+   There are layers in the Yocto Project Source Repositories that cannot be
+   found in the OpenEmbedded Layer Index. Such layers are either
    deprecated or experimental in nature.
 
 BitBake uses the ``conf/bblayers.conf`` file, which is part of the user
@@ -489,7 +489,7 @@ the machine (``conf/machine/machine.conf``) and, of course, the layer
 
 The remainder of the layer is dedicated to specific recipes by function:
 ``recipes-bsp``, ``recipes-core``, ``recipes-graphics``,
-``recipes-kernel``, and so forth. Metadata can exist for multiple
+``recipes-kernel``, and so forth. There can be metadata for multiple
 formfactors, graphics support systems, and so forth.
 
 .. note::
@@ -528,13 +528,11 @@ project that is more dynamic or experimental in nature, a project might
 keep source files in a repository controlled by a Source Control Manager
 (SCM) such as Git. Pulling source from a repository allows you to
 control the point in the repository (the revision) from which you want
-to build software. Finally, a combination of the two might exist, which
-would give the consumer a choice when deciding where to get source
-files.
+to build software. A combination of the two is also possible.
 
 BitBake uses the :term:`SRC_URI`
 variable to point to source files regardless of their location. Each
-recipe must have a ``SRC_URI`` variable that points to the source.
+recipe must have a :term:`SRC_URI` variable that points to the source.
 
 Another area that plays a significant role in where source files come
 from is pointed to by the
@@ -542,13 +540,13 @@ from is pointed to by the
 a cache that can hold previously downloaded source. You can also
 instruct the OpenEmbedded build system to create tarballs from Git
 repositories, which is not the default behavior, and store them in the
-``DL_DIR`` by using the
+:term:`DL_DIR` by using the
 :term:`BB_GENERATE_MIRROR_TARBALLS`
 variable.
 
-Judicious use of a ``DL_DIR`` directory can save the build system a trip
+Judicious use of a :term:`DL_DIR` directory can save the build system a trip
 across the Internet when looking for files. A good method for using a
-download directory is to have ``DL_DIR`` point to an area outside of
+download directory is to have :term:`DL_DIR` point to an area outside of
 your Build Directory. Doing so allows you to safely delete the Build
 Directory if needed without fear of removing any downloaded source file.
 
@@ -609,7 +607,7 @@ the specific revision from which to build.
 Source Mirror(s)
 ~~~~~~~~~~~~~~~~
 
-Two kinds of mirrors exist: pre-mirrors and regular mirrors. The
+There are two kinds of mirrors: pre-mirrors and regular mirrors. The
 :term:`PREMIRRORS` and
 :term:`MIRRORS` variables point to
 these, respectively. BitBake checks pre-mirrors before looking upstream
@@ -667,8 +665,8 @@ package files are kept:
    variables are used, respectively.
 
 -  :term:`PACKAGE_ARCH`: Defines
-   architecture-specific sub-folders. For example, packages could exist
-   for the i586 or qemux86 architectures.
+   architecture-specific sub-folders. For example, packages could be
+   available for the i586 or qemux86 architectures.
 
 BitBake uses the
 :ref:`do_package_write_* <ref-tasks-package_write_deb>`
@@ -681,8 +679,8 @@ and
 ":ref:`ref-tasks-package_write_tar`"
 sections in the Yocto Project Reference Manual for additional
 information. As an example, consider a scenario where an IPK packaging
-manager is being used and package architecture support for both i586 and
-qemux86 exist. Packages for the i586 architecture are placed in
+manager is being used and there is package architecture support for both
+i586 and qemux86. Packages for the i586 architecture are placed in
 ``build/tmp/deploy/ipk/i586``, while packages for the qemux86
 architecture are placed in ``build/tmp/deploy/ipk/qemux86``.
 
@@ -698,7 +696,7 @@ closer look at each of those areas.
 
 .. note::
 
-   Separate documentation exists for the BitBake tool. See the
+   Documentation for the BitBake tool is available separately. See the
    BitBake User Manual
    for reference material on BitBake.
 
@@ -749,7 +747,7 @@ Build Directory's hierarchy:
    architecture of the built package or packages. Depending on the
    eventual destination of the package or packages (i.e. machine
    architecture, :term:`Build Host`, SDK, or
-   specific machine), ``PACKAGE_ARCH`` varies. See the variable's
+   specific machine), :term:`PACKAGE_ARCH` varies. See the variable's
    description for details.
 
 -  :term:`TARGET_OS`: The operating
@@ -758,7 +756,7 @@ Build Directory's hierarchy:
 
 -  :term:`PN`: The name of the recipe used
    to build the package. This variable can have multiple meanings.
-   However, when used in the context of input files, ``PN`` represents
+   However, when used in the context of input files, :term:`PN` represents
    the name of the recipe.
 
 -  :term:`WORKDIR`: The location
@@ -775,20 +773,18 @@ Build Directory's hierarchy:
    files for a given recipe.
 
    -  :term:`BPN`: The name of the recipe
-      used to build the package. The ``BPN`` variable is a version of
-      the ``PN`` variable but with common prefixes and suffixes removed.
+      used to build the package. The :term:`BPN` variable is a version of
+      the :term:`PN` variable but with common prefixes and suffixes removed.
 
    -  :term:`PV`: The version of the
       recipe used to build the package.
 
 .. note::
 
-   In the previous figure, notice that two sample hierarchies exist: one
-   based on package architecture (i.e.
-   PACKAGE_ARCH
-   ) and one based on a machine (i.e.
-   MACHINE
-   ). The underlying structures are identical. The differentiator being
+   In the previous figure, notice that there are two sample hierarchies:
+   one based on package architecture (i.e. :term:`PACKAGE_ARCH`)
+   and one based on a machine (i.e. :term:`MACHINE`).
+   The underlying structures are identical. The differentiator being
    what the OpenEmbedded build system is using as a build target (e.g.
    general architecture, a build host, an SDK, or a specific machine).
 
@@ -807,13 +803,13 @@ and the :term:`FILESPATH` variable
 to locate applicable patch files.
 
 Default processing for patch files assumes the files have either
-``*.patch`` or ``*.diff`` file types. You can use ``SRC_URI`` parameters
+``*.patch`` or ``*.diff`` file types. You can use :term:`SRC_URI` parameters
 to change the way the build system recognizes patch files. See the
 :ref:`ref-tasks-patch` task for more
 information.
 
 BitBake finds and applies multiple patches for a single recipe in the
-order in which it locates the patches. The ``FILESPATH`` variable
+order in which it locates the patches. The :term:`FILESPATH` variable
 defines the default set of directories that the build system uses to
 search for patch files. Once found, patches are applied to the recipe's
 source files, which are located in the
@@ -881,12 +877,12 @@ This step in the build process consists of the following tasks:
    :ref:`ref-tasks-compile` task.
    Compilation occurs in the directory pointed to by the
    :term:`B` variable. Realize that the
-   ``B`` directory is, by default, the same as the
+   :term:`B` directory is, by default, the same as the
    :term:`S` directory.
 
 -  *do_install*: After compilation completes, BitBake executes the
    :ref:`ref-tasks-install` task.
-   This task copies files from the ``B`` directory and places them in a
+   This task copies files from the :term:`B` directory and places them in a
    holding area pointed to by the :term:`D`
    variable. Packaging occurs later using files from this holding
    directory.
@@ -932,7 +928,7 @@ the analysis and package splitting process use several areas:
 -  :term:`PKGDATA_DIR`: A shared,
    global-state directory that holds packaging metadata generated during
    the packaging process. The packaging process copies metadata from
-   ``PKGDESTWORK`` to the ``PKGDATA_DIR`` area where it becomes globally
+   :term:`PKGDESTWORK` to the :term:`PKGDATA_DIR` area where it becomes globally
    available.
 
 -  :term:`STAGING_DIR_HOST`:
@@ -963,8 +959,7 @@ that part of the build process.
 
 .. note::
 
-   Support for creating feeds directly from the
-   deploy/\*
+   Support for creating feeds directly from the ``deploy/*``
    directories does not exist. Creating such feeds usually requires some
    kind of feed maintenance mechanism that would upload the new packages
    into an official package feed (e.g. the Ångström distribution). This
@@ -1013,7 +1008,7 @@ actually install:
 
 With :term:`IMAGE_ROOTFS`
 pointing to the location of the filesystem under construction and the
-``PACKAGE_INSTALL`` variable providing the final list of packages to
+:term:`PACKAGE_INSTALL` variable providing the final list of packages to
 install, the root file system is created.
 
 Package installation is under control of the package manager (e.g.
@@ -1062,7 +1057,7 @@ based on the image types specified in the
 The process turns everything into an image file or a set of image files
 and can compress the root filesystem image to reduce the overall size of
 the image. The formats used for the root filesystem depend on the
-``IMAGE_FSTYPES`` variable. Compression depends on whether the formats
+:term:`IMAGE_FSTYPES` variable. Compression depends on whether the formats
 support compression.
 
 As an example, a dynamically created task when creating a particular
@@ -1071,7 +1066,7 @@ image type would take the following form::
    do_image_type
 
 So, if the type
-as specified by the ``IMAGE_FSTYPES`` were ``ext4``, the dynamically
+as specified by the :term:`IMAGE_FSTYPES` were ``ext4``, the dynamically
 generated task would be as follows::
 
    do_image_ext4
@@ -1156,9 +1151,9 @@ checksum <overview-manual/concepts:checksums (signatures)>`.
    OpenEmbedded.
 
 To determine if a task needs to be rerun, BitBake checks if a stamp file
-with a matching input checksum exists for the task. If such a stamp file
-exists, the task's output is assumed to exist and still be valid. If the
-file does not exist, the task is rerun.
+with a matching input checksum exists for the task. In this case,
+the task's output is assumed to exist and still be valid. Otherwise,
+the task is rerun.
 
 .. note::
 
@@ -1176,9 +1171,9 @@ file does not exist, the task is rerun.
    the sstate cache mechanism adds is a way to cache task output that
    can then be shared between build machines.
 
-Since ``STAMPS_DIR`` is usually a subdirectory of ``TMPDIR``, removing
-``TMPDIR`` will also remove ``STAMPS_DIR``, which means tasks will
-properly be rerun to repopulate ``TMPDIR``.
+Since :term:`STAMPS_DIR` is usually a subdirectory of :term:`TMPDIR`, removing
+:term:`TMPDIR` will also remove :term:`STAMPS_DIR`, which means tasks will
+properly be rerun to repopulate :term:`TMPDIR`.
 
 If you want some task to always be considered "out of date", you can
 mark it with the :ref:`nostamp <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`
@@ -1234,14 +1229,14 @@ to run any of the ``do_fetch``, ``do_unpack``, ``do_patch``,
 
 It becomes more complicated if everything can come from an sstate cache
 because some objects are simply not required at all. For example, you do
-not need a compiler or native tools, such as quilt, if nothing exists to
-compile or patch. If the ``do_package_write_*`` packages are available
+not need a compiler or native tools, such as quilt, if there isn't anything
+to compile or patch. If the ``do_package_write_*`` packages are available
 from sstate, BitBake does not need the ``do_package`` task data.
 
 To handle all these complexities, BitBake runs in two phases. The first
 is the "setscene" stage. During this stage, BitBake first checks the
 sstate cache for any targets it is planning to build. BitBake does a
-fast check to see if the object exists rather than a complete download.
+fast check to see if the object exists rather than doing a complete download.
 If nothing exists, the second phase, which is the setscene stage,
 completes and the main build proceeds.
 
@@ -1366,9 +1361,9 @@ can initialize the environment before using the tools.
 
 All the output files for an SDK are written to the ``deploy/sdk`` folder
 inside the :term:`Build Directory` as
-shown in the previous figure. Depending on the type of SDK, several
-variables exist that help configure these files. The following list
-shows the variables associated with an extensible SDK:
+shown in the previous figure. Depending on the type of SDK, there are
+several variables to configure these files. Here are the variables
+associated with an extensible SDK:
 
 -  :term:`DEPLOY_DIR`: Points to
    the ``deploy`` directory.
@@ -1413,7 +1408,7 @@ This next list, shows the variables associated with a standard SDK:
 
 -  :term:`TOOLCHAIN_HOST_TASK`:
    Lists packages that make up the host part of the SDK (i.e. the part
-   that runs on the ``SDKMACHINE``). When you use
+   that runs on the :term:`SDKMACHINE`). When you use
    ``bitbake -c populate_sdk imagename`` to create the SDK, a set of
    default packages apply. This variable allows you to add more
    packages.
@@ -1467,12 +1462,9 @@ cross-compiler that is used internally within BitBake only.
 
 .. note::
 
-   The extensible SDK does not use
-   gcc-cross-canadian
+   The extensible SDK does not use ``gcc-cross-canadian``
    since this SDK ships a copy of the OpenEmbedded build system and the
-   sysroot within it contains
-   gcc-cross
-   .
+   sysroot within it contains ``gcc-cross``.
 
 The chain of events that occurs when the standard toolchain is bootstrapped::
 
@@ -1577,8 +1569,8 @@ Shared State Cache
 By design, the OpenEmbedded build system builds everything from scratch
 unless :term:`BitBake` can determine
 that parts do not need to be rebuilt. Fundamentally, building from
-scratch is attractive as it means all parts are built fresh and no
-possibility of stale data exists that can cause problems. When
+scratch is attractive as it means all parts are built fresh and there is
+no possibility of stale data that can cause problems. When
 developers hit problems, they typically default back to building from
 scratch so they have a know state from the start.
 
@@ -1617,9 +1609,9 @@ them if they are deemed to be valid.
 
    -  The build system does not maintain
       :term:`PR` information as part of
-      the shared state packages. Consequently, considerations exist that
+      the shared state packages. Consequently, there are considerations that
       affect maintaining shared state feeds. For information on how the
-      build system works with packages and can track incrementing ``PR``
+      build system works with packages and can track incrementing :term:`PR`
       information, see the ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`"
       section in the Yocto Project Development Tasks Manual.
 
@@ -1676,8 +1668,8 @@ objective of making native or cross packages relocatable.
    build host. However, cross packages generate output for the target
    architecture.
 
-The checksum therefore needs to exclude ``WORKDIR``. The simplistic
-approach for excluding the work directory is to set ``WORKDIR`` to some
+The checksum therefore needs to exclude :term:`WORKDIR`. The simplistic
+approach for excluding the work directory is to set :term:`WORKDIR` to some
 fixed value and create the checksum for the "run" script.
 
 Another problem results from the "run" scripts containing functions that
@@ -1687,7 +1679,7 @@ used to prune the "run" scripts down to the minimum set, thereby
 alleviating this problem and making the "run" scripts much more readable
 as a bonus.
 
-So far, solutions for shell scripts exist. What about Python tasks? The
+So far, there are solutions for shell scripts. What about Python tasks? The
 same approach applies even though these tasks are more difficult. The
 process needs to figure out what variables a Python function accesses
 and what functions it calls. Again, the incremental build solution
@@ -1695,7 +1687,7 @@ contains code that first figures out the variable and function
 dependencies, and then creates a checksum for the data used as the input
 to the task.
 
-Like the ``WORKDIR`` case, situations exist where dependencies should be
+Like the :term:`WORKDIR` case, there can be situations 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::
 
@@ -1712,7 +1704,7 @@ following::
    PACKAGE_ARCHS[vardeps] = "MACHINE"
 
 This example explicitly
-adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``.
+adds the :term:`MACHINE` variable as a dependency for :term:`PACKAGE_ARCHS`.
 
 As an example, consider a case with in-line Python where BitBake is not
 able to figure out dependencies. When running in debug mode (i.e. using
@@ -1732,7 +1724,7 @@ to add is a policy decision. However, the effect is to generate a master
 checksum that combines the basehash and the hashes of the task's
 dependencies.
 
-At the code level, a variety of ways exist by which both the basehash
+At the code level, there are multiple ways by which both the basehash
 and the dependent task hashes can be influenced. Within the BitBake
 configuration file, you can give BitBake some extra information to help
 it construct the basehash. The following statement effectively results
@@ -1766,7 +1758,7 @@ through this setting in the ``bitbake.conf`` file::
 
    BB_SIGNATURE_HANDLER ?= "OEBasicHash"
 
-The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same
+The "OEBasicHash" :term:`BB_SIGNATURE_HANDLER` is the same
 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
@@ -1787,7 +1779,7 @@ the build. This information includes:
 -  ``BBHASHDEPS_``\ filename\ ``:``\ taskname: The task dependencies for
    each task.
 
--  ``BB_TASKHASH``: The hash of the currently running task.
+-  :term:`BB_TASKHASH`: The hash of the currently running task.
 
 Shared State
 ------------
@@ -1856,7 +1848,7 @@ The following list explains the previous example:
       ``do_deploy`` is in the shared state cache and its signature indicates
       that the cached output is still valid (i.e. if no relevant task inputs
       have changed), then the contents of the shared state cache copies
-      directly to ${``DEPLOY_DIR_IMAGE``} by the ``do_deploy_setscene`` task
+      directly to ${:term:`DEPLOY_DIR_IMAGE`} by the ``do_deploy_setscene`` task
       instead, skipping the ``do_deploy`` task.
 
 -  The following task definition is glue logic needed to make the
@@ -1902,8 +1894,8 @@ The following list explains the previous example:
 
 -  ``sstate-inputdirs`` and ``sstate-outputdirs`` can also be used with
    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
+   :term:`PKGDESTWORK` and ``SHLIBWORK`` as shared state input directories,
+   which populates the shared state cache, and :term:`PKGDATA_DIR` and
    ``SHLIBSDIR`` as the corresponding shared state output directories::
 
       do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
@@ -1926,11 +1918,11 @@ shared state files. Here is an example::
 
 .. note::
 
-   The shared state directory (``SSTATE_DIR``) is organized into two-character
+   The shared state directory (:term:`SSTATE_DIR`) is organized into two-character
    subdirectories, where the subdirectory names are based on the first two
    characters of the hash.
    If the shared state directory structure for a mirror has the same structure
-   as ``SSTATE_DIR``, you must specify "PATH" as part of the URI to enable the build
+   as :term:`SSTATE_DIR`, you must specify "PATH" as part of the URI to enable the build
    system to map to the appropriate subdirectory.
 
 The shared state package validity can be detected just by looking at the
@@ -1961,8 +1953,8 @@ Automatically Added Runtime Dependencies
 The OpenEmbedded build system automatically adds common types of runtime
 dependencies between packages, which means that you do not need to
 explicitly declare the packages using
-:term:`RDEPENDS`. Three automatic
-mechanisms exist (``shlibdeps``, ``pcdeps``, and ``depchains``) that
+:term:`RDEPENDS`. There are three automatic
+mechanisms (``shlibdeps``, ``pcdeps``, and ``depchains``) that
 handle shared libraries, package configuration (pkg-config) modules, and
 ``-dev`` and ``-dbg`` packages, respectively. For other types of runtime
 dependencies, you must manually declare the dependencies.
@@ -1981,7 +1973,7 @@ dependencies, you must manually declare the dependencies.
 
    Simultaneously, all executables and shared libraries installed by the
    recipe are inspected to see what shared libraries they link against.
-   For each shared library dependency that is found, ``PKGDATA_DIR`` is
+   For each shared library dependency that is found, :term:`PKGDATA_DIR` is
    queried to see if some package (likely from a different recipe)
    contains the shared library. If such a package is found, a runtime
    dependency is added from the package that depends on the shared
@@ -1990,7 +1982,7 @@ dependencies, you must manually declare the dependencies.
    The automatically added runtime dependency also includes a version
    restriction. This version restriction specifies that at least the
    current version of the package that provides the shared library must
-   be used, as if "package (>= version)" had been added to ``RDEPENDS``.
+   be used, as if "package (>= version)" had been added to :term:`RDEPENDS`.
    This forces an upgrade of the package containing the shared library
    when installing the package that depends on the library, if needed.
 
@@ -2004,14 +1996,14 @@ dependencies, you must manually declare the dependencies.
    pkg-config modules (``*.pc`` files) installed by the recipe are
    located. For each module, the package that contains the module is
    registered as providing the module. The resulting module-to-package
-   mapping is saved globally in ``PKGDATA_DIR`` by the
+   mapping is saved globally in :term:`PKGDATA_DIR` by the
    ``do_packagedata`` task.
 
    Simultaneously, all pkg-config modules installed by the recipe are
    inspected to see what other pkg-config modules they depend on. A
    module is seen as depending on another module if it contains a
    "Requires:" line that specifies the other module. For each module
-   dependency, ``PKGDATA_DIR`` is queried to see if some package
+   dependency, :term:`PKGDATA_DIR` is queried to see if some package
    contains the module. If such a package is found, a runtime dependency
    is added from the package that depends on the module to the package
    that contains the module.
@@ -2036,7 +2028,7 @@ dependencies, you must manually declare the dependencies.
 
    .. note::
 
-      By default, ``foo-dev`` also has an ``RDEPENDS``-style dependency on
+      By default, ``foo-dev`` also has an :term:`RDEPENDS`-style dependency on
       ``foo``, because the default value of ``RDEPENDS_${PN}-dev`` (set in
       bitbake.conf) includes "${PN}".
 
@@ -2051,7 +2043,7 @@ recipe in :term:`DEPENDS` through use
 of a ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]``
 declaration, which guarantees that the required
 shared-library/module-to-package mapping information will be available
-when needed as long as ``DEPENDS`` has been correctly set.
+when needed as long as :term:`DEPENDS` has been correctly set.
 
 Fakeroot and Pseudo
 ===================

documentation/overview-manual/development-environment.rst

@@ -71,7 +71,7 @@ section in
 the Yocto Project Development Tasks Manual.
 
 If your development host is going to be a system that runs a Linux
-distribution, steps still exist that you must take to prepare the system
+distribution, you must still take steps to prepare the system
 for use with the Yocto Project. You need to be sure that the Linux
 distribution on the system is one that supports the Yocto Project. You
 also need to be sure that the correct set of host packages are installed
@@ -80,8 +80,8 @@ set up a development host that runs Linux, see the
 ":ref:`dev-manual/start:setting up a native linux host`"
 section in the Yocto Project Development Tasks Manual.
 
-Once your development host is set up to use the Yocto Project, several
-methods exist for you to do work in the Yocto Project environment:
+Once your development host is set up to use the Yocto Project, there
+are several ways of working in the Yocto Project environment:
 
 -  *Command Lines, BitBake, and Shells:* Traditional development in the
    Yocto Project involves using the :term:`OpenEmbedded Build System`,
@@ -271,7 +271,7 @@ files that are being worked on simultaneously by more than one person.
 All this work is done locally on the development host before anything is
 pushed to a "contrib" area and examined at the maintainer's level.
 
-A somewhat formal method exists by which developers commit changes and
+There is a somewhat formal method by which developers commit changes and
 push them into the "contrib" area and subsequently request that the
 maintainer include them into an upstream branch. This process is called
 "submitting a patch" or "submitting a change." For information on
@@ -279,9 +279,9 @@ submitting patches and changes, see the
 ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`"
 section in the Yocto Project Development Tasks Manual.
 
-In summary, a single point of entry exists for changes into a "master"
+In summary, there is a single point of entry for changes into a "master"
 or development branch of the Git repository, which is controlled by the
-project's maintainer. And, a set of developers exist who independently
+project's maintainer. A set of developers independently
 develop, test, and submit changes to "contrib" areas for the maintainer
 to examine. The maintainer then chooses which changes are going to
 become a permanent part of the project.

documentation/overview-manual/yp-intro.rst

@@ -140,8 +140,7 @@ 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
-   difficult to choose how to proceed when varying methods exist by
-   which to accomplish a given task.
+   difficult to choose between such ways.
 
 -  *Understanding What Changes You Need to Make For Your Design Requires
    Some Research:* Beyond the simple tutorial stage, understanding what
@@ -156,7 +155,7 @@ Here are challenges you might encounter when developing using the Yocto Project:
    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
+   In a desktop development environment, there are mechanisms to easily pull
    and install new packages, which are typically pre-compiled binaries
    from servers accessible over the Internet. Using the Yocto Project,
    you must modify your configuration and rebuild to add additional
@@ -249,8 +248,7 @@ accomplish this through a recipe that is a BitBake append
 .. note::
 
    For general information on BSP layer structure, see the
-   :doc:`/bsp-guide/index`
-   .
+   :doc:`/bsp-guide/index`.
 
 The :term:`Source Directory`
 contains both general layers and BSP layers right out of the box. You
@@ -430,8 +428,8 @@ Yocto Project:
    require system administrator privileges. For example, file ownership
    or permissions might need to be defined. Pseudo is a tool that you
    can either use directly or through the environment variable
-   ``LD_PRELOAD``. Either method allows these operations to succeed as
-   if system administrator privileges exist even when they do not.
+   ``LD_PRELOAD``. Either method allows these operations to succeed
+   even without system administrator privileges.
 
    Thanks to Pseudo, the Yocto Project never needs root privileges to
    build images for your target system.
@@ -579,8 +577,7 @@ software.
 This section provides an introduction to the choices or development
 methods you have when setting up your Build Host. Depending on your
 particular workflow preference and the type of operating system your
-Build Host runs, several choices exist that allow you to use the Yocto
-Project.
+Build Host runs, you have several choices.
 
 .. note::
 
@@ -790,7 +787,7 @@ Some Basic Terms
 ================
 
 It helps to understand some basic fundamental terms when learning the
-Yocto Project. Although a list of terms exists in the ":doc:`Yocto Project
+Yocto Project. Although there is a list of terms in the ":doc:`Yocto Project
 Terms </ref-manual/terms>`" section of the Yocto Project
 Reference Manual, this section provides the definitions of some terms
 helpful for getting started:

documentation/poky.yaml

@@ -1,12 +1,12 @@
-DISTRO : "3.3"
+DISTRO : "3.3.1"
 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.3"
+YOCTO_DOC_VERSION : "3.3.1"
 YOCTO_DOC_VERSION_MINUS_ONE : "3.2.4"
-DISTRO_REL_TAG : "yocto-3.3"
-POKYVERSION : "25.0.0"
+DISTRO_REL_TAG : "yocto-3.3.1"
+POKYVERSION : "25.0.1"
 YOCTO_POKY : "poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;"
 YOCTO_DL_URL : "https://downloads.yoctoproject.org"
 YOCTO_AB_URL : "https://autobuilder.yoctoproject.org"
@@ -19,7 +19,8 @@ FEDORA_HOST_PACKAGES_ESSENTIAL : "gawk make wget tar bzip2 gzip python3 unzip pe
      diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \
      ccache perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue perl-bignum socat \
      python3-pexpect findutils which file cpio python python3-pip xz python3-GitPython \
-     python3-jinja2 SDL-devel xterm rpcgen mesa-libGL-devel"
+     python3-jinja2 SDL-devel xterm rpcgen mesa-libGL-devel perl-FindBin perl-File-Compare \
+     perl-File-Copy perl-locale"
 OPENSUSE_HOST_PACKAGES_ESSENTIAL : "python gcc gcc-c++ git chrpath make wget python-xml \
      diffstat makeinfo python-curses patch socat python3 python3-curses tar python3-pip \
      python3-pexpect xz which python3-Jinja2 Mesa-libEGL1 libSDL-devel xterm rpcgen Mesa-dri-devel

documentation/ref-manual/classes.rst

@@ -50,7 +50,7 @@ splitting out of debug symbols during packaging).
    ``do_package_write_*`` tasks to
    have different signatures for the machines with different tunings.
    Additionally, unnecessary rebuilds occur every time an image for a
-   different ``MACHINE`` is built even when the recipe never changes.
+   different :term:`MACHINE` is built even when the recipe never changes.
 
 By default, all recipes inherit the :ref:`base <ref-classes-base>` and
 :ref:`package <ref-classes-package>` classes, which enable
@@ -110,13 +110,13 @@ It's useful to have some idea of how the tasks defined by the
 -  :ref:`ref-tasks-configure` - Regenerates the
    configure script (using ``autoreconf``) and then launches it with a
    standard set of arguments used during cross-compilation. You can pass
-   additional parameters to ``configure`` through the ``EXTRA_OECONF``
+   additional parameters to ``configure`` through the :term:`EXTRA_OECONF`
    or :term:`PACKAGECONFIG_CONFARGS`
    variables.
 
 -  :ref:`ref-tasks-compile` - Runs ``make`` with
    arguments that specify the compiler and linker. You can pass
-   additional arguments through the ``EXTRA_OEMAKE`` variable.
+   additional arguments through the :term:`EXTRA_OEMAKE` variable.
 
 -  :ref:`ref-tasks-install` - Runs ``make install`` and
    passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``.
@@ -168,7 +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``::
+   :term:`S`::
 
            SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
 
@@ -256,7 +256,7 @@ Collecting build statistics is enabled by default through the
 :term:`USER_CLASSES` variable from your
 ``local.conf`` file. Consequently, you do not have to do anything to
 enable the class. However, if you want to disable the class, simply
-remove "buildstats" from the ``USER_CLASSES`` list.
+remove "buildstats" from the :term:`USER_CLASSES` list.
 
 .. _ref-classes-buildstats-summary:
 
@@ -289,21 +289,6 @@ is used during the build process for ``nativesdk``, ``cross``, and
 ``cross-canadian`` recipes to change ``RPATH`` records within binaries
 in order to make them relocatable.
 
-.. _ref-classes-clutter:
-
-``clutter.bbclass``
-===================
-
-The ``clutter`` class consolidates the major and minor version naming
-and other common items used by Clutter and related recipes.
-
-.. note::
-
-   Unlike some other classes related to specific libraries, recipes
-   building other software that uses Clutter do not need to inherit this
-   class unless they use the same recipe versioning scheme that the
-   Clutter and related recipes do.
-
 .. _ref-classes-cmake:
 
 ``cmake.bbclass``
@@ -448,7 +433,7 @@ deployed to :term:`DEPLOYDIR`, and use ``addtask`` to
 add the task at the appropriate place, which is usually after
 :ref:`ref-tasks-compile` or
 :ref:`ref-tasks-install`. The class then takes care of
-staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``.
+staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`.
 
 .. _ref-classes-devshell:
 
@@ -489,7 +474,7 @@ The class
 currently only supports creating a development variant of the target
 recipe, not ``native`` or ``nativesdk`` variants.
 
-The ``BBCLASSEXTEND`` syntax (i.e. ``devupstream:target``) provides
+The :term:`BBCLASSEXTEND` syntax (i.e. ``devupstream:target``) provides
 support for ``native`` and ``nativesdk`` variants. Consequently, this
 functionality can be added in a future release.
 
@@ -534,13 +519,13 @@ and to build it, respectively. When your recipe inherits the
 ``externalsrc`` class, you use the
 :term:`EXTERNALSRC` and
 :term:`EXTERNALSRC_BUILD` variables to
-ultimately define ``S`` and ``B``.
+ultimately define :term:`S` and :term:`B`.
 
 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``)::
+from the recipes. By default, the :term:`B` directory is set to the
+following, which is separate from the source directory (:term:`S`)::
 
    ${WORKDIR}/${BPN}/{PV}/
 
@@ -704,8 +689,8 @@ introspection. This functionality is only enabled if the
 .. note::
 
    This functionality is backfilled by default and, if not applicable,
-   should be disabled through ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` or
-   ``MACHINE_FEATURES_BACKFILL_CONSIDERED``, respectively.
+   should be disabled through :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or
+   :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively.
 
 .. _ref-classes-grub-efi:
 
@@ -853,7 +838,7 @@ using an empty :term:`PARALLEL_MAKE` variable.
 Inheriting the ``icecc`` class changes all sstate signatures.
 Consequently, if a development team has a dedicated build system that
 populates :term:`SSTATE_MIRRORS` and they want to
-reuse sstate from ``SSTATE_MIRRORS``, then all developers and the build
+reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build
 system need to either inherit the ``icecc`` class or nobody should.
 
 At the distribution level, you can inherit the ``icecc`` class to be
@@ -881,10 +866,10 @@ First, the root filesystem is created from packages using one of the
 ``rootfs*.bbclass`` files (depending on the package format used) and
 then one or more image files are created.
 
--  The ``IMAGE_FSTYPES`` variable controls the types of images to
+-  The :term:`IMAGE_FSTYPES` variable controls the types of images to
    generate.
 
--  The ``IMAGE_INSTALL`` variable controls the list of packages to
+-  The :term:`IMAGE_INSTALL` variable controls the list of packages to
    install into the image.
 
 For information on customizing images, see the
@@ -931,7 +916,7 @@ The ``image_types`` class also handles conversion and compression of images.
 .. note::
 
    To build a VMware VMDK image, you need to add "wic.vmdk" to
-   ``IMAGE_FSTYPES``. This would also be similar for Virtual Box Virtual Disk
+   :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk
    Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
 
 .. _ref-classes-image-live:
@@ -947,20 +932,6 @@ specified by :term:`EFI_PROVIDER` if
 Normally, you do not use this class directly. Instead, you add "live" to
 :term:`IMAGE_FSTYPES`.
 
-.. _ref-classes-image-mklibs:
-
-``image-mklibs.bbclass``
-========================
-
-The ``image-mklibs`` class enables the use of the ``mklibs`` utility
-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::
-
-   USER_CLASSES ?= "buildstats image-mklibs image-prelink"
-
 .. _ref-classes-image-prelink:
 
 ``image-prelink.bbclass``
@@ -974,7 +945,7 @@ time.
 By default, the class is enabled in the ``local.conf.template`` using
 the :term:`USER_CLASSES` variable as follows::
 
-   USER_CLASSES ?= "buildstats image-mklibs image-prelink"
+   USER_CLASSES ?= "buildstats image-prelink"
 
 .. _ref-classes-insane:
 
@@ -1006,11 +977,11 @@ package name override, in this example ``${PN}``, must be used::
    INSANE_SKIP_${PN} += "dev-so"
 
 Please keep in mind that the QA checks
-exist in order to detect real or potential problems in the packaged
+are meant to detect real or potential problems in the packaged
 output. So exercise caution when disabling these checks.
 
-Here are the tests you can list with the ``WARN_QA`` and
-``ERROR_QA`` variables:
+Here are the tests you can list with the :term:`WARN_QA` and
+:term:`ERROR_QA` variables:
 
 -  ``already-stripped:`` Checks that produced binaries have not
    already been stripped prior to the build system extracting debug
@@ -1045,7 +1016,7 @@ Here are the tests you can list with the ``WARN_QA`` and
    adds a dependency on the ``initscripts-functions`` package to
    packages that install an initscript that refers to
    ``/etc/init.d/functions``. The recipe should really have an explicit
-   ``RDEPENDS`` for the package in question on ``initscripts-functions``
+   :term:`RDEPENDS` for the package in question on ``initscripts-functions``
    so that the OpenEmbedded build system is able to ensure that the
    ``initscripts`` recipe is actually built and thus the
    ``initscripts-functions`` package is made available.
@@ -1085,8 +1056,8 @@ Here are the tests you can list with the ``WARN_QA`` and
 -  ``dev-so:`` Checks that the ``.so`` symbolic links are in the
    ``-dev`` package and not in any of the other packages. In general,
    these symlinks are only useful for development purposes. Thus, the
-   ``-dev`` package is the correct location for them. Some very rare
-   cases do exist for dynamically loaded modules where these symlinks
+   ``-dev`` package is the correct location for them. In very rare
+   cases, such as dynamically loaded modules, these symlinks
    are needed instead in the main package.
 
 -  ``file-rdeps:`` Checks that file-level dependencies identified by
@@ -1142,13 +1113,13 @@ Here are the tests you can list with the ``WARN_QA`` and
 
       PACKAGECONFIG[foo] = "..."
 
--  ``la:`` Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la``
+-  ``la:`` Checks ``.la`` files for any :term:`TMPDIR` paths. Any ``.la``
    file containing these paths is incorrect since ``libtool`` adds the
    correct sysroot prefix when using the files automatically itself.
 
 -  ``ldflags:`` Ensures that the binaries were linked with the
    :term:`LDFLAGS` options provided by the build system.
-   If this test fails, check that the ``LDFLAGS`` variable is being
+   If this test fails, check that the :term:`LDFLAGS` variable is being
    passed to the linker command.
 
 -  ``libdir:`` Checks for libraries being installed into incorrect
@@ -1188,7 +1159,7 @@ Here are the tests you can list with the ``WARN_QA`` and
    invalid characters (i.e. characters other than 0-9, a-z, ., +, and
    -).
 
--  ``pkgv-undefined:`` Checks to see if the ``PKGV`` variable is
+-  ``pkgv-undefined:`` Checks to see if the :term:`PKGV` variable is
    undefined during :ref:`ref-tasks-package`.
 
 -  ``pkgvarcheck:`` Checks through the variables
@@ -1208,14 +1179,14 @@ Here are the tests you can list with the ``WARN_QA`` and
 -  ``pn-overrides:`` Checks that a recipe does not have a name
    (:term:`PN`) value that appears in
    :term:`OVERRIDES`. If a recipe is named such that
-   its ``PN`` value matches something already in ``OVERRIDES`` (e.g.
-   ``PN`` happens to be the same as :term:`MACHINE` or
+   its :term:`PN` value matches something already in :term:`OVERRIDES` (e.g.
+   :term:`PN` happens to be the same as :term:`MACHINE` or
    :term:`DISTRO`), it can have unexpected consequences.
    For example, assignments such as ``FILES_${PN} = "xyz"`` effectively
    turn into ``FILES = "xyz"``.
 
 -  ``rpaths:`` Checks for rpaths in the binaries that contain build
-   system paths such as ``TMPDIR``. If this test fails, bad ``-rpath``
+   system paths such as :term:`TMPDIR`. If this test fails, bad ``-rpath``
    options are being passed to the linker commands and your binaries
    have potential security issues.
 
@@ -1288,7 +1259,7 @@ themselves.
 
 The ``kernel`` class handles building Linux kernels. The class contains
 code to build all kernel trees. All needed headers are staged into the
-``STAGING_KERNEL_DIR`` directory to allow out-of-tree module builds
+:term:`STAGING_KERNEL_DIR` directory to allow out-of-tree module builds
 using the :ref:`module <ref-classes-module>` class.
 
 This means that each built kernel module is packaged separately and
@@ -1676,7 +1647,7 @@ couple different ways:
            nativesdk-myrecipe.bb
 
 
-   Not doing so can lead to subtle problems because code exists that
+   Not doing so can lead to subtle problems because there is code that
    depends on the naming convention.
 
 Although applied differently, the ``nativesdk`` class is used with both
@@ -1714,10 +1685,10 @@ section in the Yocto Project Development Tasks Manual.
 ``oelint.bbclass``
 ==================
 
-The ``oelint`` class is an obsolete lint checking tool that exists in
+The ``oelint`` class is an obsolete lint checking tool available in
 ``meta/classes`` in the :term:`Source Directory`.
 
-A number of classes exist that could be generally useful in OE-Core but
+There are some classes that could be generally useful in OE-Core but
 are never actually used within OE-Core itself. The ``oelint`` class is
 one such example. However, being aware of this class can reduce the
 proliferation of different versions of similar classes across multiple
@@ -1740,7 +1711,7 @@ To use this class, inherit it globally and specify
    SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
 
 You can specify only a single URL
-in ``SOURCE_MIRROR_URL``.
+in :term:`SOURCE_MIRROR_URL`.
 
 .. _ref-classes-package:
 
@@ -1764,7 +1735,7 @@ package-specific classes:
    use this class.
 
 You can control the list of resulting package formats by using the
-``PACKAGE_CLASSES`` variable defined in your ``conf/local.conf``
+:term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf``
 configuration file, which is located in the :term:`Build Directory`.
 When defining the variable, you can
 specify one or more package types. Since images are generated from
@@ -1785,7 +1756,7 @@ the same or similar package. This comparison takes into account a
 complete build of the package with all dependencies previously built.
 The reason for this discrepancy is because the RPM package manager
 creates and processes more :term:`Metadata` than the IPK package
-manager. Consequently, you might consider setting ``PACKAGE_CLASSES`` to
+manager. Consequently, you might consider setting :term:`PACKAGE_CLASSES` to
 "package_ipk" if you are building smaller systems.
 
 Before making your package manager decision, however, you should
@@ -1867,7 +1838,7 @@ variable in the ``local.conf`` file.
 .. note::
 
    You cannot specify the ``package_tar`` class first using the
-   ``PACKAGE_CLASSES`` variable. You must use ``.deb``, ``.ipk``, or ``.rpm``
+   :term:`PACKAGE_CLASSES` variable. You must use ``.deb``, ``.ipk``, or ``.rpm``
    file formats for your image or SDK.
 
 .. _ref-classes-packagedata:
@@ -1889,7 +1860,7 @@ This class is enabled by default because it is inherited by the
 ========================
 
 The ``packagegroup`` class sets default values appropriate for package
-group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and
+group recipes (e.g. :term:`PACKAGES`, :term:`PACKAGE_ARCH`, :term:`ALLOW_EMPTY`, and
 so forth). It is highly recommended that all package group recipes
 inherit this class.
 
@@ -2208,7 +2179,7 @@ modifying and building source code out of the work directory for a
 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
+or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, which
 can also be set in your ``local.conf`` file. Here is an example::
 
    RM_WORK_EXCLUDE += "busybox glibc"
@@ -2323,11 +2294,11 @@ results so these tests can be skipped over but still make the correct
 values available. The ``meta/site directory`` contains test results
 sorted into different categories such as architecture, endianness, and
 the ``libc`` used. Site information provides a list of files containing
-data relevant to the current build in the ``CONFIG_SITE`` variable that
+data relevant to the current build in the :term:`CONFIG_SITE` variable that
 Autotools automatically picks up.
 
-The class also provides variables like ``SITEINFO_ENDIANNESS`` and
-``SITEINFO_BITS`` that can be used elsewhere in the metadata.
+The class also provides variables like :term:`SITEINFO_ENDIANNESS` and
+:term:`SITEINFO_BITS` that can be used elsewhere in the metadata.
 
 .. _ref-classes-sstate:
 
@@ -2378,7 +2349,7 @@ stages:
    .. note::
 
       Additionally, a recipe can customize the files further by
-      declaring a processing function in the ``SYSROOT_PREPROCESS_FUNCS``
+      declaring a processing function in the :term:`SYSROOT_PREPROCESS_FUNCS`
       variable.
 
    A shared state (sstate) object is built from these files and the
@@ -2420,11 +2391,11 @@ stages:
       recommended for general use, the files do allow some issues such
       as user creation and module indexes to be addressed.
 
-   Because recipes can have other dependencies outside of ``DEPENDS``
+   Because recipes can have other dependencies outside of :term:`DEPENDS`
    (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``),
    the sysroot creation function ``extend_recipe_sysroot`` is also added
    as a pre-function for those tasks whose dependencies are not through
-   ``DEPENDS`` but operate similarly.
+   :term:`DEPENDS` but operate similarly.
 
    When installing dependencies into the sysroot, the code traverses the
    dependency graph and processes dependencies in exactly the same way
@@ -2750,8 +2721,8 @@ initialization script on behalf of the package. The OpenEmbedded build
 system takes care of details such as making sure the script is stopped
 before a package is removed and started when the package is installed.
 
-Three variables control this class: ``INITSCRIPT_PACKAGES``,
-``INITSCRIPT_NAME`` and ``INITSCRIPT_PARAMS``. See the variable links
+Three variables control this class: :term:`INITSCRIPT_PACKAGES`,
+:term:`INITSCRIPT_NAME` and :term:`INITSCRIPT_PARAMS`. See the variable links
 for details.
 
 .. _ref-classes-useradd:
@@ -2805,9 +2776,9 @@ additional information.
 .. note::
 
    You do not use the ``useradd-staticids`` class directly. You either enable
-   or disable the class by setting the ``USERADDEXTENSION`` variable. If you
+   or disable the class by setting the :term:`USERADDEXTENSION` variable. If you
    enable or disable the class in a configured system, :term:`TMPDIR` might
-   contain incorrect ``uid`` and ``gid`` values. Deleting the ``TMPDIR``
+   contain incorrect ``uid`` and ``gid`` values. Deleting the :term:`TMPDIR`
    directory will correct this condition.
 
 .. _ref-classes-utility-tasks:

documentation/ref-manual/devtool-reference.rst

@@ -403,8 +403,8 @@ Upgrading a Recipe
 
 As software matures, upstream recipes are upgraded to newer versions. As
 a developer, you need to keep your local recipes up-to-date with the
-upstream version releases. Several methods exist by which you can
-upgrade recipes. You can read about them in the ":ref:`dev-manual/common-tasks:upgrading recipes`"
+upstream version releases. There are several ways of upgrading recipes.
+You can read about them in the ":ref:`dev-manual/common-tasks:upgrading recipes`"
 section of the Yocto Project Development Tasks Manual. This section
 overviews the ``devtool upgrade`` command.
 
@@ -516,8 +516,8 @@ you do, the package manager is bypassed.
    should never use it to update an image that will be used in
    production.
 
-Some conditions exist that could prevent a deployed application from
-behaving as expected. When both of the following conditions exist, your
+Some conditions could prevent a deployed application from
+behaving as expected. When both of the following conditions are met, your
 application has the potential to not behave correctly when run on the
 target:
 
@@ -528,7 +528,7 @@ target:
 -  The target does not physically have the packages on which the
    application depends installed.
 
-If both of these conditions exist, your application will not behave as
+If both of these conditions are met, your application will not behave as
 expected. The reason for this misbehavior is because the
 ``devtool deploy-target`` command does not deploy the packages (e.g.
 libraries) on which your new application depends. The assumption is that

documentation/ref-manual/faq.rst

@@ -108,10 +108,10 @@ the team can place sources there so builds continue to work.
 but the package is being marked as machine-specific in all cases, how do
 I prevent this?
 
-**A:** Set ``SRC_URI_OVERRIDES_PACKAGE_ARCH`` = "0" in the ``.bb`` file
+**A:** Set :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` = "0" in the ``.bb`` file
 but make sure the package is manually marked as machine-specific for the
 case that needs it. The code that handles
-``SRC_URI_OVERRIDES_PACKAGE_ARCH`` is in the
+:term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` is in the
 ``meta/classes/base.bbclass`` file.
 
 **Q:** I'm behind a firewall and need to use a proxy server. How do I do
@@ -250,7 +250,7 @@ size, you need to set various configurations:
    :term:`IMAGE_ROOTFS_EXTRA_SPACE`
    variable to add additional free space to the image. The build system
    adds this space to the image after it determines its
-   ``IMAGE_ROOTFS_SIZE``.
+   :term:`IMAGE_ROOTFS_SIZE`.
 
 **Q:** Why don't you support directories with spaces in the pathnames?
 
@@ -262,11 +262,11 @@ situation changes, the team will not support spaces in pathnames.
 **Q:** How do I use an external toolchain?
 
 **A:** The toolchain configuration is very flexible and customizable. It
-is primarily controlled with the ``TCMODE`` variable. This variable
+is primarily controlled with the :term:`TCMODE` variable. This variable
 controls which ``tcmode-*.inc`` file to include from the
 ``meta/conf/distro/include`` directory within the :term:`Source Directory`.
 
-The default value of ``TCMODE`` is "default", which tells the
+The default value of :term:`TCMODE` is "default", which tells the
 OpenEmbedded build system to use its internally built toolchain (i.e.
 ``tcmode-default.inc``). However, other patterns are accepted. In
 particular, "external-\*" refers to external toolchains. One example is
@@ -292,7 +292,7 @@ download directory. If that location fails, Poky tries
 :term:`MIRRORS` in that order.
 
 Assuming your distribution is "poky", the OpenEmbedded build system uses
-the Yocto Project source ``PREMIRRORS`` by default for SCM-based
+the Yocto Project source :term:`PREMIRRORS` by default for SCM-based
 sources, upstreams for normal tarballs, and then falls back to a number
 of other mirrors including the Yocto Project source mirror if those
 fail.
@@ -312,7 +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::
+Here are other options::
 
    BB_NO_NETWORK = "1"
 
@@ -325,7 +325,7 @@ Here is another technique::
    BB_FETCH_PREMIRRORONLY = "1"
 
 This statement
-limits the build system to pulling source from the ``PREMIRRORS`` only.
+limits the build system to pulling source from the :term:`PREMIRRORS` only.
 Again, this technique is useful for reproducing builds.
 
 Here is another technique::
@@ -339,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 :term:`PREMIRRORS` server is current::
 
    PREMIRRORS_prepend = "\
        ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
@@ -349,7 +349,7 @@ file as long as the ``PREMIRRORS`` server is current::
 
 These changes would cause the build system to successfully fetch source
 over HTTP and any network accesses to anything other than the
-``PREMIRRORS`` would fail.
+:term:`PREMIRRORS` would fail.
 
 The build system also honors the standard shell environment variables
 ``http_proxy``, ``ftp_proxy``, ``https_proxy``, and ``all_proxy`` to

documentation/ref-manual/features.rst

@@ -10,10 +10,10 @@ can select, and a reference on feature backfilling.
 
 Features provide a mechanism for working out which packages should be
 included in the generated images. Distributions can select which
-features they want to support through the ``DISTRO_FEATURES`` variable,
+features they want to support through the :term:`DISTRO_FEATURES` variable,
 which is set or appended to in a distribution's configuration file such
 as ``poky.conf``, ``poky-tiny.conf``, ``poky-lsb.conf`` and so forth.
-Machine features are set in the ``MACHINE_FEATURES`` variable, which is
+Machine features are set in the :term:`MACHINE_FEATURES` variable, which is
 set in the machine configuration file and specifies the hardware
 features for a given machine.
 
@@ -267,7 +267,7 @@ these valid features is as follows:
 -  *ssh-server-openssh:* Installs the OpenSSH SSH server, which is more
    full-featured than Dropbear. Note that if both the OpenSSH SSH server
    and the Dropbear minimal SSH server are present in
-   ``IMAGE_FEATURES``, then OpenSSH will take precedence and Dropbear
+   :term:`IMAGE_FEATURES`, then OpenSSH will take precedence and Dropbear
    will not be installed.
 
 -  *tools-debug:* Installs debugging tools such as ``strace`` and
@@ -323,27 +323,27 @@ Here are two examples to help illustrate feature backfilling:
 -  *The "pulseaudio" distro feature option*: Previously, PulseAudio
    support was enabled within the Qt and GStreamer frameworks. Because
    of this, the feature is backfilled and thus enabled for all distros
-   through the ``DISTRO_FEATURES_BACKFILL`` variable in the
+   through the :term:`DISTRO_FEATURES_BACKFILL` variable in the
    ``meta/conf/bitbake.conf`` file. However, your distro needs to
    disable the feature. You can disable the feature without affecting
    other existing distro configurations that need PulseAudio support by
-   adding "pulseaudio" to ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` in
+   adding "pulseaudio" to :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` in
    your distro's ``.conf`` file. Adding the feature to this variable
-   when it also exists in the ``DISTRO_FEATURES_BACKFILL`` variable
+   when it also exists in the :term:`DISTRO_FEATURES_BACKFILL` variable
    prevents the build system from adding the feature to your
-   configuration's ``DISTRO_FEATURES``, effectively disabling the
+   configuration's :term:`DISTRO_FEATURES`, effectively disabling the
    feature for that particular distro.
 
 -  *The "rtc" machine feature option*: Previously, real time clock (RTC)
    support was enabled for all target devices. Because of this, the
    feature is backfilled and thus enabled for all machines through the
-   ``MACHINE_FEATURES_BACKFILL`` variable in the
+   :term:`MACHINE_FEATURES_BACKFILL` variable in the
    ``meta/conf/bitbake.conf`` file. However, your target device does not
    have this capability. You can disable RTC support for your device
    without affecting other machines that need RTC support by adding the
-   feature to your machine's ``MACHINE_FEATURES_BACKFILL_CONSIDERED``
+   feature to your machine's :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`
    list in the machine's ``.conf`` file. Adding the feature to this
-   variable when it also exists in the ``MACHINE_FEATURES_BACKFILL``
+   variable when it also exists in the :term:`MACHINE_FEATURES_BACKFILL`
    variable prevents the build system from adding the feature to your
-   configuration's ``MACHINE_FEATURES``, effectively disabling RTC
+   configuration's :term:`MACHINE_FEATURES`, effectively disabling RTC
    support for that particular machine.

documentation/ref-manual/images.rst

@@ -46,10 +46,6 @@ Following is a list of supported recipes:
 -  ``core-image-base``: A console-only image that fully supports the
    target device hardware.
 
--  ``core-image-clutter``: An image with support for the Open GL-based
-   toolkit Clutter, which enables development of rich and animated
-   graphical user interfaces.
-
 -  ``core-image-full-cmdline``: A console-only image with more
    full-featured Linux system functionality installed.
 

documentation/ref-manual/index.rst

@@ -13,7 +13,6 @@ Yocto Project Reference Manual
    system-requirements
    terms
    release-process
-   migration
    structure
    classes
    tasks

documentation/ref-manual/kickstart.rst

@@ -106,13 +106,15 @@ the ``part`` and ``partition`` commands:
 -  ``--fstype``: Sets the file system type for the partition. Valid
    values are:
 
-   -  ``ext4``
+   -  ``btrfs``
 
-   -  ``ext3``
+   -  ``erofs``
 
    -  ``ext2``
 
-   -  ``btrfs``
+   -  ``ext3``
+
+   -  ``ext4``
 
    -  ``squashfs``
 
@@ -206,9 +208,9 @@ supports the following options:
    bootloader times out and boots the default option.
 
 -  ``--append``: Specifies kernel parameters. These parameters will be
-   added to the syslinux ``APPEND`` or ``grub`` kernel command line.
+   added to the syslinux :term:`APPEND` or ``grub`` kernel command line.
 
 -  ``--configfile``: Specifies a user-defined configuration file for
    the bootloader. You can provide a full pathname for the file or a
-   file that exists in the ``canned-wks`` folder. This option overrides
+   file located in the ``canned-wks`` folder. This option overrides
    all other bootloader options.

documentation/ref-manual/qa-checks.rst

@@ -88,7 +88,7 @@ Errors and Warnings
    A file-level dependency has been identified from the specified
    package on the specified files, but there is no explicit
    corresponding entry in :term:`RDEPENDS`. If
-   particular files are required at runtime then ``RDEPENDS`` should be
+   particular files are required at runtime then :term:`RDEPENDS` should be
    declared in the recipe to ensure the packages providing them are
    built.
 
@@ -97,14 +97,14 @@ Errors and Warnings
 
 -  ``<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]``
 
-   A runtime dependency exists between the two specified packages, but
+   There is a runtime dependency between the two specified packages, but
    there is nothing explicit within the recipe to enable the
    OpenEmbedded build system to ensure that dependency is satisfied.
    This condition is usually triggered by an
    :term:`RDEPENDS` value being added at the packaging
    stage rather than up front, which is usually automatic based on the
    contents of the package. In most cases, you should change the recipe
-   to add an explicit ``RDEPENDS`` for the dependency.
+   to add an explicit :term:`RDEPENDS` for the dependency.
 
     
 .. _qa-check-dev-so:
@@ -152,7 +152,7 @@ Errors and Warnings
    not explicitly add the ``.debug`` directory to the ``-dbg`` package.
    If this is the case, add the ``.debug`` directory explicitly to
    ``FILES_${PN}-dbg``. See :term:`FILES` for additional
-   information on ``FILES``.
+   information on :term:`FILES`.
 
     
 .. _qa-check-arch:
@@ -235,9 +235,9 @@ Errors and Warnings
 
    This indicates that binaries produced when building the recipe have
    not been linked with the :term:`LDFLAGS` options
-   provided by the build system. Check to be sure that the ``LDFLAGS``
+   provided by the build system. Check to be sure that the :term:`LDFLAGS`
    variable is being passed to the linker command. A common workaround
-   for this situation is to pass in ``LDFLAGS`` using
+   for this situation is to pass in :term:`LDFLAGS` using
    :term:`TARGET_CC_ARCH` within the recipe as
    follows::
 
@@ -303,7 +303,7 @@ Errors and Warnings
 
 -  ``<packagename> rdepends on <debug_packagename> [debug-deps]``
 
-   A dependency exists between the specified non-dbg package (i.e. a
+   There is a dependency between the specified non-dbg package (i.e. a
    package whose name does not end in ``-dbg``) and a package that is a
    ``dbg`` package. The ``dbg`` packages contain debug symbols and are
    brought in using several different methods:
@@ -326,7 +326,7 @@ Errors and Warnings
 
 -  ``<packagename> rdepends on <dev_packagename> [dev-deps]``
 
-   A dependency exists between the specified non-dev package (a package
+   There is a dependency between the specified non-dev package (a package
    whose name does not end in ``-dev``) and a package that is a ``dev``
    package. The ``dev`` packages contain development headers and are
    usually brought in using several different methods:
@@ -403,7 +403,7 @@ Errors and Warnings
    If your recipe name does not match this, or you add packages to
    :term:`PACKAGES` that do not conform to the
    convention, then you will receive this error. Rename your recipe. Or,
-   if you have added a non-conforming package name to ``PACKAGES``,
+   if you have added a non-conforming package name to :term:`PACKAGES`,
    change the package name appropriately.
 
     
@@ -431,13 +431,13 @@ Errors and Warnings
 
    The specified recipe has a name (:term:`PN`) value that
    appears in :term:`OVERRIDES`. If a recipe is named
-   such that its ``PN`` value matches something already in ``OVERRIDES``
-   (e.g. ``PN`` happens to be the same as :term:`MACHINE`
+   such that its :term:`PN` value matches something already in :term:`OVERRIDES`
+   (e.g. :term:`PN` happens to be the same as :term:`MACHINE`
    or :term:`DISTRO`), it can have unexpected
    consequences. For example, assignments such as
    ``FILES_${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``.
-   Rename your recipe (or if ``PN`` is being set explicitly, change the
-   ``PN`` value) so that the conflict does not occur. See
+   Rename your recipe (or if :term:`PN` is being set explicitly, change the
+   :term:`PN` value) so that the conflict does not occur. See
    :term:`FILES` for additional information.
 
     
@@ -464,7 +464,7 @@ Errors and Warnings
    This check looks for instances of setting ``DEPENDS_${PN}``
    which is erroneous (:term:`DEPENDS` is a recipe-wide variable and thus
    it is not correct to specify it for a particular package, nor will such
-   an assignment actually work.) Set ``DEPENDS`` instead.
+   an assignment actually work.) Set :term:`DEPENDS` instead.
 
 
 .. _qa-check-already-stripped:
@@ -499,7 +499,7 @@ Errors and Warnings
 
    Package names must appear only once in the
    :term:`PACKAGES` variable. You might receive this
-   error if you are attempting to add a package to ``PACKAGES`` that is
+   error if you are attempting to add a package to :term:`PACKAGES` that is
    already in the variable's value.
 
     
@@ -523,7 +523,7 @@ Errors and Warnings
    in an image later on in the build process. You need to do one of the
    following:
 
-   -  Add the files to ``FILES`` for the package you want them to appear
+   -  Add the files to :term:`FILES` for the package you want them to appear
       in (e.g. ``FILES_${``\ :term:`PN`\ ``}`` for the main
       package).
 
@@ -604,7 +604,7 @@ Errors and Warnings
     so using ${:term:`BPN`} rather than ${:term:`PN`} as the latter will change
     for different variants of the same recipe e.g. when :term:`BBCLASSEXTEND`
     or multilib are being used. This check will fail if a reference to ``${PN}``
-    is found within the ``SRC_URI`` value - change it to ``${BPN}`` instead.
+    is found within the :term:`SRC_URI` value - change it to ``${BPN}`` instead.
 
 
 .. _qa-check-unhandled-features-check:
@@ -753,6 +753,6 @@ how to work with the QA checks, see the
 
 .. note::
 
-   Please keep in mind that the QA checks exist in order to detect real
+   Please keep in mind that the QA checks are meant to detect real
    or potential problems in the packaged output. So exercise caution
    when disabling these checks.

documentation/ref-manual/release-process.rst

@@ -62,8 +62,10 @@ codename are likely to be compatible and thus work together.
 
 Releases are given a nominal release version as well but the codename is
 used in repositories for this reason. You can find information on Yocto
-Project releases and codenames at
-:yocto_wiki:`/Releases`.
+Project releases and codenames at :yocto_wiki:`/Releases`.
+
+Our :doc:`/migration-guides/index` detail how to migrate from one release of
+the Yocto Project to the next.
 
 Stable Release Process
 ======================
@@ -82,14 +84,14 @@ stable release.
    bug fixes and security fixes only. Policy dictates that features are
    not backported to a stable release. This policy means generic recipe
    version upgrades are unlikely to be accepted for backporting. The
-   exception to this policy occurs when a strong reason exists such as
+   exception to this policy occurs when there is a strong reason such as
    the fix happens to also be the preferred upstream approach.
 
 Stable release branches have strong maintenance for about a year after
 their initial release. Should significant issues be found for any
 release regardless of its age, fixes could be backported to older
 releases. For issues that are not backported given an older release,
-Community LTS trees and branches exist where community members share
+Community LTS trees and branches allow community members to share
 patches for older releases. However, these types of patches do not go
 through the same release process as do point releases. You can find more
 information about stable branch maintenance at
@@ -164,9 +166,8 @@ repository.
 
 .. note::
 
-   You can find all these branches in the Yocto Project
-   Source Repositories
-   .
+   You can find all these branches in the
+   :ref:`overview-manual/development-environment:yocto project source repositories`.
 
 Testing within these public branches ensures in a publicly visible way
 that all of the main supposed architectures and recipes in OE-Core

documentation/ref-manual/resources.rst

@@ -10,7 +10,7 @@ Introduction
 ============
 
 The Yocto Project team is happy for people to experiment with the Yocto
-Project. A number of places exist to find help if you run into
+Project. There is a number of places where you can find help if you run into
 difficulties or find bugs. This presents information about contributing
 and participating in the Yocto Project.
 
@@ -43,8 +43,7 @@ the Yocto Project itself (e.g. when discovering an issue with some
 component of the build system that acts contrary to the documentation or
 your expectations).
 
-A general procedure and guidelines exist for when you use Bugzilla to
-submit a bug. For information on how to use Bugzilla to submit a bug
+For a general procedure and guidelines on how to use Bugzilla to submit a bug
 against the Yocto Project, see the following:
 
 -  The ":ref:`dev-manual/common-tasks:submitting a defect against the yocto project`"
@@ -59,7 +58,7 @@ For information on Bugzilla in general, see https://www.bugzilla.org/about/.
 Mailing lists
 =============
 
-A number of mailing lists maintained by the Yocto Project exist as well
+There are multiple mailing lists maintained by the Yocto Project as well
 as related OpenEmbedded mailing lists for discussion, patch submission
 and announcements. To subscribe to one of the following mailing lists,
 click on the appropriate URL in the following list and follow the
@@ -156,9 +155,8 @@ Here is a list of resources you might find helpful:
 
 -  :yocto_docs:`Yocto Project Mega-Manual </singleindex.html>`\ *:* This manual
    is simply a single HTML file comprised of the bulk of the Yocto
-   Project manuals. The Mega-Manual primarily exists as a vehicle by
-   which you can easily search for phrases and terms used in the Yocto
-   Project documentation set.
+   Project manuals. It makes it easy to search for phrases and terms used
+   in the Yocto Project documentation set.
 
 -  :doc:`/profile-manual/index` *:* This manual presents a set of
    common and generally useful tracing and profiling schemes along with

documentation/ref-manual/structure.rst

@@ -251,9 +251,9 @@ variables are hard-coded for various reasons but such variables are
 relatively rare.
 
 At a minimum, you would normally edit this file to select the target
-``MACHINE``, which package types you wish to use
+:term:`MACHINE`, which package types you wish to use
 (:term:`PACKAGE_CLASSES`), and the location from
-which you want to access downloaded files (``DL_DIR``).
+which you want to access downloaded files (:term:`DL_DIR`).
 
 If ``local.conf`` is not present when you start the build, the
 OpenEmbedded build system creates it from ``local.conf.sample`` when you
@@ -336,7 +336,7 @@ the build.
 This directory contains downloaded upstream source tarballs. You can
 reuse the directory for multiple builds or move the directory to another
 location. You can control the location of this directory through the
-``DL_DIR`` variable.
+:term:`DL_DIR` variable.
 
 .. _structure-build-sstate-cache:
 
@@ -346,7 +346,7 @@ location. You can control the location of this directory through the
 This directory contains the shared state cache. You can reuse the
 directory for multiple builds or move the directory to another location.
 You can control the location of this directory through the
-``SSTATE_DIR`` variable.
+:term:`SSTATE_DIR` variable.
 
 .. _structure-build-tmp:
 
@@ -510,8 +510,8 @@ should be automatic, and recipes should not directly reference
 -----------------------
 
 Previous versions of the OpenEmbedded build system used to create a
-global shared sysroot per machine along with a native sysroot. Beginning
-with the 2.3 version of the Yocto Project, sysroots exist in
+global shared sysroot per machine along with a native sysroot. Since
+the 2.3 version of the Yocto Project, there are sysroots in
 recipe-specific :term:`WORKDIR` directories. Thus, the
 ``build/tmp/sysroots/`` directory is unused.
 
@@ -548,7 +548,7 @@ section in the Yocto Project Overview and Concepts Manual.
 ------------------
 
 This directory contains general logs that are not otherwise placed using
-the package's ``WORKDIR``. Examples of logs are the output from the
+the package's :term:`WORKDIR`. Examples of logs are the output from the
 ``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not
 necessarily mean this directory is created.
 
@@ -569,7 +569,7 @@ It is worth considering the structure of a typical work directory. As an
 example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86``
 built within the Yocto Project. For this package, a work directory of
 ``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred
-to as the ``WORKDIR``, is created. Within this directory, the source is
+to as the :term:`WORKDIR`, is created. Within this directory, the source is
 unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt.
 (See the ":ref:`dev-manual/common-tasks:using quilt in your workflow`" section in
 the Yocto Project Development Tasks Manual for more information.) Within
@@ -577,7 +577,7 @@ the ``linux-qemux86-standard-build`` directory, standard Quilt
 directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and
 standard Quilt commands can be used.
 
-There are other directories generated within ``WORKDIR``. The most
+There are other directories generated within :term:`WORKDIR`. The most
 important directory is ``WORKDIR/temp/``, which has log files for each
 task (``log.do_*.pid``) and contains the scripts BitBake runs for each
 task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make
@@ -601,7 +601,7 @@ constructed using the architecture of the given build (e.g.
 name, and the version of the recipe (i.e.
 :term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`).
 
-A number of key subdirectories exist within each recipe work directory:
+Here are key subdirectories within each recipe work directory:
 
 -  ``${WORKDIR}/temp``: Contains the log files of each task executed for
    this recipe, the "run" files for each executed task, which contain
@@ -624,7 +624,7 @@ A number of key subdirectories exist within each recipe work directory:
 
 -  ``${WORKDIR}/packages-split``: Contains the output of the
    ``do_package`` task after the output has been split into individual
-   packages. Subdirectories exist for each individual package created by
+   packages. There are subdirectories for each individual package created by
    the recipe.
 
 -  ``${WORKDIR}/recipe-sysroot``: A directory populated with the target
@@ -709,7 +709,7 @@ support for a new machine to the Yocto Project, look in this directory.
 
 The contents of this directory controls any distribution-specific
 configurations. For the Yocto Project, the ``defaultsetup.conf`` is the
-main file here. This directory includes the versions and the ``SRCDATE``
+main file here. This directory includes the versions and the :term:`SRCDATE`
 definitions for applications that are configured here. An example of an
 alternative configuration might be ``poky-bleeding.conf``. Although this
 file mainly inherits its configuration from Poky.

documentation/ref-manual/system-requirements.rst

@@ -41,7 +41,7 @@ distributions:
 
 -  Ubuntu 18.04 (LTS)
 
--  Ubuntu 20.04
+-  Ubuntu 20.04 (LTS)
 
 -  Fedora 30
 
@@ -66,9 +66,8 @@ distributions:
 
    -  While the Yocto Project Team attempts to ensure all Yocto Project
       releases are one hundred percent compatible with each officially
-      supported Linux distribution, instances might exist where you
-      encounter a problem while using the Yocto Project on a specific
-      distribution.
+      supported Linux distribution, you may still encounter problems
+      that happen only with a specific distribution.
 
    -  Yocto Project releases are tested against the stable Linux
       distributions in the above list. The Yocto Project should work
@@ -119,8 +118,7 @@ supported Ubuntu or Debian Linux distribution:
    -  If your build system has the ``oss4-dev`` package installed, you
       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::
+      system. If you run into this situation, try either of these solutions::
 
          $ sudo apt-get build-dep qemu
          $ sudo apt-get remove oss4-dev

documentation/ref-manual/tasks.rst

@@ -57,7 +57,7 @@ the current working directory set to ``${``\ :term:`B`\ ``}``.
 The default behavior of this task is to run ``oe_runmake clean`` if a
 makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found and
 :term:`CLEANBROKEN` is not set to "1". If no such
-file is found or the ``CLEANBROKEN`` variable is set to "1", the
+file is found or the :term:`CLEANBROKEN` variable is set to "1", the
 ``do_configure`` task does nothing.
 
 .. _ref-tasks-configure_ptest_base:
@@ -308,17 +308,17 @@ This recipe has two patch files located here::
 
    poky/meta/recipes-connectivity/bluez5/bluez5
 
-In the ``bluez5`` recipe, the ``SRC_URI`` statements point to the source
+In the ``bluez5`` recipe, the :term:`SRC_URI` statements point to the source
 and patch files needed to build the package.
 
 .. note::
 
-   In the case for the ``bluez5_5.48.bb`` recipe, the ``SRC_URI`` statements
+   In the case for the ``bluez5_5.48.bb`` recipe, the :term:`SRC_URI` statements
    are from an include file ``bluez5.inc``.
 
 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
+"apply=yes" parameter with the :term:`SRC_URI` statement to indicate any
 file as a patch file::
 
    SRC_URI = " \
@@ -329,7 +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::
+:term:`SRC_URI` statement::
 
    SRC_URI = " \
        git://path_to_repo/some_package \
@@ -430,7 +430,7 @@ variable also plays a role in where unpacked source files ultimately
 reside. For more information on how source files are unpacked, see the
 ":ref:`overview-manual/concepts:source fetching`"
 section in the Yocto Project Overview and Concepts Manual and also see
-the ``WORKDIR`` and ``S`` variable descriptions.
+the :term:`WORKDIR` and :term:`S` variable descriptions.
 
 Manually Called Tasks
 =====================
@@ -823,6 +823,5 @@ sections from a size-sensitive configuration.
 After the kernel is unpacked but before it is patched, this task makes
 sure that the machine and metadata branches as specified by the
 :term:`SRCREV` variables actually exist on the specified
-branches. If these branches do not exist and
-:term:`AUTOREV` is not being used, the
+branches. Otherwise, if :term:`AUTOREV` is not being used, the
 ``do_validate_branches`` task fails during the build.

documentation/ref-manual/terms.rst

@@ -97,11 +97,11 @@ universal, the list includes them just in case:
       .. note::
 
          By default, the Build Directory contains :term:`TMPDIR`, which is a
-         temporary directory the build system uses for its work. ``TMPDIR`` cannot
+         temporary directory the build system uses for its work. :term:`TMPDIR` cannot
          be under NFS. Thus, by default, the Build Directory cannot be under
          NFS. However, if you need the Build Directory to be under NFS, you can
-         set this up by setting ``TMPDIR`` in your ``local.conf`` file to use a local
-         drive. Doing so effectively separates ``TMPDIR`` from :term:`TOPDIR`, which is the
+         set this up by setting :term:`TMPDIR` in your ``local.conf`` file to use a local
+         drive. Doing so effectively separates :term:`TMPDIR` from :term:`TOPDIR`, which is the
          Build Directory.
 
    :term:`Build Host`

documentation/releases.rst

@@ -1,17 +1,18 @@
 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
 
-=========================
- Current Release Manuals
-=========================
+===========================
+ Supported Release Manuals
+===========================
 
-*******************************
-3.3 'hardknott' Release Series
-*******************************
+******************************
+Release Series 3.3 (hardknott)
+******************************
 
 - :yocto_docs:`3.3 Documentation </3.3>`
+- :yocto_docs:`3.3.1 Documentation </3.3.1>`
 
 *******************************
-3.2 'gatesgarth' Release Series
+Release Series 3.2 (gatesgarth)
 *******************************
 
 - :yocto_docs:`3.2 Documentation </3.2>`
@@ -21,7 +22,7 @@
 - :yocto_docs:`3.2.4 Documentation </3.2.4>`
 
 ****************************
-3.1 'dunfell' Release Series
+Release Series 3.1 (dunfell)
 ****************************
 
 - :yocto_docs:`3.1 Documentation </3.1>`
@@ -32,13 +33,15 @@
 - :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>`
+- :yocto_docs:`3.1.8 Documentation </3.1.8>`
+- :yocto_docs:`3.1.8 Documentation </3.1.9>`
 
 ==========================
- Previous Release Manuals
+ Outdated Release Manuals
 ==========================
 
 *************************
-3.0 'zeus' Release Series
+Release Series 3.0 (zeus)
 *************************
 
 - :yocto_docs:`3.0 Documentation </3.0>`
@@ -48,7 +51,7 @@
 - :yocto_docs:`3.0.4 Documentation </3.0.4>`
 
 ****************************
-2.7 'warrior' Release Series
+Release Series 2.7 (warrior)
 ****************************
 
 - :yocto_docs:`2.7 Documentation </2.7>`
@@ -58,7 +61,7 @@
 - :yocto_docs:`2.7.4 Documentation </2.7.4>`
 
 *************************
-2.6 'thud' Release Series
+Release Series 2.6 (thud)
 *************************
 
 - :yocto_docs:`2.6 Documentation </2.6>`
@@ -68,16 +71,16 @@
 - :yocto_docs:`2.6.4 Documentation </2.6.4>`
 
 *************************
-2.5 'sumo' Release Series
+Release Series 2.5 (sumo)
 *************************
 
 - :yocto_docs:`2.5 Documentation </2.5>`
 - :yocto_docs:`2.5.1 Documentation </2.5.1>`
 - :yocto_docs:`2.5.2 Documentation </2.5.2>`
 - :yocto_docs:`2.5.3 Documentation </2.5.3>`
- 
+
 **************************
-2.4 'rocko' Release Series
+Release Series 2.4 (rocko)
 **************************
 
 - :yocto_docs:`2.4 Documentation </2.4>`
@@ -87,7 +90,7 @@
 - :yocto_docs:`2.4.4 Documentation </2.4.4>`
 
 *************************
-2.3 'pyro' Release Series
+Release Series 2.3 (pyro)
 *************************
 
 - :yocto_docs:`2.3 Documentation </2.3>`
@@ -97,7 +100,7 @@
 - :yocto_docs:`2.3.4 Documentation </2.3.4>`
 
 **************************
-2.2 'morty' Release Series
+Release Series 2.2 (morty)
 **************************
 
 - :yocto_docs:`2.2 Documentation </2.2>`
@@ -106,7 +109,7 @@
 - :yocto_docs:`2.2.3 Documentation </2.2.3>`
 
 ****************************
-2.1 'krogoth' Release Series
+Release Series 2.1 (krogoth)
 ****************************
 
 - :yocto_docs:`2.1 Documentation </2.1>`
@@ -115,7 +118,7 @@
 - :yocto_docs:`2.1.3 Documentation </2.1.3>`
 
 ***************************
-2.0 'jethro' Release Series
+Release Series 2.0 (jethro)
 ***************************
 
 - :yocto_docs:`1.9 Documentation </1.9>`
@@ -125,7 +128,7 @@
 - :yocto_docs:`2.0.3 Documentation </2.0.3>`
 
 *************************
-1.8 'fido' Release Series
+Release Series 1.8 (fido)
 *************************
 
 - :yocto_docs:`1.8 Documentation </1.8>`
@@ -133,7 +136,7 @@
 - :yocto_docs:`1.8.2 Documentation </1.8.2>`
 
 **************************
-1.7 'dizzy' Release Series
+Release Series 1.7 (dizzy)
 **************************
 
 - :yocto_docs:`1.7 Documentation </1.7>`
@@ -142,16 +145,16 @@
 - :yocto_docs:`1.7.3 Documentation </1.7.3>`
 
 **************************
-1.6 'daisy' Release Series
+Release Series 1.6 (daisy)
 **************************
 
 - :yocto_docs:`1.6 Documentation </1.6>`
 - :yocto_docs:`1.6.1 Documentation </1.6.1>`
 - :yocto_docs:`1.6.2 Documentation </1.6.2>`
 - :yocto_docs:`1.6.3 Documentation </1.6.3>`
- 
+
 *************************
-1.5 'dora' Release Series
+Release Series 1.5 (dora)
 *************************
 
 - :yocto_docs:`1.5 Documentation </1.5>`
@@ -161,7 +164,7 @@
 - :yocto_docs:`1.5.4 Documentation </1.5.4>`
 
 **************************
-1.4 'dylan' Release Series
+Release Series 1.4 (dylan)
 **************************
 
 - :yocto_docs:`1.4 Documentation </1.4>`
@@ -170,9 +173,9 @@
 - :yocto_docs:`1.4.3 Documentation </1.4.3>`
 - :yocto_docs:`1.4.4 Documentation </1.4.4>`
 - :yocto_docs:`1.4.5 Documentation </1.4.5>`
- 
+
 **************************
-1.3 'danny' Release Series
+Release Series 1.3 (danny)
 **************************
 
 - :yocto_docs:`1.3 Documentation </1.3>`
@@ -180,7 +183,7 @@
 - :yocto_docs:`1.3.2 Documentation </1.3.2>`
 
 ***************************
-1.2 'denzil' Release Series
+Release Series 1.2 (denzil)
 ***************************
 
 - :yocto_docs:`1.2 Documentation </1.2>`
@@ -188,7 +191,7 @@
 - :yocto_docs:`1.2.2 Documentation </1.2.2>`
 
 ***************************
-1.1 'edison' Release Series
+Release Series 1.1 (edison)
 ***************************
 
 - :yocto_docs:`1.1 Documentation </1.1>`
@@ -196,7 +199,7 @@
 - :yocto_docs:`1.1.2 Documentation </1.1.2>`
 
 ****************************
-1.0 'bernard' Release Series
+Release Series 1.0 (bernard)
 ****************************
 
 - :yocto_docs:`1.0 Documentation </1.0>`
@@ -204,7 +207,7 @@
 - :yocto_docs:`1.0.2 Documentation </1.0.2>`
 
 ****************************
-0.9 'laverne' Release Series
+Release Series 0.9 (laverne)
 ****************************
 
 - :yocto_docs:`0.9 Documentation </0.9>`

documentation/sdk-manual/appendix-customizing-standard.rst

@@ -17,10 +17,10 @@ and
 variables control the set of packages adding to the SDK.
 
 If you want to add individual packages to the toolchain that runs on the
-host, simply add those packages to the ``TOOLCHAIN_HOST_TASK`` variable.
+host, simply add those packages to the :term:`TOOLCHAIN_HOST_TASK` variable.
 Similarly, if you want to add packages to the default set that is part
 of the toolchain that runs on the target, add the packages to the
-``TOOLCHAIN_TARGET_TASK`` variable.
+:term:`TOOLCHAIN_TARGET_TASK` variable.
 
 Adding API Documentation to the Standard SDK
 ============================================

documentation/sdk-manual/appendix-customizing.rst

@@ -35,13 +35,13 @@ build system applies them against ``local.conf`` and ``auto.conf``:
 -  Variables listed in
    :term:`SDK_LOCAL_CONF_WHITELIST`
    are included. Including a variable in the value of
-   ``SDK_LOCAL_CONF_WHITELIST`` overrides either of the previous two
+   :term:`SDK_LOCAL_CONF_WHITELIST` overrides either of the previous two
    filters. The default value is blank.
 
 -  Classes inherited globally with
    :term:`INHERIT` that are listed in
    :term:`SDK_INHERIT_BLACKLIST`
-   are disabled. Using ``SDK_INHERIT_BLACKLIST`` to disable these
+   are disabled. Using :term:`SDK_INHERIT_BLACKLIST` to disable these
    classes is the typical method to disable classes that are problematic
    or unnecessary in the SDK context. The default value blacklists the
    :ref:`buildhistory <ref-classes-buildhistory>`
@@ -57,8 +57,7 @@ Adjusting the Extensible SDK to Suit Your Build Host's Setup
 ============================================================
 
 In most cases, the extensible SDK defaults should work with your :term:`Build
-Host`'s setup.
-However, some cases exist for which you might consider making
+Host`'s setup. However, there are cases when you might consider making
 adjustments:
 
 -  If your SDK configuration inherits additional classes using the
@@ -75,11 +74,9 @@ adjustments:
       is set using the "?=" operator. Consequently, you will need to
       either define the entire list by using the "=" operator, or you
       will need to append a value using either "_append" or the "+="
-      operator. You can learn more about these operators in the "
-      Basic Syntax
-      " section of the BitBake User Manual.
-
-   .
+      operator. You can learn more about these operators in the
+      ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`"
+      section of the BitBake User Manual.
 
 -  If you have classes or recipes that add additional tasks to the
    standard build flow (i.e. the tasks execute as the recipe builds as
@@ -96,7 +93,7 @@ adjustments:
 
    -  Disable the tasks if they are added by a class and you do not need
       the functionality the class provides in the extensible SDK. To
-      disable the tasks, add the class to the ``SDK_INHERIT_BLACKLIST``
+      disable the tasks, add the class to the :term:`SDK_INHERIT_BLACKLIST`
       variable as described in the previous section.
 
 -  Generally, you want to have a shared state mirror set up so users of
@@ -129,8 +126,7 @@ adjustments:
    .. note::
 
       You must also reflect this change in the value used for the
-      COREBASE_FILES
-      variable as previously described.
+      :term:`COREBASE_FILES` variable as previously described.
 
 Changing the Extensible SDK Installer Title
 ===========================================
@@ -143,23 +139,23 @@ section.
 
 By default, this title is derived from
 :term:`DISTRO_NAME` when it is
-set. If the ``DISTRO_NAME`` variable is not set, the title is derived
+set. If the :term:`DISTRO_NAME` variable is not set, the title is derived
 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
+class defines the default value of the :term:`SDK_TITLE` variable as
 follows::
 
    SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
 
-While several ways exist to change this variable, an efficient method is
+While there are several ways of changing this variable, an efficient method is
 to set the variable in your distribution's configuration file. Doing so
 creates an SDK installer title that applies across your distribution. As
 an example, assume you have your own layer for your distribution named
 "meta-mydistro" and you are using the same type of file hierarchy as
 does the default "poky" distribution. If so, you could update the
-``SDK_TITLE`` variable in the
+:term:`SDK_TITLE` variable in the
 ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
 form::
 
@@ -221,16 +217,16 @@ class as follows::
 
 You can
 change this default installation directory by specifically setting the
-``SDKEXTPATH`` variable.
+:term:`SDKEXTPATH` variable.
 
-While a number of ways exist through which you can set this variable,
+While there are several ways of setting this variable,
 the method that makes the most sense is to set the variable in your
 distribution's configuration file. Doing so creates an SDK installer
 default directory that applies across your distribution. As an example,
 assume you have your own layer for your distribution named
 "meta-mydistro" and you are using the same type of file hierarchy as
 does the default "poky" distribution. If so, you could update the
-``SDKEXTPATH`` variable in the
+:term:`SDKEXTPATH` variable in the
 ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
 form::
 
@@ -271,8 +267,7 @@ source, you need to do a number of things:
 
       SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH"
 
-   You can set the
-   ``SSTATE_MIRRORS`` variable in two different places:
+   You can set the :term:`SSTATE_MIRRORS` variable in two different places:
 
    -  If the mirror value you are setting is appropriate to be set for
       both the OpenEmbedded build system that is actually building the
@@ -285,18 +280,17 @@ source, you need to do a number of things:
 
          SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
 
-   -  Alternatively, if you just want to set the ``SSTATE_MIRRORS``
+   -  Alternatively, if you just want to set the :term:`SSTATE_MIRRORS`
       variable's value for the SDK alone, create a
       ``conf/sdk-extra.conf`` file either in your
       :term:`Build Directory` or within any
-      layer and put your ``SSTATE_MIRRORS`` setting within that file.
+      layer and put your :term:`SSTATE_MIRRORS` setting within that file.
 
       .. note::
 
          This second option is the safest option should you have any
          doubts as to which method to use when setting
-         SSTATE_MIRRORS
-         .
+         :term:`SSTATE_MIRRORS`
 
 Minimizing the Size of the Extensible SDK Installer Download
 ============================================================
@@ -334,7 +328,7 @@ following::
 
 See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information.
 
-Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world"
+Setting the :term:`SDK_INCLUDE_PKGDATA` variable as shown causes the "world"
 target to be built so that information for all of the recipes included
 within it are available. Having these recipes available increases build
 time significantly and increases the size of the SDK installer by 30-80
@@ -351,15 +345,15 @@ in most cases.
    If you set
    SDK_EXT_TYPE
    to "minimal", then providing a shared state mirror is mandatory so
-   that items can be installed as needed. See the "
-   Providing Additional Installable Extensible SDK Content
-   " section for more information.
+   that items can be installed as needed. See the
+   :ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`
+   section for more information.
 
 You can explicitly control whether or not to include the toolchain when
 you build an SDK by setting the
 :term:`SDK_INCLUDE_TOOLCHAIN`
 variable to "1". In particular, it is useful to include the toolchain
-when you have set ``SDK_EXT_TYPE`` to "minimal", which by default,
+when you have set :term:`SDK_EXT_TYPE` to "minimal", which by default,
 excludes the toolchain. Also, it is helpful if you are building a small
 SDK for use with an IDE or some other tool where you do not want to take
 extra steps to install a toolchain.

documentation/sdk-manual/extensible.rst

@@ -15,9 +15,8 @@ hardware, and ease integration into the rest of the
 .. note::
 
    For a side-by-side comparison of main features supported for an
-   extensible SDK as compared to a standard SDK, see the "
-   Introduction
-   " section.
+   extensible SDK as compared to a standard SDK, see the
+   :ref:`sdk-manual/intro:introduction` section.
 
 In addition to the functionality available through ``devtool``, you can
 alternatively make use of the toolchain directly, for example from
@@ -89,9 +88,9 @@ the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot::
 .. 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
@@ -194,7 +193,7 @@ all the commands.
    devtool
    quick reference.
 
-Three ``devtool`` subcommands exist that provide entry-points into
+Three ``devtool`` subcommands provide entry-points into
 development:
 
 -  *devtool add*: Assists in adding new software to be built.
@@ -276,7 +275,7 @@ command:
          devtool
          always creates a Git repository locally during the extraction.
 
-      Furthermore, the first positional argument srctree in this case
+      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::
@@ -285,13 +284,13 @@ command:
 
       In summary,
       the source code is pulled from fetchuri and extracted into the
-      location defined by srctree as a local Git repository.
+      location defined by ``srctree`` as a local Git repository.
 
       Within workspace, ``devtool`` creates a recipe named recipe along
       with an associated append file.
 
    -  *Right*: The right scenario in the figure represents a situation
-      where the srctree has been previously prepared outside of the
+      where the ``srctree`` has been previously prepared outside of the
       ``devtool`` workspace.
 
       The following command provides a new recipe name and identifies
@@ -437,9 +436,9 @@ command:
       locate the source code and any local patch files from other
       developers.
 
-      With this scenario, no srctree argument exists. Consequently, the
+      With this scenario, there is no ``srctree`` argument. Consequently, the
       default behavior of the ``devtool modify`` command is to extract
-      the source files pointed to by the ``SRC_URI`` statements into a
+      the source files pointed to by the :term:`SRC_URI` statements into a
       local Git structure. Furthermore, the location for the extracted
       source is the default area within the ``devtool`` workspace. The
       result is that the command sets up both the source code and an
@@ -447,7 +446,7 @@ command:
       original location.
 
       Additionally, if you have any non-patch local files (i.e. files
-      referred to with ``file://`` entries in ``SRC_URI`` statement
+      referred to with ``file://`` entries in :term:`SRC_URI` statement
       excluding ``*.patch/`` or ``*.diff``), these files are copied to
       an ``oe-local-files`` folder under the newly created source tree.
       Copying the files here gives you a convenient area from which you
@@ -477,27 +476,27 @@ command:
          devtool
          command.
 
-      As with all extractions, the command uses the recipe's ``SRC_URI``
+      As with all extractions, the command uses the recipe's :term:`SRC_URI`
       statements to locate the source files and any associated patch
       files. Non-patch files are copied to an ``oe-local-files`` folder
       under the newly created source tree.
 
       Once the files are located, the command by default extracts them
-      into srctree.
+      into ``srctree``.
 
       Within workspace, ``devtool`` creates an append file for the
       recipe. The recipe remains in its original location but the source
-      files are extracted to the location you provide with srctree.
+      files are extracted to the location you provide with ``srctree``.
 
    -  *Right*: The right scenario in the figure represents a situation
-      where the source tree (srctree) already exists locally as a
+      where the source tree (``srctree``) already exists locally as a
       previously extracted Git structure outside of the ``devtool``
       workspace. In this example, the recipe also exists elsewhere
       locally in its own layer.
 
       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
+      extracted, and uses ``srctree`` to point to the previously extracted
       source files::
 
          $ devtool modify -n recipe srctree
@@ -604,11 +603,11 @@ counterparts.
 .. note::
 
    Several methods exist by which you can upgrade recipes -
-   devtool upgrade
+   ``devtool upgrade``
    happens to be one. You can read about all the methods by which you
-   can upgrade recipes in the "
-   Upgrading Recipes
-   " section of the Yocto Project Development Tasks Manual.
+   can upgrade recipes in the
+   :ref:`dev-manual/common-tasks:upgrading recipes` section
+   of the Yocto Project Development Tasks Manual.
 
 The ``devtool upgrade`` command is flexible enough to allow you to
 specify source code revision and versioning schemes, extract code into
@@ -646,8 +645,9 @@ The following diagram shows the common development flow used with the
    code into the ``sources`` directory in the
    :ref:`devtool-the-workspace-layer-structure`.
    If you want the code extracted to any other location, you need to
-   provide the srctree positional argument with the command as follows:
-   $ devtool upgrade -V version recipe srctree
+   provide the ``srctree`` positional argument with the command as follows::
+
+      $ devtool upgrade -V version recipe srctree
 
    .. note::
 
@@ -655,18 +655,18 @@ The following diagram shows the common development flow used with the
       don't use "-V", the command upgrades the recipe to the latest
       version.
 
-   If the source files pointed to by the ``SRC_URI`` statement in the
+   If the source files pointed to by the :term:`SRC_URI` statement in the
    recipe are in a Git repository, you must provide the "-S" option and
    specify a revision for the software.
 
-   Once ``devtool`` locates the recipe, it uses the ``SRC_URI`` variable
+   Once ``devtool`` locates the recipe, it uses the :term:`SRC_URI` variable
    to locate the source code and any local patch files from other
    developers. The result is that the command sets up the source code,
    the new version of the recipe, and an append file all within the
    workspace.
 
    Additionally, if you have any non-patch local files (i.e. files
-   referred to with ``file://`` entries in ``SRC_URI`` statement
+   referred to with ``file://`` entries in :term:`SRC_URI` statement
    excluding ``*.patch/`` or ``*.diff``), these files are copied to an
    ``oe-local-files`` folder under the newly created source tree.
    Copying the files here gives you a convenient area from which you can
@@ -674,9 +674,9 @@ The following diagram shows the common development flow used with the
    are incorporated into the build the next time you build the software
    just as are other changes you might have made to the source.
 
-2. *Resolve any Conflicts created by the Upgrade*: Conflicts could exist
-   due to the software being upgraded to a new version. Conflicts occur
-   if your recipe specifies some patch files in ``SRC_URI`` that
+2. *Resolve any Conflicts created by the Upgrade*: Conflicts could happen
+   after upgrading the software to a new version. Conflicts occur
+   if your recipe specifies some patch files in :term:`SRC_URI` that
    conflict with changes made in the new version of the software. For
    such cases, you need to resolve the conflicts by editing the source
    and following the normal ``git rebase`` conflict resolution process.
@@ -832,7 +832,7 @@ result from naming not being recognized or because the dependency simply
 is not available. For cases where the dependency is not available, you
 must use the ``devtool add`` command to add an additional recipe that
 satisfies the dependency. Once you add that recipe, you need to update
-the ``DEPENDS`` variable in the original recipe to include the new
+the :term:`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
@@ -861,7 +861,7 @@ license. If so, the command sets the
 :term:`LICENSE` value accordingly.
 You should double-check the value added by the command against the
 documentation or source files for the software you are building and, if
-necessary, update that ``LICENSE`` value.
+necessary, update that :term:`LICENSE` value.
 
 The ``devtool add`` command also sets the
 :term:`LIC_FILES_CHKSUM`
@@ -869,16 +869,16 @@ value to point to all files that appear to be license-related. Realize
 that license statements often appear in comments at the top of source
 files or within the documentation. In such cases, the command does not
 recognize those license statements. Consequently, you might need to
-amend the ``LIC_FILES_CHKSUM`` variable to point to one or more of those
-comments if present. Setting ``LIC_FILES_CHKSUM`` is particularly
+amend the :term:`LIC_FILES_CHKSUM` variable to point to one or more of those
+comments if present. Setting :term:`LIC_FILES_CHKSUM` is particularly
 important for third-party software. The mechanism attempts to ensure
 correct licensing should you upgrade the recipe to a newer upstream
 version in future. Any change in licensing is detected and you receive
 an error prompting you to check the license text again.
 
 If the ``devtool add`` command cannot determine licensing information,
-``devtool`` sets the ``LICENSE`` value to "CLOSED" and leaves the
-``LIC_FILES_CHKSUM`` value unset. This behavior allows you to continue
+``devtool`` sets the :term:`LICENSE` value to "CLOSED" and leaves the
+:term:`LIC_FILES_CHKSUM` value unset. This behavior allows you to continue
 with development even though the settings are unlikely to be correct in
 all cases. You should check the documentation or source files for the
 software you are building to determine the actual license.
@@ -904,12 +904,12 @@ mind:
    hardcoding tools within the toolchain such as ``gcc`` and ``g++``.
 
 -  The environment in which Make runs is set up with various standard
-   variables for compilation (e.g. ``CC``, ``CXX``, and so forth) in a
+   variables for compilation (e.g. :term:`CC`, :term:`CXX`, and so forth) in a
    similar manner to the environment set up by the SDK's environment
    setup script. One easy way to see these variables is to run the
    ``devtool build`` command on the recipe and then look in
-   ``oe-logs/run.do_compile``. Towards the top of this file, a list of
-   environment variables exists that are being set. You can take
+   ``oe-logs/run.do_compile``. Towards the top of this file, there is
+   a list of environment variables that are set. You can take
    advantage of these variables within the Makefile.
 
 -  If the Makefile sets a default for a variable using "=", that default
@@ -920,7 +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 :term:`EXTRA_OEMAKE`::
 
       EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
 
@@ -1037,8 +1037,8 @@ If you look at the contents of a recipe, you will see that the recipe
 does not include complete instructions for building the software.
 Instead, common functionality is encapsulated in classes inherited with
 the ``inherit`` directive. This technique leaves the recipe to describe
-just the things that are specific to the software being built. A
-:ref:`base <ref-classes-base>` class exists that
+just the things that are specific to the software being built. There is
+a :ref:`base <ref-classes-base>` class that
 is implicitly inherited by all recipes and provides the functionality
 that most recipes typically need.
 
@@ -1086,20 +1086,20 @@ extras specified by
 :term:`EXTRA_OECONF` or
 :term:`PACKAGECONFIG_CONFARGS`
 set within the recipe. If you wish to pass additional options, add them
-to ``EXTRA_OECONF`` or ``PACKAGECONFIG_CONFARGS``. Other supported build
+to :term:`EXTRA_OECONF` or :term:`PACKAGECONFIG_CONFARGS`. Other supported build
 tools have similar variables (e.g.
 :term:`EXTRA_OECMAKE` for
 CMake, :term:`EXTRA_OESCONS`
 for Scons, and so forth). If you need to pass anything on the ``make``
-command line, you can use ``EXTRA_OEMAKE`` or the
+command line, you can use :term:`EXTRA_OEMAKE` or the
 :term:`PACKAGECONFIG_CONFARGS`
 variables to do so.
 
 You can use the ``devtool configure-help`` command to help you set the
 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
+arguments specified through :term:`EXTRA_OECONF` or
+:term:`PACKAGECONFIG_CONFARGS`. If applicable, the command also shows you
 the output of the configure script's "--help" option as a
 reference.
 
@@ -1110,9 +1110,9 @@ Recipes often need to use files provided by other recipes on the
 :term:`Build Host`. For example,
 an application linking to a common library needs access to the library
 itself and its associated headers. The way this access is accomplished
-within the extensible SDK is through the sysroot. One sysroot exists per
+within the extensible SDK is through the sysroot. There is one sysroot per
 "machine" for which the SDK is being built. In practical terms, this
-means a sysroot exists for the target machine, and a sysroot exists for
+means there is a sysroot for the target machine, and a sysroot for
 the build host.
 
 Recipes should never write files directly into the sysroot. Instead,
@@ -1151,16 +1151,16 @@ the ``oe-workdir/packages-split`` directory, which contains a
 subdirectory for each package. Apart from some advanced cases, the
 :term:`PACKAGES` and
 :term:`FILES` variables controls
-splitting. The ``PACKAGES`` variable lists all of the packages to be
-produced, while the ``FILES`` variable specifies which files to include
+splitting. The :term:`PACKAGES` variable lists all of the packages to be
+produced, while the :term:`FILES` variable specifies which files to include
 in each package by using an override to specify the package. For
 example, ``FILES_${PN}`` specifies the files to go into the main package
 (i.e. the main package has the same name as the recipe and
 ``${``\ :term:`PN`\ ``}`` evaluates to the
-recipe name). The order of the ``PACKAGES`` value is significant. For
-each installed file, the first package whose ``FILES`` value matches the
-file is the package into which the file goes. Defaults exist for both
-the ``PACKAGES`` and ``FILES`` variables. Consequently, you might find
+recipe name). The order of the :term:`PACKAGES` value is significant. For
+each installed file, the first package whose :term:`FILES` value matches the
+file is the package into which the file goes. Both the :term:`PACKAGES` and
+:term:`FILES` variables have default values. Consequently, you might find
 you do not even need to set these variables in your recipe unless the
 software the recipe is building installs files into non-standard
 locations.
@@ -1230,7 +1230,7 @@ source, you can add the "-s" option as follows::
 
 It is important to remember that building the item from source
 takes significantly longer than installing the pre-built artifact. Also,
-if no recipe exists for the item you want to add to the SDK, you must
+if there is no recipe for the item you want to add to the SDK, you must
 instead add the item using the ``devtool add`` command.
 
 Applying Updates to an Installed Extensible SDK

documentation/sdk-manual/intro.rst

@@ -214,5 +214,5 @@ You just need to follow these general steps:
    within the Yocto Project.
 
 The remainder of this manual describes how to use the extensible and
-standard SDKs. Information also exists in appendix form that describes
+standard SDKs. There is also information in appendix form describing
 how you can build, install, and modify an SDK.

documentation/sdk-manual/working-projects.rst

@@ -135,9 +135,8 @@ project:
 
       To learn about environment variables established when you run the
       cross-toolchain environment setup script and how they are used or
-      overridden when the Makefile, see the "
-      Makefile-Based Projects
-      " section.
+      overridden by the Makefile, see the
+      :ref:`sdk-manual/working-projects:makefile-based projects` section.
 
    This next command is a simple way to verify the installation of your
    project. Running the command prints the architecture on which the
@@ -279,9 +278,9 @@ example:
       $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
 
 3. *Create the Makefile:* For this example, the Makefile contains
-   two lines that can be used to set the ``CC`` variable. One line is
+   two lines that can be used to set the :term:`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
+   setup script, and the other line sets :term:`CC` to "gcc", the default
    GNU compiler on the build host::
 
       # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
@@ -298,7 +297,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
+   value used for :term:`CC` is the value set when the SDK environment setup
    file was run::
 
       $ make
@@ -307,10 +306,10 @@ example:
       i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
 
    From the results of the previous command, you can see that
-   the compiler used was the compiler established through the ``CC``
+   the compiler used was the compiler established through the :term:`CC`
    variable defined in the setup script.
 
-   You can override the ``CC`` environment variable with the same
+   You can override the :term:`CC` environment variable with the same
    variable as set from the Makefile by uncommenting the line in the
    Makefile and running ``make`` again.
    ::
@@ -334,7 +333,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 :term:`CC` to "gcc"::
 
       $ make clean
       rm -rf *.o

documentation/sphinx-static/switchers.js

@@ -3,9 +3,9 @@
 
   var all_versions = {
     'dev': 'dev (3.4)',
-    '3.3': '3.3',
+    '3.3.1': '3.3.1',
     '3.2.4': '3.2.4',
-    '3.1.7': '3.1.7',
+    '3.1.9': '3.1.9',
     '3.0.4': '3.0.4',
     '2.7.4': '2.7.4',
   };

documentation/test-manual/index.rst

@@ -13,6 +13,8 @@ Yocto Project Test Environment Manual
    intro
    test-process
    understand-autobuilder
+   reproducible-builds
+   yocto-project-compatible
    history
 
 .. include:: /boilerplate.rst

documentation/test-manual/reproducible-builds.rst

@@ -0,0 +1,135 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+*******************
+Reproducible Builds
+*******************
+
+================
+How we define it
+================
+
+The Yocto Project defines reproducibility as where a given input build
+configuration will give the same binary output regardless of when it is built
+(now or in 5 years time), regardless of the path on the filesystem the build is
+run in, and regardless of the distro and tools on the underlying host system the
+build is running on.
+
+==============
+Why it matters
+==============
+
+The project aligns with the `Reproducible Builds project
+<https://reproducible-builds.org/>`_, which shares information about why
+reproducibility matters. The primary focus of the project is the ability to
+detect security issues being introduced. However, from a Yocto Project
+perspective, it is also hugely important that our builds are deterministic. When
+you build a given input set of metadata, we expect you to get consistent output.
+This has always been a key focus but, :yocto_docs:`since release 3.1 ("dunfell")
+</ref-manual/migration-3.1.html#reproducible-builds-now-enabled-by-default>`,
+it is now true down to the binary level including timestamps.
+
+For example, at some point in the future life of a product, you find that you
+need to rebuild to add a security fix. If this happens, only the components that
+have been modified should change at the binary level. This would lead to much
+easier and clearer bounds on where validation is needed.
+
+This also gives an additional benefit to the project builds themselves, our hash
+equivalence for :ref:`Shared State <overview-manual/concepts:Shared State>`
+object reuse works much more effectively when the binary output remains the
+same.
+
+.. note::
+
+   We strongly advise you to make sure your project builds reproducibly
+   before finalizing your production images. It would be too late if you
+   only address this issue when the first updates are required.
+
+===================
+How we implement it
+===================
+
+There are many different aspects to build reproducibility, but some particular
+things we do within the build system to ensure reproducibility include:
+
+-  Adding mappings to the compiler options to ensure debug filepaths are mapped
+   to consistent target compatible paths. This is done through the
+   ``DEBUG_PREFIX_MAP`` variable which sets the ``-fmacro-prefix-map`` and
+   ``-fdebug-prefix-map`` compiler options correctly to map to target paths.
+-  Being explicit about recipe dependencies and their configuration (no floating
+   configure options or host dependencies creeping in). In particular this means
+   making sure :term:`PACKAGECONFIG` coverage covers configure options which may
+   otherwise try and auto-detect host dependencies.
+-  Using recipe specific sysroots to isolate recipes so they only see their
+   dependencies. These are visible as ``recipe-sysroot`` and
+   ``recipe-sysroot-native`` directories within the :term:`WORKDIR` of a given
+   recipe and are populated only with the dependencies a recipe has.
+-  Build images from a reduced package set: only packages from recipes the image
+   depends upon.
+-  Filtering the tools available from the host's ``PATH`` to only a specific set
+   of tools, set using the :term:`HOSTTOOLS` variable.
+
+=========================================
+Can we prove the project is reproducible?
+=========================================
+
+Yes, we can prove it and we regularly test this on the Autobuilder. At the
+time of writing (release 3.3, "hardknott"), :term:`OpenEmbedded-Core (OE-Core)`
+is 100% reproducible for all its recipes (i.e. world builds) apart from the Go
+language and Ruby documentation packages. Unfortunately, the current
+implementation of the Go language has fundamental reproducibility problems as
+it always depends upon the paths it is built in.
+
+.. note::
+
+   Only BitBake and :term:`OpenEmbedded-Core (OE-Core)`, which is the ``meta``
+   layer in Poky, guarantee complete reproducibility. The moment you add
+   another layer, this warranty is voided, because of additional configuration
+   files, ``bbappend`` files, overridden classes, etc.
+
+To run our automated selftest, as we use in our CI on the Autobuilder, you can
+run::
+
+   oe-selftest -r reproducible.ReproducibleTests.test_reproducible_builds
+
+This defaults to including a ``world`` build so, if other layers are added, it would
+also run the tests for recipes in the additional layers. The first build will be
+run using :ref:`Shared State <overview-manual/concepts:Shared State>` if
+available, the second build explicitly disables
+:ref:`Shared State <overview-manual/concepts:Shared State>` and builds on the
+specific host the build is running on. This means we can test reproducibility
+builds between different host distributions over time on the Autobuilder.
+
+If ``OEQA_DEBUGGING_SAVED_OUTPUT`` is set, any differing packages will be saved
+here. The test is also able to run the ``diffoscope`` command on the output to
+generate HTML files showing the differences between the packages, to aid
+debugging. On the Autobuilder, these appear under
+https://autobuilder.yocto.io/pub/repro-fail/ in the form ``oe-reproducible +
+<date> + <random ID>``, e.g. ``oe-reproducible-20200202-1lm8o1th``.
+
+The project's current reproducibility status can be seen at
+:yocto_home:`/reproducible-build-results/`
+
+You can also check the reproducibility status on supported host distributions:
+
+-  CentOS: :yocto_ab:`/typhoon/#/builders/reproducible-centos`
+-  Debian: :yocto_ab:`/typhoon/#/builders/reproducible-debian`
+-  Fedora: :yocto_ab:`/typhoon/#/builders/reproducible-fedora`
+-  Ubuntu: :yocto_ab:`/typhoon/#/builders/reproducible-ubuntu`
+
+===============================
+Can I test my layer or recipes?
+===============================
+
+Once again, you can run a ``world`` test using the
+:ref:`oe-selftest <ref-manual/release-process:Testing and Quality Assurance>`
+command provided above. This functionality is implemented
+in :oe_git:`meta/lib/oeqa/selftest/cases/reproducible.py
+</openembedded-core/tree/meta/lib/oeqa/selftest/cases/reproducible.py>`.
+
+You could subclass the test and change ``targets`` to a different target.
+
+You may also change ``sstate_targets`` which would allow you to "pre-cache" some
+set of recipes before the test, meaning they are excluded from reproducibility
+testing. As a practical example, you could set ``sstate_targets`` to
+``core-image-sato``, then setting ``targets`` to ``core-image-sato-sdk`` would
+run reproducibility tests only on the targets belonging only to ``core-image-sato-sdk``.

documentation/test-manual/yocto-project-compatible.rst

@@ -0,0 +1,124 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+************************
+Yocto Project Compatible
+************************
+
+============
+Introduction
+============
+
+After the introduction of layers to OpenEmbedded, it quickly became clear
+that while some layers were popular and worked well, others developed a
+reputation for being "problematic". Those were layers which didn't
+interoperate well with others and tended to assume they controlled all
+the aspects of the final output.  This usually isn't intentional but happens
+because such layers are often created by developers with a particular focus
+(e.g. a company's :term:`BSP<Board Support Package (BSP)>`) whilst the end
+users have a different one (e.g. integrating that
+:term:`BSP<Board Support Package (BSP)>` into a product).
+
+As a result of noticing such patterns and friction between layers, the project
+developed the "Yocto Project Compatible" badge program, allowing layers
+following the best known practises to be marked as being widely compatible
+with other ones. This takes the form of a set of "yes/no" binary answer
+questions where layers can declare if they meet the appropriate criteria.
+In the second version of the program, a script was added to make validation
+easier and clearer, the script is called  ``yocto-check-layer`` and is
+available in :term:`OpenEmbedded-Core (OE-Core)`.
+
+See :ref:`dev-manual/common-tasks:making sure your layer is compatible with yocto project`
+for details.
+
+========
+Benefits
+========
+
+:ref:`overview-manual/yp-intro:the yocto project layer model` is powerful
+and flexible: it gives users the ultimate power to change pretty much any
+aspect of the system but as with most things, power comes with responsibility.
+The Yocto Project would like to see people able to mix and match BSPs with
+distro configs or software stacks and be able to merge succesfully.
+Over time, the project identified characteristics in layers that allow them
+to operate well together. "anti-patterns" were also found, preventing layers
+from working well together.
+
+The intent of the compatibility program is simple: if the layer passes the
+compatibility tests, it is considered "well behaved" and should operate
+and cooperate well with other compatible layers.
+
+The benefits of compatibility can be seen from multiple different user and
+member perspectives. From a hardware perspective
+(a :ref:`overview-manual/concepts:bsp layer`), compatibility means the
+hardware can be used in many different products and use cases without
+impacting the software stacks being run with it. For a company developing
+a product, compatibility gives you a specification / standard you can
+require in a contract and then know it will have certain desired
+characteristics for interoperability. It also puts constraints on how invasive
+the code bases are into the rest of the system, meaning that multiple
+different separate hardware support layers can coexist (e.g. for multiple
+product lines from different hardware manufacturers). This can also make it
+easier for one or more parties to upgrade those system components for security
+purposes during the lifecycle of a product.
+
+==================
+Validating a layer
+==================
+
+The badges are available to members of the Yocto Project (as member benefit)
+and to open source projects run on a non-commercial basis. However, anyone can
+answer the questions and run the script.
+
+The project encourages all layer maintainers to review the questions and the
+output from the script against their layer, as the way some layers are
+constructed often has unintended consequences. The questions and the script
+are designed to highlight known issues which are often easy to solve. This
+makes layers easier to use and therefore more popular.
+
+It is intended that over time, the tests will evolve as new best known
+practices are identified, and as new interoperability issues are found,
+unnecessarily restricting layer interoperability. If anyone becomes aware of
+either type, please let the project know through the
+:yocto_home:`technical calls </public-virtual-meetings/>`,
+the :yocto_home:`mailing lists </community/mailing-lists/>`
+or through the :oe_wiki:`Technical Steering Committee (TSC) </TSC>`.
+The TSC is responsible for the technical criteria used by the program.
+
+Layers are divided into three types:
+
+-  :ref:`"BSP" or "hardware support"<overview-manual/concepts:bsp layer>`
+   layers contain support for particular pieces of hardware. This includes
+   kernel and boot loader configuration, and any recipes for firmware or
+   kernel modules needed for the hardware. Such layers usually correspond
+   to a :term:`MACHINE` setting.
+
+-  :ref:`"distro" layers<overview-manual/concepts:distro layer>` defined
+   as layers providing configuration options and settings such as the
+   choice of init system, compiler and optimisation options, and
+   configuration and choices of software components. This would usually
+   correspond to a :term:`DISTRO` setting.
+
+-  "software" layers are usually recipes. A layer might target a
+   particular graphical UI or software stack component.
+
+Here are key best practices the program tries to encourage:
+
+-  A layer should clearly show who maintains it, and who change
+   submissions and bug reports should be sent to.
+
+-  Where multiple types of functionality are present, the layer should
+   be internally divided into sublayers to separate these components.
+   That's because some users may only need one of them and separability
+   is a key best practice.
+
+-  Adding a layer to a build should not modify that build, unless the
+   user changes a configuration setting to activate the layer, by selecting
+   a :term:`MACHINE`, a :term:`DISTRO` or a :term:`DISTRO_FEATURES` setting.
+
+The project does test the compatibility status of the core project layers on
+its :doc:`Autobuilder </test-manual/understand-autobuilder>`.
+
+The official form to submit compatibility requests with is at
+:yocto_home:`/ecosystem/branding/compatible-registration/`.
+Applicants can display the badge they get when their application is successful.
+

documentation/toaster-manual/reference.rst

@@ -9,8 +9,8 @@ concepts and have some basic command reference material available. This
 final chapter provides conceptual information on layer sources,
 releases, and JSON configuration files. Also provided is a quick look at
 some useful ``manage.py`` commands that are Toaster-specific.
-Information on ``manage.py`` commands does exist across the Web and the
-information in this manual by no means attempts to provide a command
+Information on ``manage.py`` commands is available across the Web and
+this manual by no means attempts to provide a command
 comprehensive reference.
 
 Layer Source
@@ -508,7 +508,7 @@ Useful Commands
 ===============
 
 In addition to the web user interface and the scripts that start and
-stop Toaster, command-line commands exist through the ``manage.py``
+stop Toaster, command-line commands are available through the ``manage.py``
 management script. You can find general documentation on ``manage.py``
 at the
 `Django <https://docs.djangoproject.com/en/2.2/topics/settings/>`__

documentation/toaster-manual/setup-and-use.rst

@@ -625,7 +625,7 @@ To specify ``bash`` 3.2.48 as the version to build, enter
    :scale: 75%
 
 After clicking the "Add variable" button, the settings for
-``PREFERRED_VERSION`` are added to the bottom of the BitBake variables
+:term:`PREFERRED_VERSION` are added to the bottom of the BitBake variables
 list. With these settings, the OpenEmbedded build system builds the
 desired version of the recipe rather than the default version:
 

documentation/transitioning-to-a-custom-environment.rst

@@ -47,7 +47,7 @@ Transitioning to a custom environment for systems development
 #. **Based on the layers you've chosen, make needed changes in your
    configuration**.
    For instance, you've chosen a machine type and added in the corresponding BSP
-   layer. You'll then need to change the value of the ``MACHINE`` variable in your
+   layer. You'll then need to change the value of the :term:`MACHINE` variable in your
    configuration file (build/local.conf) to point to that same machine
    type. There could be other layer-specific settings you need to change as
    well. Each layer has a ``README`` document that you can look at for this type of

meta-poky/README.poky

@@ -1,71 +0,0 @@
-Poky
-====
-
-Poky is an integration of various components to form a complete prepackaged
-build system and development environment. It features support for building
-customised embedded device style images. There are reference demo images
-featuring a X11/Matchbox/GTK themed UI called Sato. The system supports
-cross-architecture application development using QEMU emulation and a
-standalone toolchain and SDK with IDE integration.
-
-Additional information on the specifics of hardware that Poky supports
-is available in README.hardware. Further hardware support can easily be added
-in the form of layers which extend the systems capabilities in a modular way.
-
-As an integration layer Poky consists of several upstream projects such as 
-BitBake, OpenEmbedded-Core, Yocto documentation and various sources of information 
-e.g. for the hardware support. Poky is in turn a component of the Yocto Project.
-
-The Yocto Project has extensive documentation about the system including a 
-reference manual which can be found at:
-    http://yoctoproject.org/documentation
-
-OpenEmbedded-Core is a layer containing the core metadata for current versions
-of OpenEmbedded. It is distro-less (can build a functional image with
-DISTRO = "nodistro") and contains only emulated machine support.
-
-For information about OpenEmbedded, see the OpenEmbedded website:
-    http://www.openembedded.org/
-
-
-Contribution Guidelines
-=======================
-
-A guide to submitting patches to OpenEmbedded is available at:
-
-http://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded
-
-There is good documentation on how to write/format patches at:
-
-https://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines
-
-
-Where to Send Patches
-=====================
-
-As Poky is an integration repository (built using a tool called combo-layer),
-patches against the various components should be sent to their respective
-upstreams:
-
-bitbake:
-    Git repository: http://git.openembedded.org/bitbake/
-    Mailing list: bitbake-devel@lists.openembedded.org
-
-documentation:
-    Git repository: http://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/
-    Mailing list: docs@lists.yoctoproject.org
-
-meta-poky, meta-yocto-bsp:
-    Git repository: http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto(-bsp)
-    Mailing list: poky@lists.yoctoproject.org
-
-Everything else should be sent to the OpenEmbedded Core mailing list.  If in
-doubt, check the oe-core git repository for the content you intend to modify.
-Before sending, be sure the patches apply cleanly to the current oe-core git
-repository.
-
-    Git repository: http://git.openembedded.org/openembedded-core/
-    Mailing list: openembedded-core@lists.openembedded.org
-
-Note: The scripts directory should be treated with extra care as it is a mix of
-oe-core and poky-specific files from meta-poky.

meta-poky/README.poky.md

@@ -0,0 +1,84 @@
+Poky
+====
+
+Poky is an integration of various components to form a pre-packaged
+build system and development environment which is used as a development and
+validation tool by the [Yocto Project](http://www.yoctoproject.org/). It
+features support for building customised embedded style device images
+and custom containers. There are reference demo images ranging from X11/GTK+
+ to Weston, commandline and more. The system supports cross-architecture
+application development using QEMU emulation and a standalone toolchain and
+SDK suitable for IDE integration.
+
+Additional information on the specifics of hardware that Poky supports
+is available in README.hardware. Further hardware support can easily be added
+in the form of BSP layers which extend the systems capabilities in a modular way.
+Many layers are available and can be found through the
+[layer index](https://layers.openembedded.org/).
+
+As an integration layer Poky consists of several upstream projects such as 
+[BitBake](https://git.openembedded.org/bitbake/),
+[OpenEmbedded-Core](https://git.openembedded.org/openembedded-core/),
+[Yocto documentation](http://git.yoctoproject.org/cgit.cgi/yocto-docs/),
+the '[meta-yocto](http://git.yoctoproject.org/cgit.cgi/meta-yocto/)' layer
+which has configuration and hardware support components. These components
+are all part of the Yocto Project and OpenEmbedded ecosystems.
+
+The Yocto Project has extensive documentation about the system including a 
+reference manual which can be found at <https://docs.yoctoproject.org/>
+
+OpenEmbedded is the build architecture used by Poky and the Yocto project.
+For information about OpenEmbedded, see the 
+[OpenEmbedded website](http://www.openembedded.org/).
+
+Contribution Guidelines
+-----------------------
+
+The project works using a mailing list patch submission process. Patches
+should be sent to the mailing list for the repository the components
+originate from (see below). Throughout the Yocto Project, the README
+files in the component in question should detail where to send patches,
+who the maintainers are and where bugs should be reported.
+
+A guide to submitting patches to OpenEmbedded is available at:
+
+<http://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded>
+
+There is good documentation on how to write/format patches at:
+
+<https://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines>
+
+Where to Send Patches
+---------------------
+
+As Poky is an integration repository (built using a tool called combo-layer),
+patches against the various components should be sent to their respective
+upstreams:
+
+OpenEmbedded-Core (files in meta/, meta-selftest/, meta-skeleton/, scripts/):
+
+- Git repository: <https://git.openembedded.org/openembedded-core/>
+- Mailing list: openembedded-core@lists.openembedded.org
+
+BitBake (files in bitbake/):
+
+- Git repository: <https://git.openembedded.org/bitbake/>
+- Mailing list: bitbake-devel@lists.openembedded.org
+
+Documentation (files in documentation/):
+
+- Git repository: <https://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/>
+- Mailing list: docs@lists.yoctoproject.org
+
+meta-yocto (files in meta-poky/, meta-yocto-bsp/):
+
+- Git repository: <http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto>
+- Mailing list: poky@lists.yoctoproject.org
+
+If in doubt, check the openembedded-core git repository for the content you
+intend to modify as most files are from there unless clearly one of the above
+categories. Before sending, be sure the patches apply cleanly to the current
+git repository branch in question.
+
+[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/765/badge)](https://bestpractices.coreinfrastructure.org/projects/765)
+

meta-poky/conf/distro/include/poky-floating-revisions.inc

@@ -26,8 +26,6 @@ SRCREV_pn-sato-icon-theme ?= "${AUTOREV}"
 SRCREV_pn-matchbox-desktop-sato ?= "${AUTOREV}"
 SRCREV_pn-oh-puzzles ?= "${AUTOREV}"
 SRCREV_pn-libowl ?= "${AUTOREV}"
-SRCREV_pn-clutter ?= "${AUTOREV}"
-SRCREV_pn-clutter-gst ?= "${AUTOREV}"
 SRCREV_pn-libmatchbox ?= "${AUTOREV}"
 SRCREV_pn-ofono ?= "${AUTOREV}"
 

meta-poky/conf/distro/poky-tiny.conf

@@ -115,7 +115,6 @@ RDEPENDS_${PN}-mtrace_pn-eglibc = ""
 
 PNBLACKLIST[build-appliance-image] = "not buildable with poky-tiny"
 PNBLACKLIST[core-image-base] = "not buildable with poky-tiny"
-PNBLACKLIST[core-image-clutter] = "not buildable with poky-tiny"
 PNBLACKLIST[core-image-full-cmdline] = "not buildable with poky-tiny"
 PNBLACKLIST[core-image-rt] = "not buildable with poky-tiny"
 PNBLACKLIST[core-image-rt-sdk] = "not buildable with poky-tiny"

meta-skeleton/README.skeleton

@@ -0,0 +1,4 @@
+meta-skeleton
+=============
+
+The meta-skeleton layer contains example recipes and configuration files.

meta-skeleton/recipes-core/busybox/busybox_%.bbappend

@@ -2,11 +2,12 @@
 # mechanism as the linux-yocto kernel recipe.
 #
 # The entries here will override any entries in the base busybox recipe
+# when DISTRO = "mydistro" is defined in your conf/local.conf file.
 #
 # More details can be found in the Kernel Dev Manual
 # http://www.yoctoproject.org/docs/current/kernel-dev/kernel-dev.html#changing-the-configuration
 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
 
-SRC_URI += " \
+SRC_URI_append_mydistro += " \
 	    file://no_rfkill.cfg \
            "