@@ -103,15 +103,17 @@ Creating a test directory
103103:file: `tests/ ` is a placeholder for test files. Leave it empty for now.
104104
105105
106- Creating pyproject.toml
106+ Choosing a build backend
107107-----------------------
108108
109- .. TODO: Add an intro sentence about pyproject.toml, and a sub-heading for
110- "Configuring build tools"
109+ Tools like :ref: `pip ` and :ref: `build ` do not actually convert your sources
110+ into a :term: `distribution package <Distribution Package> `;
111+ that job is performed by a _build backend _. The build backend determines how
112+ your project will specify its configuration, including metadata (information
113+ about the project, for example, the name and tags that are displayed on PyPI)
114+ and input files. Build backends have different levels of functionality, and
115+ you should choose one that suits your needs, but also meets your preferences.
111116
112- :file: `pyproject.toml ` tells "frontend" build tools like :ref: `pip ` and
113- :ref: `build ` what "backend" tool to use to create
114- :term: `distribution packages <Distribution Package> ` for your project.
115117You can choose from a number of backends; this tutorial uses :ref: `Hatchling
116118<hatch>` by default, but it will work identically with :ref: `setuptools `,
117119:ref: `Flit <flit >`, :ref: `PDM <pdm >`, and others that support the ``[project] ``
@@ -124,7 +126,10 @@ table for :ref:`metadata <configuring metadata>`.
124126 management, as well as building, uploading, and installing packages. This
125127 tutorial uses single-purpose tools that work independently.
126128
127- Open :file: `pyproject.toml ` and enter one of these ``[build-system] `` tables:
129+ The :file: `pyproject.toml ` tells "front end" build tools like :ref: `pip ` and
130+ :ref: `build ` which backend to use for your project. Below are some
131+ examples for common build backends, but check your backend's own documentation
132+ for more details.
128133
129134.. tab :: Hatchling
130135
@@ -159,14 +164,24 @@ Open :file:`pyproject.toml` and enter one of these ``[build-system]`` tables:
159164 build-backend = "pdm.backend"
160165
161166
162- - ``requires `` is a list of packages that are needed to build your package. You
163- don't need to install them; build frontends like :ref: `pip ` will install them
164- automatically in a temporary, isolated virtual environment for use during the
165- build process.
166- - ``build-backend `` is the name of the Python object that frontends will use to
167- perform the build.
167+ The ``requires `` key is a list of packages that are needed to build your package.
168+ The front end should install them automatically when building your package.
169+ There will always be your build backend package, and potentially other build-time
170+ dependencies.
168171
169- .. TODO: Add note to check the tools' documentation for the current snippet?
172+ The ``build-backend `` key is the name of the Python object that frontends will use
173+ to perform the build.
174+
175+ Both of these values will be given to you by the documentation for your build
176+ backend, or generated by its command line interface. There should be no need for
177+ you to customize these settings.
178+
179+ Additional configuration of the build tool will either be in a ``tool `` section
180+ of the ``pyproject.toml ``, or in a special file defined by the build tool. For
181+ example, when using ``setuptools `` as your build backend, additional configuration
182+ may be added to a ``setup.py `` or ``setup.cfg `` file, and specifying
183+ ``setuptools.build_meta `` in your build allows the tools to locate and use these
184+ automatically.
170185
171186.. _configuring metadata :
172187
0 commit comments