[PATCH v2 00/14] Documentation updates for 3.3

[PATCH v2 00/14] Documentation updates for 3.3

[Paul Eggleton]

The migration guide for 3.3, plus some missing related changes and a few
cleanups. Let me know if I missed anything.

Changes since v1:
* Incorporated feedback from Quentin, Nico & Robert.
* Removed erroneous mention of ccache host requirement (commit that
  made the corresponding code change was later reverted)
* Added DISTUTILS_SETUP_PATH info as I noticed this was also missing.



The following changes since commit 4f7f451df266a307b34bf145b29291ca85eb882f:

  docs: add a top level page for bitbake documentation (2021-04-09 09:00:53 +0200)

are available in the git repository at:

  git://git.yoctoproject.org/poky-contrib paule/migration-3.3
  http://git.yoctoproject.org/cgit.cgi/poky-contrib/log/?h=paule/migration-3.3

Paul Eggleton (14):
  ref-manual: add METADATA_REVISION and METADATA_BRANCH
  Use variables for minimum host versions and bump Python to 3.6
  ref-manual: update/fix text for SDK_VERSION
  overview-manual: fix git command line
  ref-manual: and SDK_CUSTOM_TEMPLATECONF to glossary
  ref-manual: add REQUIRED_VERSION and adjust PREFERRED_VERSION entry
  ref-manual: add python3targetconfig class and remove python 2
    references
  ref-manual: add passwd-expire to EXTRA_USERS_PARAMS
  ref-manual: add FIT_KERNEL_COMP_ALG*
  ref-manual: fix reference to build-essential
  ref-manual: tweak buildtools section
  ref-manual: add migration section for 3.3 release
  ref-manual: migration guide: add release codenames
  ref-manual: add mention of DISTUTILS_SETUP_PATH

 documentation/brief-yoctoprojectqs/index.rst       |   8 +-
 documentation/dev-manual/start.rst                 |   8 +-
 .../overview-manual/development-environment.rst    |   2 +-
 documentation/poky.yaml                            |   4 +
 documentation/ref-manual/classes.rst               |  67 ++------
 documentation/ref-manual/faq.rst                   |   2 +-
 documentation/ref-manual/migration-1.3.rst         |   6 +-
 documentation/ref-manual/migration-1.4.rst         |   6 +-
 documentation/ref-manual/migration-1.5.rst         |   6 +-
 documentation/ref-manual/migration-1.6.rst         |   6 +-
 documentation/ref-manual/migration-1.7.rst         |   6 +-
 documentation/ref-manual/migration-1.8.rst         |   6 +-
 documentation/ref-manual/migration-2.0.rst         |   6 +-
 documentation/ref-manual/migration-2.1.rst         |   6 +-
 documentation/ref-manual/migration-2.2.rst         |   6 +-
 documentation/ref-manual/migration-2.3.rst         |   6 +-
 documentation/ref-manual/migration-2.4.rst         |   6 +-
 documentation/ref-manual/migration-2.5.rst         |   6 +-
 documentation/ref-manual/migration-2.6.rst         |   8 +-
 documentation/ref-manual/migration-2.7.rst         |   6 +-
 documentation/ref-manual/migration-3.0.rst         |   6 +-
 documentation/ref-manual/migration-3.1.rst         |   6 +-
 documentation/ref-manual/migration-3.2.rst         |   6 +-
 documentation/ref-manual/migration-3.3.rst         | 168 +++++++++++++++++++++
 documentation/ref-manual/migration.rst             |   1 +
 documentation/ref-manual/system-requirements.rst   |  19 ++-
 documentation/ref-manual/variables.rst             |  89 +++++++++--
 27 files changed, 337 insertions(+), 135 deletions(-)
 create mode 100644 documentation/ref-manual/migration-3.3.rst

-- 
1.8.3.1

[PATCH v2 01/14] ref-manual: add METADATA_REVISION and METADATA_BRANCH

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

These are not new variables, but we are using METADATA_REVISION in a new
place and thus need to refer to it.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 19f5e34..f906d4e 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -4659,6 +4659,14 @@ system and gives an overview of their function and contents.
    :term:`MAINTAINER`
       The email address of the distribution maintainer.
 
+   :term:`METADATA_BRANCH`
+      The branch currently checked out for the OpenEmbedded-Core layer (path
+      determined by :term:`COREBASE`).
+
+   :term:`METADATA_REVISION`
+      The revision currently checked out for the OpenEmbedded-Core layer (path
+      determined by :term:`COREBASE`).
+
    :term:`MIRRORS`
       Specifies additional paths from which the OpenEmbedded build system
       gets source code. When the build system searches for source code, it
-- 
1.8.3.1

[PATCH v2 02/14] Use variables for minimum host versions and bump Python to 3.6

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Minimum Git, tar, Python and gcc versions are specified in quite a few
different places. Let's add some variables for these so there's no
chance of missing one if they're updated in future. Additionally, for
hardknott the minimum Python version is 3.6 so set that as the value for
Python.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/brief-yoctoprojectqs/index.rst     | 8 ++++----
 documentation/dev-manual/start.rst               | 8 ++++----
 documentation/poky.yaml                          | 4 ++++
 documentation/ref-manual/faq.rst                 | 2 +-
 documentation/ref-manual/system-requirements.rst | 8 ++++----
 5 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index 7bba47e..974ae5e 100644
