Skip to content

Commit c6b8bbd

Browse files
authored
Update Choosing a build backend section
1 parent 0b20b77 commit c6b8bbd

File tree

1 file changed

+29
-14
lines changed

1 file changed

+29
-14
lines changed

source/tutorials/packaging-projects.rst

Lines changed: 29 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -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.
115117
You 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

Comments
 (0)