Add tool.uv.build-constraint-dependencies to pyproject.toml (#11585)

## Summary

Resolves #6913. 

Add `tool.uv.build-constraint-dependencies` to pyproject.toml.
The changes are analogous to the constraint-dependencies feature
implemented in #5248.

Add documentation for `build-constraint-dependencies`

## Test Plan

Add tests for `uv lock`, `uv add`, `uv pip install` and `uv pip
compile`.

---------

Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>

docs/pip/compile.md

@@ -125,6 +125,38 @@ $ uv pip compile requirements.in --constraint constraints.txt
 
 Note that multiple constraints can be defined in each file and multiple files can be used.
 
+uv will also read `constraint-dependencies` from the `pyproject.toml` at the workspace root, and
+append them to those specified in the constraints file.
+
+## Adding build constraints
+
+Similar to `constraints`, but specifically for build-time dependencies, including those required
+when building runtime dependencies.
+
+Build constraint files are `requirements.txt`-like files that only control the _version_ of a
+build-time requirement. However, including a package in a build constraints file will _not_ trigger
+its installation at build time; instead, constraints apply only when the package is required as a
+direct or transitive build-time dependency. Build constraints can be used to add bounds to
+dependencies that are not explicitly declared as build-time dependencies of the current project.
+
+For example, if a package defines its build dependencies as follows:
+
+```toml title="pyproject.toml"
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+```
+
+Build constraints could be used to ensure that a specific version of `setuptools` is used for every
+package in the workspace:
+
+```python title="build-constraints.txt"
+setuptools==75.0.0
+```
+
+uv will also read `build-constraint-dependencies` from the `pyproject.toml` at the workspace root,
+and append them to those specified in the build constraints file.
+
 ## Overriding dependency versions
 
 Overrides files are `requirements.txt`-like files that force a specific version of a requirement to

docs/reference/settings.md

@@ -1,4 +1,35 @@
 ## Project metadata
+### [`build-constraint-dependencies`](#build-constraint-dependencies) {: #build-constraint-dependencies }
+
+Constraints to apply when solving build dependencies.
+
+Build constraints are used to restrict the versions of build dependencies that are selected
+when building a package during resolution or installation.
+
+Including a package as a constraint will _not_ trigger installation of the package during
+a build; instead, the package must be requested elsewhere in the project's build dependency
+graph.
+
+!!! note
+    In `uv lock`, `uv sync`, and `uv run`, uv will only read `build-constraint-dependencies` from
+    the `pyproject.toml` at the workspace root, and will ignore any declarations in other
+    workspace members or `uv.toml` files.
+
+**Default value**: `[]`
+
+**Type**: `list[str]`
+
+**Example usage**:
+
+```toml title="pyproject.toml"
+[tool.uv]
+# Ensure that the setuptools v60.0.0 is used whenever a package has a build dependency
+# on setuptools.
+build-constraint-dependencies = ["setuptools==60.0.0"]
+```
+
+---
+
 ### [`conflicts`](#conflicts) {: #conflicts }
 
 Declare collections of extras or dependency groups that are conflicting

docs/reference/troubleshooting/build-failures.md

@@ -288,6 +288,28 @@ uv will avoid using an old version of `apache-beam`.
 Constraints can also be defined for indirect dependencies using `constraints.txt` files or the
 [`constraint-dependencies`](../settings.md#constraint-dependencies) setting.
 
+### Old Version of a build dependency is used
+
+If a package fails to build because `uv` selects an incompatible or outdated version of a build-time
+dependency, you can enforce constraints specifically for build dependencies. The
+[`build-constraint-dependencies`](../settings.md#build-constraint-dependencies) setting (or an
+analogous `build-constraints.txt` file) can be used to ensure that `uv` selects an appropriate
+version of a given build requirements.
+
+For example, the issue described in
+[#5551](https://github.com/astral-sh/uv/issues/5551#issuecomment-2256055975) could be addressed by
+specifying a build constraint that excludes `setuptools` version `72.0.0`:
+
+```toml title="pyproject.toml"
+[tool.uv]
+# Prevent setuptools version 72.0.0 from being used as a build dependency.
+build-constraint-dependencies = ["setuptools!=72.0.0"]
+```
+
+The build constraint will thus ensure that any package requiring `setuptools` during the build
+process will avoid using the problematic version, preventing build failures caused by incompatible
+build dependencies.
+
 ### Package is only needed for an unused platform
 
 If locking fails due to building a package from a platform you do not need to support, consider