diff options
authorPaul Eggleton <>2021-04-15 21:46:06 +1200
committerRichard Purdie <>2021-04-15 20:18:58 +0100
commit1203d1f24d51316ff693556a2d36e1fd71789865 (patch)
parent34a72cf61389eb0bed05953ecf72fab8c75d580c (diff)
ref-manual: add mention of DISTUTILS_SETUP_PATH
Add a variable glossary entry and corresponding 3.3 migration section entry for DISTUTILS_SETUP_PATH. (From yocto-docs rev: 0823237e6f4b9dbdf48500b3c1e8cc61696fa2d2) Signed-off-by: Paul Eggleton <> Signed-off-by: Richard Purdie <>
2 files changed, 42 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration-3.3.rst b/documentation/ref-manual/migration-3.3.rst
index db1619e627..4fb51a39dc 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``,
+.. _migration-3.3-distutils-path:
+```` path for python modules
+In a Python module, sometimes ```` 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 ```` 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
+ S = "${WORKDIR}/git/python/pythonmodule"
+then in ```` 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 8f059650d3..74ac12bf98 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
+ 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 ```` 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 ```` is in a ``python/pythonmodule``
+ subdirectory, you would have this::
+ S = "${WORKDIR}/git"
+ DISTUTILS_SETUP_PATH = "${S}/python/pythonmodule"
The central download directory used by the build process to store
downloads. By default, ``DL_DIR`` gets files suitable for mirroring