Build backend: Make preview default and add configuration docs (#12804)

Add configuration documentation for the build backend and make it the
preview default.

The build backend should generally work with default configuration
unless you want specific features such as flat layout or module
renaming, there is only a dedicated configuration, but no concept or
guide page for the build backend. Once the build backend is stable, we
can update the guide documentation to explain that uv defaults to its
own build backend, but other build backends are also supported.

The uv build backend becomes the default in preview, giving it more
exposure from users and preparing it to make it the default proper. The
current documentation retains warnings that the build backend is in
preview.

To see current uses of `uv_build` on GitHub:
https://github.com/search?q=path%3A**%2Fpyproject.toml+uv_build%3E%3D0&type=code

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>

docs/concepts/projects/init.md

@@ -202,8 +202,8 @@ build-backend = "hatchling.build"
 !!! tip
 
     You can select a different build backend template by using `--build-backend` with `hatchling`,
-    `flit-core`, `pdm-backend`, `setuptools`, `maturin`, or `scikit-build-core`. An alternative
-    backend is required if you want to create a [library with extension modules](#projects-with-extension-modules).
+    `uv_build`, `flit-core`, `pdm-backend`, `setuptools`, `maturin`, or `scikit-build-core`. An
+    alternative backend is required if you want to create a [library with extension modules](#projects-with-extension-modules).
 
 The created module defines a simple API function:
 

docs/configuration/build-backend.md

@@ -0,0 +1,92 @@
+# The uv build backend
+
+!!! note
+
+    The uv build backend is currently in preview and may change without warning.
+
+    When preview mode is not enabled, uv uses [hatchling](https://pypi.org/project/hatchling/) as the default build backend.
+
+A build backend transforms a source tree (i.e., a directory) into a source distribution or a wheel.
+While uv supports all build backends (as specified by PEP 517), it includes a `uv_build` backend
+that integrates tightly with uv to improve performance and user experience.
+
+The uv build backend currently only supports Python code. An alternative backend is required if you
+want to create a
+[library with extension modules](../concepts/projects/init.md#projects-with-extension-modules).
+
+To use the uv build backend as [build system](../concepts/projects/config.md#build-systems) in an
+existing project, add it to the `[build-system]` section in your `pyproject.toml`:
+
+```toml
+[build-system]
+requires = ["uv_build>=0.6.13,<0.7"]
+build-backend = "uv_build"
+```
+
+!!! important
+
+    The uv build backend follows the same [versioning policy](../reference/policies/versioning.md),
+    setting an upper bound on the `uv_build` version ensures that the package continues to build in
+    the future.
+
+You can also create a new project that uses the uv build backend with `uv init`:
+
+```shell
+uv init --build-backend uv
+```
+
+`uv_build` is a separate package from uv, optimized for portability and small binary size. The `uv`
+command includes a copy of the build backend, so when running `uv build`, the same version will be
+used for the build backend as for the uv process. Other build frontends, such as `python -m build`,
+will choose the latest compatible `uv_build` version.
+
+## Include and exclude configuration
+
+To select which files to include in the source distribution, uv first adds the included files and
+directories, then removes the excluded files and directories. This means that exclusions always take
+precedence over inclusions.
+
+When building the source distribution, the following files and directories are included:
+
+- `pyproject.toml`
+- The module under `tool.uv.build-backend.module-root`, by default
+  `src/<module-name or project_name_with_underscores>/**`.
+- `project.license-files` and `project.readme`.
+- All directories under `tool.uv.build-backend.data`.
+- All patterns from `tool.uv.build-backend.source-include`.
+
+From these, `tool.uv.build-backend.source-exclude` and the default excludes are removed.
+
+When building the wheel, the following files and directories are included:
+
+- The module under `tool.uv.build-backend.module-root`, by default
+  `src/<module-name or project_name_with_underscores>/**`.
+- `project.license-files` and `project.readme`, as part of the project metadata.
+- Each directory under `tool.uv.build-backend.data`, as data directories.
+
+From these, `tool.uv.build-backend.source-exclude`, `tool.uv.build-backend.wheel-exclude` and the
+default excludes are removed. The source dist excludes are applied to avoid source tree to wheel
+source builds including more files than source tree to source distribution to wheel build.
+
+There are no specific wheel includes. There must only be one top level module, and all data files
+must either be under the module root or in the appropriate
+[data directory](../reference/settings.md#build-backend_data). Most packages store small data in the
+module root alongside the source code.
+
+## Include and exclude syntax
+
+Includes are anchored, which means that `pyproject.toml` includes only
+`<project root>/pyproject.toml`. For example, `assets/**/sample.csv` includes all `sample.csv` files
+in `<project root>/assets` or any child directory. To recursively include all files under a
+directory, use a `/**` suffix, e.g. `src/**`.
+
+!!! note
+
+    For performance and reproducibility, avoid patterns without an anchor such as `**/sample.csv`.
+
+Excludes are not anchored, which means that `__pycache__` excludes all directories named
+`__pycache__` and its children anywhere. To anchor a directory, use a `/` prefix, e.g., `/dist` will
+exclude only `<project root>/dist`.
+
+All fields accepting patterns use the reduced portable glob syntax from
+[PEP 639](https://peps.python.org/pep-0639/#add-license-FILES-key).

docs/configuration/index.md

@@ -6,6 +6,7 @@ Read about the various ways to configure uv:
 - [Using environment variables](./environment.md)
 - [Configuring authentication](./authentication.md)
 - [Configuring package indexes](./indexes.md)
+- [The uv build backend](build-backend.md)
 
 Or, jump to the [settings reference](../reference/settings.md) which enumerates the available
 configuration options.