From patchwork Mon Mar 21 15:09:27 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ross Burton X-Patchwork-Id: 5601 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id F338FC433F5 for ; Mon, 21 Mar 2022 15:09:30 +0000 (UTC) Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by mx.groups.io with SMTP id smtpd.web08.31760.1647875369634738072 for ; Mon, 21 Mar 2022 08:09:30 -0700 Authentication-Results: mx.groups.io; dkim=missing; spf=pass (domain: arm.com, ip: 217.140.110.172, mailfrom: ross.burton@arm.com) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 434F01042 for ; Mon, 21 Mar 2022 08:09:29 -0700 (PDT) Received: from oss-tx204.lab.cambridge.arm.com (usa-sjc-imap-foss1.foss.arm.com [10.121.207.14]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id E9F4A3F73D for ; Mon, 21 Mar 2022 08:09:28 -0700 (PDT) From: Ross Burton To: docs@lists.yoctoproject.org Subject: [PATCH v2] ref-manual: update Python class documentation Date: Mon, 21 Mar 2022 15:09:27 +0000 Message-Id: <20220321150927.3355757-1-ross.burton@arm.com> X-Mailer: git-send-email 2.25.1 MIME-Version: 1.0 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Mon, 21 Mar 2022 15:09:30 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/2651 Add new PEP517_* variables, remove obsolete variables, and update for renamed classes. Signed-off-by: Ross Burton Reviewed-by: Michael Opdenacker --- documentation/ref-manual/classes.rst | 71 +++++++++++++++----------- documentation/ref-manual/variables.rst | 11 ++-- 2 files changed, 46 insertions(+), 36 deletions(-) diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 4dd09016233..6ba792d3f9a 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -602,22 +602,6 @@ variables are not met, the recipe will be skipped, and if the build system attempts to build the recipe then an error will be triggered. -.. _ref-classes-flit_core: - -``flit_core.bbclass`` -===================== - -The ``flit_core`` class enables building Python modules which declare -the `PEP-517 `__ compliant -``flit_core.buildapi`` ``build-backend`` in the ``[build-system]`` -section of ``pyproject.toml`` (See `PEP-518 `__). - -Python modules built with ``flit_core.buildapi`` are pure Python (no -``C`` or ``Rust`` extensions). - -The resulting ``wheel`` (See `PEP-427 `__) -is installed with the :ref:`python_pep517 ` class. - .. _ref-classes-fontcache: ``fontcache.bbclass`` @@ -1978,20 +1962,48 @@ When inherited by a recipe, the ``perlnative`` class supports using the native version of Perl built by the build system rather than using the version provided by the build host. +.. _ref-classes-python_flit_core: + +``python_flit_core.bbclass`` +============================ + +The ``python_flit_core`` class enables building Python modules which declare +the `PEP-517 `__ compliant +``flit_core.buildapi`` ``build-backend`` in the ``[build-system]`` +section of ``pyproject.toml`` (See `PEP-518 `__). + +Python modules built with ``flit_core.buildapi`` are pure Python (no +``C`` or ``Rust`` extensions). + +Internally this uses the :ref:`python_pep517 ` class. + .. _ref-classes-python_pep517: ``python_pep517.bbclass`` -============================= +========================= + +The ``python_pep517`` class builds and installs a Python ``wheel`` binary +archive (see `PEP-517 `__). -The ``python_pep517`` class installs a Python ``wheel`` binary archive (see -`PEP-517 `__). +Recipes wouldn't inherit this directly, instead typically another class will +inherit this, add the relevant native dependencies, and set +:term:`PEP517_BUILD_API` to the Python class which implements the PEP-517 build +API. -The Python ``wheel`` can be built with several classes, including :ref:`flit_core `, -:ref:`setuptools_build_meta `, and :ref:`setuptools3 `. +Examples of classes which do this are :ref:`python_flit_core +`, :ref:`python_setuptools_build_meta +`, and :ref:`python_poetry_core +`. -The path to the wheel to be installed is defined by :term:`PEP517_WHEEL_PATH`. -This defaults to ``${D}/dist`` and should be respected by the builder class -(such as :ref:`flit_core `). +.. _ref-classes-python_poetry_core: + +``python_poetry_core.bbclass`` +============================== + +The ``python_poetry_core`` class enables building Python modules which use the +`Poetry Core `__ build system. + +Internally this uses the :ref:`python_pep517 ` class. .. _ref-classes-pixbufcache: @@ -2348,12 +2360,12 @@ 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_build_meta: +.. _ref-classes-python_setuptools_build_meta: -``setuptools_build_meta.bbclass`` -================================= +``python_setuptools_build_meta.bbclass`` +======================================== -The ``setuptools_build_meta`` class enables building Python modules which +The ``python_setuptools_build_meta`` class enables building Python modules which declare the `PEP-517 `__ compliant ``setuptools.build_meta`` ``build-backend`` in the ``[build-system]`` @@ -2362,8 +2374,7 @@ section of ``pyproject.toml`` (See `PEP-518 `__) -is installed with the :ref:`python_pep517 ` class. +Internally this uses the :ref:`python_pep517 ` class. .. _ref-classes-setuptools3: diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 634f19a6733..781cd19765e 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -5632,6 +5632,11 @@ system and gives an overview of their function and contents. :term:`PE` is the default value of the :term:`PKGE` variable. + :term:`PEP517_BUILD_API` + When used by recipes that inherit the :ref:`python_pep517 + ` class, specifies the entry point to the + PEP-517 compliant build API (such as ``flit_core.buildapi``). + :term:`PEP517_WHEEL_PATH` When used by recipes that inherit the :ref:`python_pep517 ` class, @@ -5644,12 +5649,6 @@ system and gives an overview of their function and contents. ``bash-4.2-r1/``). This variable is comprised of the following: ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`} - :term:`PIP_INSTALL_ARGS` - When used by recipes that inherit the - :ref:`python_pep517 ` class, - denotes the arguments passed to ``pip install`` to adjust the - behavior of how the ``wheel`` is installed. - :term:`PIXBUF_PACKAGES` When inheriting the :ref:`pixbufcache ` class, this variable identifies packages that contain the pixbuf