@@ -103,15 +103,17 @@ Creating a test directory
103
103
:file: `tests/ ` is a placeholder for test files. Leave it empty for now.
104
104
105
105
106
- Creating pyproject.toml
106
+ Choosing a build backend
107
107
-----------------------
108
108
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.
111
116
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.
115
117
You can choose from a number of backends; this tutorial uses :ref: `Hatchling
116
118
<hatch>` by default, but it will work identically with :ref: `setuptools `,
117
119
:ref: `Flit <flit >`, :ref: `PDM <pdm >`, and others that support the ``[project] ``
@@ -124,7 +126,10 @@ table for :ref:`metadata <configuring metadata>`.
124
126
management, as well as building, uploading, and installing packages. This
125
127
tutorial uses single-purpose tools that work independently.
126
128
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.
128
133
129
134
.. tab :: Hatchling
130
135
@@ -159,14 +164,24 @@ Open :file:`pyproject.toml` and enter one of these ``[build-system]`` tables:
159
164
build-backend = "pdm.backend"
160
165
161
166
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.
168
171
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.
170
185
171
186
.. _configuring metadata :
172
187
0 commit comments