Merge pull request #1326 from zooba/patch-1

Update Choosing a build backend section

Author: webknjaz

source/tutorials/packaging-projects.rst

@@ -103,15 +103,18 @@ Creating a test directory
 :file:`tests/` is a placeholder for test files. Leave it empty for now.
 
 
-Creating pyproject.toml
------------------------
+Choosing a build backend
+------------------------
+
+Tools like :ref:`pip` and :ref:`build` do not actually convert your sources
+into a :term:`distribution package <Distribution Package>` (like a wheel); 
+that job is performed by a *build backend*. The build backend determines how
+your project will specify its configuration, including metadata (information
+about the project, for example, the name and tags that are displayed on PyPI)
+and input files. Build backends have different levels of functionality, such as
+whether they support building :term:`extension modules <Extension Module>`, and
+you should choose one that suits your needs and preferences.
 
-.. TODO: Add an intro sentence about pyproject.toml, and a sub-heading for
-   "Configuring build tools"
-
-:file:`pyproject.toml` tells "frontend" build tools like :ref:`pip` and
-:ref:`build` what "backend" tool to use to create
-:term:`distribution packages <Distribution Package>` for your project.
 You can choose from a number of backends; this tutorial uses :ref:`Hatchling
 <hatch>` by default, but it will work identically with :ref:`setuptools`,
 :ref:`Flit <flit>`, :ref:`PDM <pdm>`, and others that support the ``[project]``
@@ -124,7 +127,10 @@ table for :ref:`metadata <configuring metadata>`.
    management, as well as building, uploading, and installing packages. This
    tutorial uses single-purpose tools that work independently.
 
-Open :file:`pyproject.toml` and enter one of these ``[build-system]`` tables:
+The :file:`pyproject.toml` tells "front end" build tools like :ref:`pip` and
+:ref:`build` which backend to use for your project. Below are some
+examples for common build backends, but check your backend's own documentation
+for more details.
 
 .. tab:: Hatchling
 
@@ -159,14 +165,26 @@ Open :file:`pyproject.toml` and enter one of these ``[build-system]`` tables:
         build-backend = "pdm.backend"
 
 
-- ``requires`` is a list of packages that are needed to build your package. You
-  don't need to install them; build frontends like :ref:`pip` will install them
-  automatically in a temporary, isolated virtual environment for use during the
-  build process.
-- ``build-backend`` is the name of the Python object that frontends will use to
-  perform the build.
+The ``requires`` key is a list of packages that are needed to build your package.
+The frontend should install them automatically when building your package.
+Frontends usually run builds in isolated environments, so omitting dependencies
+here may cause build-time errors.
+This should always include your backend's package, and might have other build-time
+dependencies.
+
+The ``build-backend`` key is the name of the Python object that frontends will use
+to perform the build.
+
+Both of these values will be provided by the documentation for your build
+backend, or generated by its command line interface. There should be no need for
+you to customize these settings.
 
-.. TODO: Add note to check the tools' documentation for the current snippet?
+Additional configuration of the build tool will either be in a ``tool`` section
+of the ``pyproject.toml``, or in a special file defined by the build tool. For
+example, when using ``setuptools`` as your build backend, additional configuration
+may be added to a ``setup.py`` or ``setup.cfg`` file, and specifying
+``setuptools.build_meta`` in your build allows the tools to locate and use these
+automatically.
 
 .. _configuring metadata: