Merge pull request #2897 from abravalheri/improve-docs

Docs: Add instructions about `build_meta` wrappers as alternative to dynamic `setup_requires`

2 files changed, 83 insertions, 0 deletions

diff --git a/docs/build_meta.rst b/docs/build_meta.rst
index a14a5843..1337bddb 100644
--- a/docs/build_meta.rst
+++ b/docs/build_meta.rst
@@ -90,3 +90,85 @@ 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>`.
+
+.. 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``:
+
+
+.. 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.
+
+.. important:: Make sure your backend script is included in the :doc:`source
+   distribution </userguide/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
+   <manifest>`.
+
+   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 1fb27716..bfd45a69 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -96,6 +96,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']