--- a/documentation/brief-yoctoprojectqs/index.rst
+++ b/documentation/brief-yoctoprojectqs/index.rst
@@ -60,10 +60,10 @@ following requirements:
 
 -
 
-   -  Git 1.8.3.1 or greater
-   -  tar 1.28 or greater
-   -  Python 3.5.0 or greater.
-   -  gcc 5.0 or greater.
+   -  Git &MIN_GIT_VERSION; or greater
+   -  tar &MIN_TAR_VERSION; or greater
+   -  Python &MIN_PYTHON_VERSION; or greater.
+   -  gcc &MIN_GCC_VERSION; or greater.
 
 If your build host does not meet any of these three listed version
 requirements, you can take steps to prepare the system so that you
diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
index 3903618..84abf4c 100644
--- a/documentation/dev-manual/start.rst
+++ b/documentation/dev-manual/start.rst
@@ -314,13 +314,13 @@ Project Build Host:
    should be able to run on any modern distribution that has the
    following versions for Git, tar, Python and gcc.
 
-   -  Git 1.8.3.1 or greater
+   -  Git &MIN_GIT_VERSION; or greater
 
-   -  tar 1.28 or greater
+   -  tar &MIN_TAR_VERSION; or greater
 
-   -  Python 3.5.0 or greater.
+   -  Python &MIN_PYTHON_VERSION; or greater.
 
-   -  gcc 5.0 or greater.
+   -  gcc &MIN_GCC_VERSION; or greater.
 
    If your build host does not meet any of these three listed version
    requirements, you can take steps to prepare the system so that you
diff --git a/documentation/poky.yaml b/documentation/poky.yaml
index e0cf0b3..8ccb359 100644
--- a/documentation/poky.yaml
+++ b/documentation/poky.yaml
@@ -40,3 +40,7 @@ CENTOS8_HOST_PACKAGES_ESSENTIAL : "-y epel-release
      python3-GitPython python3-jinja2 python3-pexpect xz which SDL-devel xterm \
      rpcgen mesa-libGL-devel"
 PIP3_HOST_PACKAGES_DOC : "$ sudo pip3 install sphinx sphinx_rtd_theme pyyaml"
+MIN_PYTHON_VERSION : "3.6.0"
+MIN_TAR_VERSION : "1.28"
+MIN_GIT_VERSION : "1.8.3.1"
+MIN_GCC_VERSION : "5.0"
diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
index 3b65588..64fdfdf 100644
--- a/documentation/ref-manual/faq.rst
+++ b/documentation/ref-manual/faq.rst
@@ -16,7 +16,7 @@ first before being pulled back into Poky. This practice benefits both
 projects immediately.
 
 **Q:** My development system does not meet the required Git, tar, and
-Python versions. In particular, I do not have Python 3.5.0 or greater.
+Python versions. In particular, I do not have Python &MIN_PYTHON_VERSION; or greater.
 Can I still use the Yocto Project?
 
 **A:** You can get the required tools on your host development system a
diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
index 6edfa1a..dc619ce 100644
--- a/documentation/ref-manual/system-requirements.rst
+++ b/documentation/ref-manual/system-requirements.rst
@@ -256,11 +256,11 @@ Required Git, tar, Python and gcc Versions
 In order to use the build system, your host development system must meet
 the following version requirements for Git, tar, and Python:
 
--  Git 1.8.3.1 or greater
+-  Git &MIN_GIT_VERSION; or greater
 
--  tar 1.28 or greater
+-  tar &MIN_TAR_VERSION; or greater
 
--  Python 3.5.0 or greater
+-  Python &MIN_PYTHON_VERSION; or greater
 
 If your host development system does not meet all these requirements,
 you can resolve this by installing a ``buildtools`` tarball that
@@ -270,7 +270,7 @@ a pre-built tarball or use BitBake to build the tarball.
 In addition, your host development system must meet the following
 version requirement for gcc:
 
--  gcc 5.0 or greater
+-  gcc &MIN_GCC_VERSION; or greater
 
 If your host development system does not meet this requirement, you can
 resolve this by installing a ``buildtools-extended`` tarball that
-- 
1.8.3.1

[PATCH v2 03/14] ref-manual: update/fix text for SDK_VERSION

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

DISTRO_VERSION snapshot versions use METADATA_REVISION not DATE in
hardknott and thus the default for SDK_VERSION has been updated, so
update it here as well. Additionally, fix the text so it makes sense.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index f906d4e..188a3eb 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6764,16 +6764,16 @@ system and gives an overview of their function and contents.
       Specifies the name of the SDK vendor.
 
    :term:`SDK_VERSION`
-      Specifies the version of the SDK. The distribution configuration file
-      (e.g. ``/meta-poky/conf/distro/poky.conf``) defines the
+      Specifies the version of the SDK. The Poky distribution configuration file
+      (``/meta-poky/conf/distro/poky.conf``) sets the default
       ``SDK_VERSION`` as follows:
       ::
 
-         SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}"
+         SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}"
 
       For additional information, see the
       :term:`DISTRO_VERSION` and
