From 52dc3365ebb74e3002faf6ca4cc41037cad4a0f4 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 19 Nov 2021 20:24:09 +0000 Subject: Add documentation about build_meta wrappers --- docs/build_meta.rst | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 1 + 2 files changed, 78 insertions(+) (limited to 'docs') diff --git a/docs/build_meta.rst b/docs/build_meta.rst index 27df70a2..5851d965 100644 --- a/docs/build_meta.rst +++ b/docs/build_meta.rst @@ -89,3 +89,80 @@ and installed:: or:: $ pip install dist/meowpkg-0.0.1.tar.gz + +Dynamic build dependencies and other ``build_meta`` tweaks +---------------------------------------------------------- + +With the changes introduced by :pep:`517` and :pep:`518`, the +``setup_requires`` configuration field was made deprecated in ``setup.cfg`` and +``setup.py``, in favour of directly listing build dependencies in the +``requires`` field of the ``build-system`` table of ``pyproject.toml``. +This approach has a series of advantages and gives package managers and +installers the ability to inspect in advance the build requirements and +perform a series of optimisations. + +However some package authors might still need to dynamically inspect the final +users machine before deciding these requirements. One way of doing that, as +specified by :pep:`517`, is to "tweak" ``setuptools.build_meta`` by using a +:pep:`in-tree backend <517#in-tree-build-backends>`. + +If you add the following configuration to your ``pyprojec.toml``: + + +.. code-block:: toml + + [build-system] + requires = ["setuptools", "wheel"] + build-backend = "backend" + backend-path = ["_custom_build"] + + +then you should be able to implement a thin wrapper around ``build_meta`` in +the ``_custom_build/backend.py`` file, as shown in the following example: + +.. code-block:: python + + from setuptools import build_meta as _orig + + prepare_metadata_for_build_wheel = _orig.prepare_metadata_for_build_wheel + build_wheel = _orig.build_wheel + build_sdist = _orig.build_sdist + + + def get_requires_for_build_wheel(self, config_settings=None): + return _orig.get_requires_for_build_wheel(config_settings) + [...] + + + def get_requires_for_build_sdist(self, config_settings=None): + return _orig.get_requires_for_build_sdist(config_settings) + [...] + + +Note that you can override any of the functions specified in :pep:`PEP 517 +<517#build-backend-interface>`, not only the ones responsible for gathering +requirements. + +.. tip:: Make sure your backend script is included in the :doc:`source + distribution `, otherwise the build will fail. + This can be done by using a SCM_/VCS_ plugin (like :pypi:`setuptools-scm` + and :pypi:`setuptools-svn`), or by correctly setting up :ref:`MANIFEST.in + `. + + If this is the first time you are using a customised backend, please have a + look on the generated ``.tar.gz`` and ``.whl``. + On POSIX systems that can be done with ``tar -tf dist/*.tar.gz`` + and ``unzip -l dist/*.whl``. + On Windows systems you can rename the ``.whl`` to ``.zip`` to be able to + inspect it on the file explorer, and use the same ``tar`` command in a + command prompt (alternativelly there are GUI programs like `7-zip`_ that + handle ``.tar.gz``). + + In general the backend script should be present in the ``.tar.gz`` (so the + project can be build from the source) but not in the ``.whl`` (otherwise the + backend script would end up being distributed alongside your package). + See ":doc:`/userguide/package_discovery`" for more details about package + files. + + +.. _SCM: https://en.wikipedia.org/wiki/Software_configuration_management +.. _VCS: https://en.wikipedia.org/wiki/Version_control +.. _7-zip: https://www.7-zip.org diff --git a/docs/conf.py b/docs/conf.py index 3cc8e35b..38be1de5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -95,6 +95,7 @@ github_url = 'https://github.com' github_sponsors_url = f'{github_url}/sponsors' extlinks = { 'user': (f'{github_sponsors_url}/%s', '@'), # noqa: WPS323 + 'pypi': ('https://pypi.org/project/%s', '%s'), } extensions += ['sphinx.ext.extlinks'] -- cgit v1.2.1 From 7d3db3f9e6f1c6b29217a402d0294b423e1ee187 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 19 Nov 2021 20:49:06 +0000 Subject: Mention environment markers as alternative --- docs/build_meta.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/build_meta.rst b/docs/build_meta.rst index 5851d965..3c236d68 100644 --- a/docs/build_meta.rst +++ b/docs/build_meta.rst @@ -106,6 +106,11 @@ users machine before deciding these requirements. One way of doing that, as specified by :pep:`517`, is to "tweak" ``setuptools.build_meta`` by using a :pep:`in-tree backend <517#in-tree-build-backends>`. +.. tip:: Before implementing a *in-tree* backend, have a look on + :pep:`PEP 508 <508#environment-markers>`. Most of the times, dependencies + with **environment markers** are enough to differentiate operating systems + and platforms. + If you add the following configuration to your ``pyprojec.toml``: @@ -141,7 +146,7 @@ Note that you can override any of the functions specified in :pep:`PEP 517 <517#build-backend-interface>`, not only the ones responsible for gathering requirements. -.. tip:: Make sure your backend script is included in the :doc:`source +.. important:: Make sure your backend script is included in the :doc:`source distribution `, otherwise the build will fail. This can be done by using a SCM_/VCS_ plugin (like :pypi:`setuptools-scm` and :pypi:`setuptools-svn`), or by correctly setting up :ref:`MANIFEST.in -- cgit v1.2.1