summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRoss Burton <ross@burtonini.com>2022-03-14 17:07:50 +0000
committerRichard Purdie <richard.purdie@linuxfoundation.org>2022-03-16 14:25:02 +0000
commit4b15900ee056977393db290d8980bb330b2bc67e (patch)
tree0e249dea6acb08969044d0be241e25e6bb9034bd
parente3b7a5ba49416fbc30c4c8892c705baa25029f9a (diff)
downloadpoky-4b15900ee056977393db290d8980bb330b2bc67e.tar.gz
Update documentation for Python packaging changes
A number of classes and variables have been renamed, so update the documentation as needed. (From yocto-docs rev: 35b2e1757f5f2f09bb899ed24ffea50e5041b471) Signed-off-by: Ross Burton <ross.burton@arm.com> Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/ref-manual/classes.rst45
-rw-r--r--documentation/ref-manual/variables.rst28
2 files changed, 35 insertions, 38 deletions
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index e26e4343a1..4dd0901623 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -616,7 +616,7 @@ Python modules built with ``flit_core.buildapi`` are pure Python (no
616``C`` or ``Rust`` extensions). 616``C`` or ``Rust`` extensions).
617 617
618The resulting ``wheel`` (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__) 618The resulting ``wheel`` (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__)
619is installed with the :ref:`pip_install_wheel <ref-classes-pip_install_wheel>` class. 619is installed with the :ref:`python_pep517 <ref-classes-python_pep517>` class.
620 620
621.. _ref-classes-fontcache: 621.. _ref-classes-fontcache:
622 622
@@ -1978,25 +1978,20 @@ When inherited by a recipe, the ``perlnative`` class supports using the
1978native version of Perl built by the build system rather than using the 1978native version of Perl built by the build system rather than using the
1979version provided by the build host. 1979version provided by the build host.
1980 1980
1981.. _ref-classes-pip_install_wheel: 1981.. _ref-classes-python_pep517:
1982 1982
1983``pip_install_wheel.bbclass`` 1983``python_pep517.bbclass``
1984============================= 1984=============================
1985 1985
1986The ``pip_install_wheel`` class uses ``pip`` to install a Python ``wheel`` 1986The ``python_pep517`` class installs a Python ``wheel`` binary archive (see
1987binary archive format (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__) 1987`PEP-517 <https://peps.python.org/pep-0517/>`__).
1988 1988
1989The Python ``wheel`` can be built with several classes, including :ref:`flit_core <ref-classes-flit_core>`, 1989The Python ``wheel`` can be built with several classes, including :ref:`flit_core <ref-classes-flit_core>`,
1990:ref:`setuptools_build_meta <ref-classes-setuptools_build_meta>`, and :ref:`setuptools3 <ref-classes-setuptools3>`. 1990:ref:`setuptools_build_meta <ref-classes-setuptools_build_meta>`, and :ref:`setuptools3 <ref-classes-setuptools3>`.
1991 1991
1992The absolute path to the built ``wheel`` to be installed is defined by :term:`PYPA_WHEEL` which can be 1992The path to the wheel to be installed is defined by :term:`PEP517_WHEEL_PATH`.
1993overriden for recipes where the filename or version number of the wheel are not easily 1993This defaults to ``${D}/dist`` and should be respected by the builder class
1994determined by the defaults. Other variables which can be used to customize the behavior 1994(such as :ref:`flit_core <ref-classes-flit_core>`).
1995of the ``pip_install_wheel`` class include:
1996
1997- :term:`PIP_INSTALL_ARGS`
1998- :term:`PIP_INSTALL_PACKAGE`
1999- :term:`PIP_INSTALL_DIST_PATH`
2000 1995
2001.. _ref-classes-pixbufcache: 1996.. _ref-classes-pixbufcache:
2002 1997
@@ -2368,7 +2363,7 @@ Python modules built with ``setuptools.build_meta`` can be pure Python or
2368include ``C`` or ``Rust`` extensions). 2363include ``C`` or ``Rust`` extensions).
2369 2364
2370The resulting ``wheel`` (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__) 2365The resulting ``wheel`` (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__)
2371is installed with the :ref:`pip_install_wheel <ref-classes-pip_install_wheel>` class. 2366is installed with the :ref:`python_pep517 <ref-classes-python_pep517>` class.
2372 2367
2373.. _ref-classes-setuptools3: 2368.. _ref-classes-setuptools3:
2374 2369
@@ -2393,9 +2388,25 @@ uses these build systems, the recipe needs to inherit the ``setuptools3`` class.
2393 2388
2394 .. note:: 2389 .. note::
2395 2390
2396 The ``setuptools3`` class ``do_install()`` task now calls ``pip install`` 2391 The ``setuptools3`` class ``do_install()`` task now installs the ``wheel``
2397 to install the ``wheel`` binary archive. In current versions of 2392 binary archive. In current versions of ``setuptools`` the legacy ``setup.py
2398 ``setuptools`` the legacy ``setup.py install`` method is deprecated. 2393 install`` method is deprecated. If the ``setup.py`` cannot be used with
2394 wheels, for example it creates files outside of the Python module or
2395 standard entry points, then :ref:`setuptools3_legacy
2396 <ref-classes-setuptools3_legacy>` should be used.
2397
2398.. _ref-classes-setuptools3_legacy:
2399
2400``setuptools3_legacy.bbclass``
2401==============================
2402
2403The ``setuptools3_legacy`` class supports Python version 3.x extensions that use
2404build systems based on ``setuptools`` (e.g. only have a ``setup.py`` and have
2405not migrated to the official ``pyproject.toml`` format). Unlike
2406``setuptools3.bbclass``, this uses the traditional ``setup.py`` ``build`` and
2407``install`` commands and not wheels. This use of ``setuptools`` like this is
2408`deprecated <https://github.com/pypa/setuptools/blob/main/CHANGES.rst#v5830>`_
2409but still relatively common.
2399 2410
2400.. _ref-classes-setuptools3-base: 2411.. _ref-classes-setuptools3-base:
2401 2412
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 81a6a0b240..6a4d3fcc3c 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -5569,6 +5569,12 @@ system and gives an overview of their function and contents.
5569 5569
5570 :term:`PE` is the default value of the :term:`PKGE` variable. 5570 :term:`PE` is the default value of the :term:`PKGE` variable.
5571 5571
5572 :term:`PEP517_WHEEL_PATH`
5573 When used by recipes that inherit the
5574 :ref:`python_pep517 <ref-classes-python_pep517>` class,
5575 denotes the path to ``dist/`` (short for distribution) where the
5576 binary archive ``wheel`` is built.
5577
5572 :term:`PF` 5578 :term:`PF`
5573 Specifies the recipe or package name and includes all version and 5579 Specifies the recipe or package name and includes all version and
5574 revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and 5580 revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and
@@ -5577,23 +5583,10 @@ system and gives an overview of their function and contents.
5577 5583
5578 :term:`PIP_INSTALL_ARGS` 5584 :term:`PIP_INSTALL_ARGS`
5579 When used by recipes that inherit the 5585 When used by recipes that inherit the
5580 :ref:`pip_install_wheel <ref-classes-pip_install_wheel>` class, 5586 :ref:`python_pep517 <ref-classes-python_pep517>` class,
5581 denotes the arguments passed to ``pip install`` to adjust the 5587 denotes the arguments passed to ``pip install`` to adjust the
5582 behavior of how the ``wheel`` is installed. 5588 behavior of how the ``wheel`` is installed.
5583 5589
5584 :term:`PIP_INSTALL_DIST_PATH`
5585 When used by recipes that inherit the
5586 :ref:`pip_install_wheel <ref-classes-pip_install_wheel>` class,
5587 denotes the path to ``dist/`` (short for distribution) where the
5588 binary archive ``wheel`` is built. This is used in part to create
5589 the :term:`PYPA_WHEEL` variable.
5590
5591 :term:`PIP_INSTALL_PACKAGE`
5592 When used by recipes that inherit the
5593 :ref:`pip_install_wheel <ref-classes-pip_install_wheel>` class,
5594 denotes the name of the package portion of the ``wheel`` filename.
5595 This is used in part to create the :term:`PYPA_WHEEL` variable.
5596
5597 :term:`PIXBUF_PACKAGES` 5590 :term:`PIXBUF_PACKAGES`
5598 When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>` 5591 When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>`
5599 class, this variable identifies packages that contain the pixbuf 5592 class, this variable identifies packages that contain the pixbuf
@@ -6009,13 +6002,6 @@ system and gives an overview of their function and contents.
6009 6002
6010 :term:`PV` is the default value of the :term:`PKGV` variable. 6003 :term:`PV` is the default value of the :term:`PKGV` variable.
6011 6004
6012 :term:`PYPA_WHEEL`
6013 When used by recipes that inherit the
6014 :ref:`pip_install_wheel <ref-classes-pip_install_wheel>` class, denotes
6015 the absolute path to the built ``wheel`` to be installed. Normally the
6016 defaults which use :term:`PIP_INSTALL_PACKAGE` and :term:`PIP_INSTALL_DIST_PATH`
6017 to build the path to the ``wheel`` should be sufficient.
6018
6019 :term:`PYTHON_ABI` 6005 :term:`PYTHON_ABI`
6020 When used by recipes that inherit the 6006 When used by recipes that inherit the
6021 :ref:`setuptools3 <ref-classes-setuptools3>` class, denotes the 6007 :ref:`setuptools3 <ref-classes-setuptools3>` class, denotes the