-      :term:`DATE` variables.
+      :term:`METADATA_REVISION` variables.
 
    :term:`SDKEXTPATH`
       The default installation directory for the Extensible SDK. By
-- 
1.8.3.1

[PATCH v2 04/14] overview-manual: fix git command line

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

There was an en dash here instead of a hyphen; this meant that the
command line could not be copied and pasted verbatim. (Admittedly that
is less likely here than in other examples, but let's correct it
anyway.)

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/overview-manual/development-environment.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/overview-manual/development-environment.rst b/documentation/overview-manual/development-environment.rst
index 6d1dbfc..a33f89e 100644
--- a/documentation/overview-manual/development-environment.rst
+++ b/documentation/overview-manual/development-environment.rst
@@ -542,7 +542,7 @@ descriptions and strategies on how to use these commands:
    in this form assumes the local branch already exists. This command is
    analogous to "cd".
 
--  *git checkout –b working-branch upstream-branch:* Creates and
+-  *git checkout -b working-branch upstream-branch:* Creates and
    checks out a working branch on your local machine. The local branch
    tracks the upstream branch. You can use your local branch to isolate
    your work. It is a good idea to use local branches when adding
-- 
1.8.3.1

[PATCH v2 05/14] ref-manual: and SDK_CUSTOM_TEMPLATECONF to glossary

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 188a3eb..4632754 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6489,6 +6489,11 @@ system and gives an overview of their function and contents.
       The target architecture for the SDK. Typically, you do not directly
       set this variable. Instead, use :term:`SDKMACHINE`.
 
+   :term:`SDK_CUSTOM_TEMPLATECONF`
+      When building the extensible SDK, if ``SDK_CUSTOM_TEMPLATECONF`` is set to
+      "1" and a ``conf/templateconf.conf`` file exists in the build directory
+      (``TOPDIR``) then this will be copied into the SDK.
+
    :term:`SDK_DEPLOY`
       The directory set up and used by the
       :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which
-- 
1.8.3.1

[PATCH v2 06/14] ref-manual: add REQUIRED_VERSION and adjust PREFERRED_VERSION entry

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Add REQUIRED_VERSION, add a reference to it in PREFERRED_VERSION and
adjust the opening statement to read slightly better.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 4632754..e63d07b 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -5798,10 +5798,11 @@ system and gives an overview of their function and contents.
          exclusive alternative providers.
 
    :term:`PREFERRED_VERSION`
-      If multiple versions of recipes exist, this variable determines which
-      version is given preference. You must always suffix the variable with
-      the :term:`PN` you want to select, and you should set the
-      :term:`PV` accordingly for precedence.
+      If there are multiple versions of a recipe available, this variable
+      determines which version should be given preference. You must always
+      suffix the variable with the :term:`PN` you want to select (`python` in
+      the first example below), and you should specify the :term:`PV`
+      accordingly (`3.4.0` in the example).
 
       The ``PREFERRED_VERSION`` variable supports limited wildcard use
       through the "``%``" character. You can use the character to match any
@@ -5859,6 +5860,10 @@ system and gives an overview of their function and contents.
          The ``\_forcevariable`` override is not handled specially. This override
          only works because the default value of ``OVERRIDES`` includes "forcevariable".
 
+      If a recipe with the specified version is not available, a warning
+      message will be shown. See :term:`REQUIRED_VERSION` if you want this
+      to be an error instead.
+
    :term:`PREMIRRORS`
       Specifies additional paths from which the OpenEmbedded build system
       gets source code. When the build system searches for source code, it
@@ -6216,6 +6221,17 @@ system and gives an overview of their function and contents.
       the recipe will be skipped, and if the build system attempts to build
       the recipe then an error will be triggered.
 
+   :term:`REQUIRED_VERSION`
+      If there are multiple versions of a recipe available, this variable
+      determines which version should be given preference.
+      :term:`REQUIRED_VERSION` works in exactly the same manner as
+      :term:`PREFERRED_VERSION`, except that if the specified version is not
+      available then an error message is shown and the build fails
+      immediately.
+
+      If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set
+      for the same recipe, the :term:`REQUIRED_VERSION` value applies.
+
    :term:`RM_WORK_EXCLUDE`
       With ``rm_work`` enabled, this variable specifies a list of recipes
       whose work directories should not be removed. See the
-- 
1.8.3.1

[PATCH v2 07/14] ref-manual: add python3targetconfig class and remove python 2 references

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Add the recently added python3targetconfig class. Also, we no longer
have the python 2 classes, remove all references to those.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/classes.rst       | 67 +++++++-----------------------
 documentation/ref-manual/migration-2.6.rst |  2 +-
 documentation/ref-manual/variables.rst     | 10 ++---
 3 files changed, 20 insertions(+), 59 deletions(-)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 6d9779f..52a50fa 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -501,29 +501,6 @@ Support for other version control systems such as Subversion is limited
 due to BitBake's automatic fetch dependencies (e.g.
 ``subversion-native``).
 
