Skip to content

Commit db4fcf7

Browse files
committed
Add build constraints to user guide
1 parent 1aa1d32 commit db4fcf7

File tree

1 file changed

+45
-0
lines changed

1 file changed

+45
-0
lines changed

docs/html/user_guide.rst

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,51 @@ e.g. http://example.com/constraints.txt, so that your organization can store and
257257
serve them in a centralized place.
258258

259259

260+
.. _`Build Constraints`:
261+
262+
Build Constraints
263+
-----------------
264+
265+
.. versionadded:: 25.2
266+
.. note::
267+
268+
Build constraints are currently an **experimental feature** and must be
269+
enabled using ``--use-feature=build-constraint``.
270+
271+
Build constraints are a specialized type of constraints file that apply only
272+
to the build environment when building packages from source. Unlike regular
273+
constraints which affect the installed packages in your environment, build
274+
constraints only influence the versions of packages available during the
275+
build process.
276+
277+
This is particularly useful when you need to constrain build dependencies
278+
(like ``setuptools``, ``cython``, etc.) without affecting the
279+
final installed environment.
280+
281+
Use build constraints like so:
282+
283+
.. tab:: Unix/macOS
284+
285+
.. code-block:: shell
286+
287+
python -m pip install --build-constraint build-constraints.txt --use-feature=build-constraint SomePackage
288+
289+
.. tab:: Windows
290+
291+
.. code-block:: shell
292+
293+
py -m pip install --build-constraint build-constraints.txt --use-feature=build-constraint SomePackage
294+
295+
Example build constraints file (``build-constraints.txt``):
296+
297+
.. code-block:: text
298+
299+
# Constrain setuptools version during build
300+
setuptools>=45.0.0,<60.0.0
301+
# Pin Cython for packages that use it
302+
cython==0.29.24
303+
304+
260305
.. _`Dependency Groups`:
261306

262307

0 commit comments

Comments
 (0)