-.. _ref-classes-distutils:
-
-``distutils*.bbclass``
-======================
-
-The ``distutils*`` classes support recipes for Python version 2.x
-extensions, which are simple. These recipes usually only need to point
-to the source's archive and then inherit the proper class. Building is
-split into two methods depending on which method the module authors
-used.
-
--  Extensions that use an Autotools-based build system require Autotools
-   and the classes based on ``distutils`` in their recipes.
-
--  Extensions that use build systems based on ``distutils`` require the
-   ``distutils`` class in their recipes.
-
--  Extensions that use build systems based on ``setuptools`` require the
-   :ref:`setuptools <ref-classes-setuptools>` class in their recipes.
-
-The ``distutils-common-base`` class is required by some of the
-``distutils*`` classes to provide common Python2 support.
-
 .. _ref-classes-distutils3:
 
 ``distutils3*.bbclass``
@@ -542,15 +519,9 @@ used.
    ``distutils`` class in their recipes.
 
 -  Extensions that use build systems based on ``setuptools3`` require
-   the :ref:`setuptools3 <ref-classes-setuptools>` class in their
+   the :ref:`setuptools3 <ref-classes-setuptools3>` class in their
    recipes.
 
-The ``distutils3*`` classes either inherit their corresponding
-``distutils*`` class or replicate them using a Python3 version instead
-(e.g. ``distutils3-base`` inherits ``distutils-common-base``, which is
-the same as ``distutils-base`` but inherits ``python3native`` instead of
-``pythonnative``).
-
 .. _ref-classes-externalsrc:
 
 ``externalsrc.bbclass``
@@ -2138,13 +2109,13 @@ For information on setting up and running ptests, see the
 ":ref:`dev-manual/common-tasks:testing packages with ptest`"
 section in the Yocto Project Development Tasks Manual.
 
-.. _ref-classes-python-dir:
+.. _ref-classes-python3-dir:
 
-``python-dir.bbclass``
-======================
+``python3-dir.bbclass``
+=======================
 
-The ``python-dir`` class provides the base version, location, and site
-package location for Python.
+The ``python3-dir`` class provides the base version, location, and site
+package location for Python 3.
 
 .. _ref-classes-python3native:
 
@@ -2155,14 +2126,17 @@ The ``python3native`` class supports using the native version of Python
 3 built by the build system rather than support of the version provided
 by the build host.
 
-.. _ref-classes-pythonnative:
+.. _ref-classes-python3targetconfig:
 
-``pythonnative.bbclass``
-========================
+``python3targetconfig.bbclass``
+===============================
 
-When inherited by a recipe, the ``pythonnative`` class supports using
-the native version of Python built by the build system rather than using
-the version provided by the build host.
+The ``python3targetconfig`` class supports using the native version of Python
+3 built by the build system rather than support of the version provided
+by the build host, except that the configuration for the target machine
+is accessible (such as correct installation directories). This also adds a
+dependency on target ``python3``, so should only be used where appropriate
+in order to avoid unnecessarily lengthening builds.
 
 .. _ref-classes-qemu:
 
@@ -2323,22 +2297,13 @@ additional configuration options you want to pass SCons command line.
 The ``sdl`` class supports recipes that need to build software that uses
 the Simple DirectMedia Layer (SDL) library.
 
-.. _ref-classes-setuptools:
-
-``setuptools.bbclass``
-======================
-
-The ``setuptools`` class supports Python version 2.x extensions that use
-build systems based on ``setuptools``. If your recipe uses these build
-systems, the recipe needs to inherit the ``setuptools`` class.
-
 .. _ref-classes-setuptools3:
 
 ``setuptools3.bbclass``
 =======================
 
 The ``setuptools3`` class supports Python version 3.x extensions that
-use build systems based on ``setuptools3``. If your recipe uses these
+use build systems based on ``setuptools``. If your recipe uses these
 build systems, the recipe needs to inherit the ``setuptools3`` class.
 
 .. _ref-classes-sign_rpm:
diff --git a/documentation/ref-manual/migration-2.6.rst b/documentation/ref-manual/migration-2.6.rst
index 0517b0a..823d3cb 100644
--- a/documentation/ref-manual/migration-2.6.rst
+++ b/documentation/ref-manual/migration-2.6.rst
@@ -118,7 +118,7 @@ For names of recipes removed because of this repository change, see the
 ---------------------------------------------------------------------------------------------------
 
 Previously, it was possible for Python recipes that inherited the
-:ref:`distutils <ref-classes-distutils>` and
+``distutils`` and
 :ref:`distutils3 <ref-classes-distutils3>` classes to fetch code
 during the :ref:`ref-tasks-configure` task to satisfy
 dependencies mentioned in ``setup.py`` if those dependencies were not
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index e63d07b..7ae33d5 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6030,9 +6030,7 @@ system and gives an overview of their function and contents.
    :term:`PYTHON_ABI`
       When used by recipes that inherit the
       :ref:`distutils3 <ref-classes-distutils3>`,
-      :ref:`setuptools3 <ref-classes-setuptools3>`,
-      :ref:`distutils <ref-classes-distutils>`, or
-      :ref:`setuptools <ref-classes-setuptools>` classes, denotes the
+      :ref:`setuptools3 <ref-classes-setuptools3>` classes, denotes the
       Application Binary Interface (ABI) currently in use for Python. By
       default, the ABI is "m". You do not have to set this variable as the
       OpenEmbedded build system sets it for you.
@@ -6041,16 +6039,14 @@ system and gives an overview of their function and contents.
       names used when installing the Python headers and libraries in
       sysroot (e.g. ``.../python3.3m/...``).
 
-      Recipes that inherit the ``distutils`` class during cross-builds also
+      Recipes that inherit the ``distutils3`` class during cross-builds also
       use this variable to locate the headers and libraries of the
       appropriate Python that the extension is targeting.
 
    :term:`PYTHON_PN`
       When used by recipes that inherit the
       `distutils3 <ref-classes-distutils3>`,
-      :ref:`setuptools3 <ref-classes-setuptools3>`,
-      :ref:`distutils <ref-classes-distutils>`, or
-      :ref:`setuptools <ref-classes-setuptools>` classes, specifies the
+      :ref:`setuptools3 <ref-classes-setuptools3>` classes, specifies the
       major Python version being built. For Python 3.x, ``PYTHON_PN`` would
       be "python3". You do not have to set this variable as the
       OpenEmbedded build system automatically sets it for you.
-- 
1.8.3.1

[PATCH v2 08/14] ref-manual: add passwd-expire to EXTRA_USERS_PARAMS

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Add a reference to the recently added passwd-expire command in
EXTRA_USERS_PARAMS.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 7ae33d5..ca24471 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -2293,6 +2293,17 @@ system and gives an overview of their function and contents.
          # usermod -s /bin/sh tester; \
          # "
 
+      Additionally there is a special ``passwd-expire`` command that will
+      cause the password for a user to be expired and thus force changing it
+      on first login, for example::
+
+         EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;"
+
+      .. note::
+
+         At present, ``passwd-expire`` may only work for remote logins when
+         using OpenSSH and not dropbear as an SSH server.
+
    :term:`FEATURE_PACKAGES`
       Defines one or more packages to include in an image when a specific
       item is included in :term:`IMAGE_FEATURES`.
-- 
1.8.3.1

[PATCH v2 09/14] ref-manual: add FIT_KERNEL_COMP_ALG*

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Add FIT_KERNEL_COMP_ALG and FIT_KERNEL_COMP_ALG_EXTENSION. Examining
OE-Core commit 5c72105e2973e613b5c0f0e6310ffdea6e56c6c7 and the
associated code, these do not enable arbitrary selection of compression
algorithm - only disabling compression - so document them accordingly.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index ca24471..aab062b 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -2580,6 +2580,16 @@ system and gives an overview of their function and contents.
    :term:`FIT_HASH_ALG`
       Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
 
+   :term:`FIT_KERNEL_COMP_ALG`
+      Compression algorithm to use for the kernel image inside the FIT Image.
+      At present, the only supported values are "gzip" (default) or "none"
+      If you set this variable to anything other than "none" you may also need
+      to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`.
+
+   :term:`FIT_KERNEL_COMP_ALG_EXTENSION`
+      File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default
+      value is ".gz".
+
    :term:`FIT_KEY_GENRSA_ARGS`
       Arguments to openssl genrsa for generating RSA private key for signing
       fitImage. The default value is "-F4". i.e. the public exponent 65537 to
-- 
1.8.3.1

[PATCH v2 10/14] ref-manual: fix reference to build-essential

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

This has been here since the text was added to the DocBook version.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/system-requirements.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
index dc619ce..2e2d0d3 100644
--- a/documentation/ref-manual/system-requirements.rst
+++ b/documentation/ref-manual/system-requirements.rst
@@ -274,7 +274,8 @@ version requirement for gcc:
 
 If your host development system does not meet this requirement, you can
 resolve this by installing a ``buildtools-extended`` tarball that
-contains additional tools, the equivalent of ``buildtools-essential``.
+contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential``
+package.
 
 Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script
 --------------------------------------------------------------------------------
-- 
1.8.3.1

[PATCH v2 11/14] ref-manual: tweak buildtools section

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Add a joining paragraph and fix the second section so that it makes
sense with the addition of the first one.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/system-requirements.rst | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
index 2e2d0d3..80378ce 100644
--- a/documentation/ref-manual/system-requirements.rst
+++ b/documentation/ref-manual/system-requirements.rst
@@ -277,6 +277,9 @@ resolve this by installing a ``buildtools-extended`` tarball that
 contains additional tools, the equivalent of the Debian/Ubuntu ``build-essential``
 package.
 
+In the sections that follow, three different methods will be described for
+installing the ``buildtools`` or ``buildtools-extended`` toolset.
+
 Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script
 --------------------------------------------------------------------------------
 
@@ -332,8 +335,9 @@ installer and automatically installs the tools for you:
 Downloading a Pre-Built ``buildtools`` Tarball
 ----------------------------------------------
 
-Downloading and running a pre-built buildtools installer is the easiest
-of the two methods by which you can get these tools:
+If you would prefer not to use the ``install-buildtools`` script, you can instead
+download and run a pre-built buildtools installer yourself with the following
+steps:
 
 1. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/
 
-- 
1.8.3.1

[PATCH v2 12/14] ref-manual: add migration section for 3.3 release

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/migration-3.3.rst | 139 +++++++++++++++++++++++++++++
 documentation/ref-manual/migration.rst     |   1 +
 2 files changed, 140 insertions(+)
 create mode 100644 documentation/ref-manual/migration-3.3.rst

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

[PATCH v2 13/14] ref-manual: migration guide: add release codenames

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

People will see release codenames in other contexts, and thus it is
useful to mention them explicitly here rather than having to go to the
Releases wiki page to map version number to release codename.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/migration-1.3.rst | 6 +++---
 documentation/ref-manual/migration-1.4.rst | 6 +++---
 documentation/ref-manual/migration-1.5.rst | 6 +++---
 documentation/ref-manual/migration-1.6.rst | 6 +++---
 documentation/ref-manual/migration-1.7.rst | 6 +++---
 documentation/ref-manual/migration-1.8.rst | 6 +++---
 documentation/ref-manual/migration-2.0.rst | 6 +++---
 documentation/ref-manual/migration-2.1.rst | 6 +++---
 documentation/ref-manual/migration-2.2.rst | 6 +++---
 documentation/ref-manual/migration-2.3.rst | 6 +++---
 documentation/ref-manual/migration-2.4.rst | 6 +++---
 documentation/ref-manual/migration-2.5.rst | 6 +++---
 documentation/ref-manual/migration-2.6.rst | 6 +++---
 documentation/ref-manual/migration-2.7.rst | 6 +++---
 documentation/ref-manual/migration-3.0.rst | 6 +++---
 documentation/ref-manual/migration-3.1.rst | 6 +++---
 documentation/ref-manual/migration-3.2.rst | 6 +++---
 documentation/ref-manual/migration-3.3.rst | 6 +++---
 18 files changed, 54 insertions(+), 54 deletions(-)

diff --git a/documentation/ref-manual/migration-1.3.rst b/documentation/ref-manual/migration-1.3.rst
index 12e225b..0929f49 100644
--- a/documentation/ref-manual/migration-1.3.rst
+++ b/documentation/ref-manual/migration-1.3.rst
@@ -1,10 +1,10 @@
 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
 
-Moving to the Yocto Project 1.3 Release
-=======================================
+Moving to the Yocto Project 1.3 Release (danny)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.3 Release from the prior release.
+Project 1.3 Release (codename "danny") from the prior release.
 
 .. _1.3-local-configuration:
 
diff --git a/documentation/ref-manual/migration-1.4.rst b/documentation/ref-manual/migration-1.4.rst
index 0b7e861..f5fac7a 100644
--- a/documentation/ref-manual/migration-1.4.rst
+++ b/documentation/ref-manual/migration-1.4.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.4 Release
-=======================================
+Moving to the Yocto Project 1.4 Release (dylan)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.4 Release from the prior release.
+Project 1.4 Release (codename "dylan") from the prior release.
 
 .. _migration-1.4-bitbake:
 
diff --git a/documentation/ref-manual/migration-1.5.rst b/documentation/ref-manual/migration-1.5.rst
index 2d638f9..c772e51 100644
--- a/documentation/ref-manual/migration-1.5.rst
+++ b/documentation/ref-manual/migration-1.5.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.5 Release
-=======================================
+Moving to the Yocto Project 1.5 Release (dora)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.5 Release from the prior release.
+Project 1.5 Release (codename "dora") from the prior release.
 
 .. _migration-1.5-host-dependency-changes:
 
diff --git a/documentation/ref-manual/migration-1.6.rst b/documentation/ref-manual/migration-1.6.rst
index ed155d0..4c6afab 100644
--- a/documentation/ref-manual/migration-1.6.rst
+++ b/documentation/ref-manual/migration-1.6.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.6 Release
-=======================================
+Moving to the Yocto Project 1.6 Release (daisy)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.6 Release from the prior release.
+Project 1.6 Release (codename "daisy") from the prior release.
 
 .. _migration-1.6-archiver-class:
 
diff --git a/documentation/ref-manual/migration-1.7.rst b/documentation/ref-manual/migration-1.7.rst
index c00768c..9cf467f 100644
--- a/documentation/ref-manual/migration-1.7.rst
+++ b/documentation/ref-manual/migration-1.7.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.7 Release
-=======================================
+Moving to the Yocto Project 1.7 Release (dizzy)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.7 Release from the prior release.
+Project 1.7 Release (codename "dizzy") from the prior release.
 
 .. _migration-1.7-changes-to-setting-qemu-packageconfig-options:
 
diff --git a/documentation/ref-manual/migration-1.8.rst b/documentation/ref-manual/migration-1.8.rst
index 73789bd..ec2b138 100644
--- a/documentation/ref-manual/migration-1.8.rst
+++ b/documentation/ref-manual/migration-1.8.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 1.8 Release
-=======================================
+Moving to the Yocto Project 1.8 Release (fido)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 1.8 Release from the prior release.
+Project 1.8 Release (codename "fido") from the prior release.
 
 .. _migration-1.8-removed-recipes:
 
diff --git a/documentation/ref-manual/migration-2.0.rst b/documentation/ref-manual/migration-2.0.rst
index 4eea948..9da60df 100644
--- a/documentation/ref-manual/migration-2.0.rst
+++ b/documentation/ref-manual/migration-2.0.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.0 Release
-=======================================
+Moving to the Yocto Project 2.0 Release (jethro)
+================================================
 
 This section provides migration information for moving to the Yocto
-Project 2.0 Release from the prior release.
+Project 2.0 Release (codename "jethro") from the prior release.
 
 .. _migration-2.0-gcc-5:
 
diff --git a/documentation/ref-manual/migration-2.1.rst b/documentation/ref-manual/migration-2.1.rst
index b7bac0c..1eb9ab5 100644
--- a/documentation/ref-manual/migration-2.1.rst
+++ b/documentation/ref-manual/migration-2.1.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.1 Release
-=======================================
+Moving to the Yocto Project 2.1 Release (krogoth)
+=================================================
 
 This section provides migration information for moving to the Yocto
-Project 2.1 Release from the prior release.
+Project 2.1 Release (codename "krogoth") from the prior release.
 
 .. _migration-2.1-variable-expansion-in-python-functions:
 
diff --git a/documentation/ref-manual/migration-2.2.rst b/documentation/ref-manual/migration-2.2.rst
index 8b3c5d6..198181a 100644
--- a/documentation/ref-manual/migration-2.2.rst
+++ b/documentation/ref-manual/migration-2.2.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.2 Release
-=======================================
+Moving to the Yocto Project 2.2 Release (morty)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.2 Release from the prior release.
+Project 2.2 Release (codename "morty") from the prior release.
 
 .. _migration-2.2-minimum-kernel-version:
 
diff --git a/documentation/ref-manual/migration-2.3.rst b/documentation/ref-manual/migration-2.3.rst
index 04b11da..0541eb3 100644
--- a/documentation/ref-manual/migration-2.3.rst
+++ b/documentation/ref-manual/migration-2.3.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.3 Release
-=======================================
+Moving to the Yocto Project 2.3 Release (pyro)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.3 Release from the prior release.
+Project 2.3 Release (codename "pyro") from the prior release.
 
 .. _migration-2.3-recipe-specific-sysroots:
 
diff --git a/documentation/ref-manual/migration-2.4.rst b/documentation/ref-manual/migration-2.4.rst
index 260b320..2ba17e0 100644
--- a/documentation/ref-manual/migration-2.4.rst
+++ b/documentation/ref-manual/migration-2.4.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.4 Release
-=======================================
+Moving to the Yocto Project 2.4 Release (rocko)
+===============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.4 Release from the prior release.
+Project 2.4 Release (codename "rocko") from the prior release.
 
 .. _migration-2.4-memory-resident-mode:
 
diff --git a/documentation/ref-manual/migration-2.5.rst b/documentation/ref-manual/migration-2.5.rst
index 9f45ffc..9ef4b55 100644
--- a/documentation/ref-manual/migration-2.5.rst
+++ b/documentation/ref-manual/migration-2.5.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.5 Release
-=======================================
+Moving to the Yocto Project 2.5 Release (sumo)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.5 Release from the prior release.
+Project 2.5 Release (codename "sumo") from the prior release.
 
 .. _migration-2.5-packaging-changes:
 
diff --git a/documentation/ref-manual/migration-2.6.rst b/documentation/ref-manual/migration-2.6.rst
index 823d3cb..aeac509 100644
--- a/documentation/ref-manual/migration-2.6.rst
+++ b/documentation/ref-manual/migration-2.6.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.6 Release
-=======================================
+Moving to the Yocto Project 2.6 Release (thud)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 2.6 Release from the prior release.
+Project 2.6 Release (codename "thud") from the prior release.
 
 .. _migration-2.6-gcc-changes:
 
diff --git a/documentation/ref-manual/migration-2.7.rst b/documentation/ref-manual/migration-2.7.rst
index 5af5947..1be4d5d 100644
--- a/documentation/ref-manual/migration-2.7.rst
+++ b/documentation/ref-manual/migration-2.7.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 2.7 Release
-=======================================
+Moving to the Yocto Project 2.7 Release (warrior)
+=================================================
 
 This section provides migration information for moving to the Yocto
-Project 2.7 Release from the prior release.
+Project 2.7 Release (codename "warrior") from the prior release.
 
 .. _migration-2.7-bitbake-changes:
 
diff --git a/documentation/ref-manual/migration-3.0.rst b/documentation/ref-manual/migration-3.0.rst
index 7ef2742..f3d20e2 100644
--- a/documentation/ref-manual/migration-3.0.rst
+++ b/documentation/ref-manual/migration-3.0.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 3.0 Release
-=======================================
+Moving to the Yocto Project 3.0 Release (zeus)
+==============================================
 
 This section provides migration information for moving to the Yocto
-Project 3.0 Release from the prior release.
+Project 3.0 Release (codename "zeus") from the prior release.
 
 .. _migration-3.0-init-system-selection:
 
diff --git a/documentation/ref-manual/migration-3.1.rst b/documentation/ref-manual/migration-3.1.rst
index 4fcd249..84d3250 100644
--- a/documentation/ref-manual/migration-3.1.rst
+++ b/documentation/ref-manual/migration-3.1.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 3.1 Release
-=======================================
+Moving to the Yocto Project 3.1 Release (dunfell)
+=================================================
 
 This section provides migration information for moving to the Yocto
-Project 3.1 Release from the prior release.
+Project 3.1 Release (codename "dunfell") from the prior release.
 
 .. _migration-3.1-minimum-system-requirements:
 
diff --git a/documentation/ref-manual/migration-3.2.rst b/documentation/ref-manual/migration-3.2.rst
index cca8124..39743af 100644
--- a/documentation/ref-manual/migration-3.2.rst
+++ b/documentation/ref-manual/migration-3.2.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 3.2 Release
-=======================================
+Moving to the Yocto Project 3.2 Release (gatesgarth)
+====================================================
 
 This section provides migration information for moving to the Yocto
-Project 3.2 Release from the prior release.
+Project 3.2 Release (codename "gatesgarth") from the prior release.
 
 .. _migration-3.2-minimum-system-requirements:
 
diff --git a/documentation/ref-manual/migration-3.3.rst b/documentation/ref-manual/migration-3.3.rst
index dcd7b56..db1619e 100644
--- a/documentation/ref-manual/migration-3.3.rst
+++ b/documentation/ref-manual/migration-3.3.rst
@@ -1,8 +1,8 @@
-Moving to the Yocto Project 3.3 Release
-=======================================
+Moving to the Yocto Project 3.3 Release (hardknott)
+===================================================
 
 This section provides migration information for moving to the Yocto
-Project 3.3 Release from the prior release.
+Project 3.3 Release (codename "hardknott") from the prior release.
 
 
 .. _migration-3.3-minimum-system-requirements:
-- 
1.8.3.1

[PATCH v2 14/14] ref-manual: add mention of DISTUTILS_SETUP_PATH

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Add a variable glossary entry and corresponding 3.3 migration
section entry for DISTUTILS_SETUP_PATH.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/migration-3.3.rst | 29 +++++++++++++++++++++++++++++
 documentation/ref-manual/variables.rst     | 13 +++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/documentation/ref-manual/migration-3.3.rst b/documentation/ref-manual/migration-3.3.rst
index db1619e..4fb51a3 100644
--- a/documentation/ref-manual/migration-3.3.rst
+++ b/documentation/ref-manual/migration-3.3.rst
@@ -74,6 +74,35 @@ Some example recipes where this change has been made: ``gpgme``, ``libcap-ng``,
 ``python3-pycairo``.
 
 
+.. _migration-3.3-distutils-path:
+
+``setup.py`` path for python modules
+------------------------------------
+
+In a Python module, sometimes ``setup.py`` can be buried deep in the
+source tree. Previously this was handled in recipes by setting :term:`S` to
+point to the subdirectory within the source where ``setup.py`` is located.
+However with the recent :ref:`pseudo <overview-manual/concepts:fakeroot and pseudo>`
+changes, some Python modules make changes to files beneath ``${S}``, for
+example::
+
+   S = "${WORKDIR}/git/python/pythonmodule"
+
+then in ``setup.py`` it works with source code in a relative fashion, such
+as ``../../src``. This causes pseudo to abort as it isn't able to track
+the paths properly. This release introduces a new :term:`DISTUTILS_SETUP_PATH`
+variable so that recipes can specify it explicitly, for example::
+
+   S = "${WORKDIR}/git"
+   DISTUTILS_SETUP_PATH = "${S}/python/pythonmodule"
+
+Recipes that inherit from :ref:`distutils3 <ref-classes-distutils3>` (or
+:ref:`setuptools3 <ref-classes-setuptools3>` which itself inherits
+:ref:`distutils3 <ref-classes-distutils3>`) that also set :term:`S` to
+point to a Python module within a subdirectory in the aforementioned
+manner should be changed to set :term:`DISTUTILS_SETUP_PATH` instead.
+
+
 .. _migration-3.3-bitbake:
 
 BitBake changes
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index aab062b..ea0fa2d 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -1978,6 +1978,19 @@ system and gives an overview of their function and contents.
       is included in the default value of
       :term:`OVERRIDES`.
 
+   :term:`DISTUTILS_SETUP_PATH`
+      When used by recipes that inherit the
+      :ref:`distutils3 <ref-classes-distutils3>` or
+      :ref:`setuptools3 <ref-classes-setuptools3>` class, this variable should
+      be used to specify the directory in which the ``setup.py`` file is
+      located if it is not at the root of the source tree (as specified by
+      :term:`S`). For example, in a recipe where the sources are fetched from
+      a Git repository and ``setup.py`` is in a ``python/pythonmodule``
+      subdirectory, you would have this::
+
+         S = "${WORKDIR}/git"
+         DISTUTILS_SETUP_PATH = "${S}/python/pythonmodule"
+
    :term:`DL_DIR`
       The central download directory used by the build process to store
       downloads. By default, ``DL_DIR`` gets files suitable for mirroring
-- 
1.8.3.1

Re: [docs] [PATCH v2 05/14] ref-manual: and SDK_CUSTOM_TEMPLATECONF to glossary

[Paul Eggleton]

On Thursday, 15 April 2021 21:59:03 NZST Paul Eggleton wrote:
> +   :term:`SDK_CUSTOM_TEMPLATECONF`
> +      When building the extensible SDK, if ``SDK_CUSTOM_TEMPLATECONF`` is set to
> +      "1" and a ``conf/templateconf.conf`` file exists in the build directory
> +      (``TOPDIR``) then this will be copied into the SDK.

Just realised I forgot to fix the TOPDIR reference here as pointed out by
Quentin. I've pushed a new branch with that fixed.

Cheers
Paul