构建配置¶

所有构建配置都在 tool.hatch.build 表中定义。

Build targets 被定义为 tool.hatch.build.targets 内的部分：

[tool.hatch.build.targets.<TARGET_NAME>]

[build.targets.<TARGET_NAME>]

对于每个构建目标，您可以覆盖顶层 tool.hatch.build 表中设置的任何默认值。

构建系统¶

要与更广泛的 Python 打包生态系统 兼容，必须如下定义构建系统：

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

这里定义的 hatchling 版本将用于构建所有目标。

Hatchling 是 PEP 517/PEP 660 兼容的构建后端，是 Hatch 本身的一个依赖项。

文件选择¶

VCS¶

默认情况下，Hatch 会尊重项目根目录或父目录中的第一个 .gitignore 或 .hgignore 文件。设置 ignore-vcs 为 true 来禁用此行为：

[tool.hatch.build]
ignore-vcs = true

[build]
ignore-vcs = true

模式¶

您可以设置 include 和 exclude 选项，以准确地选择在每次构建中使用哪些文件，其中 exclude 优先。每个条目都代表 git 风格的 glob 模式。

例如，配置如下：

[tool.hatch.build]
include = [
  "pkg/*.py",
  "/tests",
]
exclude = [
  "*.json",
  "pkg/_compat.py",
]

[build]
include = [
  "pkg/*.py",
  "/tests",
]
exclude = [
  "*.json",
  "pkg/_compat.py",
]

将排除所有扩展名为 .json 的文件，并包括位于根目录下的 tests/ 目录下的所有文件，以及位于根目录下的 pkg 目录下的所有扩展名为 .py 的文件(_compat.py 除外)。

Artifacts¶

如果你想包含 被VCS忽略 的文件，比如那些可能由 build hooks 创建的文件，你可以使用 artifacts 选项。该选项在语义上等价于 include。

注意，artifacts 不受 exclude 选项的影响。可以使用更显式的路径或使用 ! 否定算子。当使用 ! 算子，否定模式必须在更通用的模式之后。

[tool.hatch.build]
artifacts = [
  "*.so",
  "*.dll",
  "!/foo/*.so",
]

[build]
artifacts = [
  "*.so",
  "*.dll",
  "!/foo/*.so",
]

显式选择¶

通用¶

您可以使用 only-include 选项来防止从项目根开始的目录遍历，并且只选择目录或文件的特定相对路径。使用此选项会忽略任何已定义的 include 模式。

[tool.hatch.build.targets.wheel]
only-include = ["pkg", "tests/unit"]

[build.targets.wheel]
only-include = ["pkg", "tests/unit"]

Packages¶

packages 选项在语义上等价于 only-include (优先级)，只是附带的路径将被折叠为只包含最终组件。

例如，如果你想要发送存储在 src 目录下的包 foo，你可以这样做：

[tool.hatch.build.targets.wheel]
packages = ["src/foo"]

[build.targets.wheel]
packages = ["src/foo"]

Forced inclusion¶

force-include 选项允许您从文件系统上任何位置选择应该包含的特定文件或目录，并将它们映射到所需的相对发布路径。

例如，如果在项目根目录中有名为 artifacts 的目录，其中包含名为 lib.so 的文件。并且，在你的主目录下有名为 lib.h 的文件，你可以使用以下配置将这两个文件放在 pkg 目录中：

[tool.hatch.build.force-include]
"../artifacts" = "pkg"
"~/lib.h" = "pkg/lib.h"

[build.force-include]
"../artifacts" = "pkg"
"~/lib.h" = "pkg/lib.h"

默认文件选择¶

如果没有提供文件选择选项，则包含的内容由每个 build target 决定。

排除包之外的文件¶

如果你想排除不存在于 Python 包中的非 artifact 文件，将 only-packages 设置为 true：

[tool.hatch.build]
only-packages = true

[build]
only-packages = true

重写路径¶

你可以用 sources 选项重写目录的相对路径。例如，配置如下：

[tool.hatch.build.sources]
"src/foo" = "bar"

[build.sources]
"src/foo" = "bar"

将分发文件 src/foo/file.ext 作为 bar/file.ext。

如果你想完全删除路径前缀，而不是将每个前缀都设置为空字符串，你可以将 sources 定义为数组：

[tool.hatch.build]
sources = ["src"]

[build]
sources = ["src"]

packages 选项本身依赖于 sources。为 wheel 目标定义 packages = ["src/foo"] 等价如下：

[tool.hatch.build.targets.wheel]
only-include = ["src/foo"]
sources = ["src"]

[build.targets.wheel]
only-include = ["src/foo"]
sources = ["src"]

Performance¶

All encountered directories are traversed by default. To skip non-artifact directories that are excluded, set skip-excluded-dirs to true:

[tool.hatch.build]
skip-excluded-dirs = true

[build]
skip-excluded-dirs = true

Reproducible builds¶

By default, build targets will build in a reproducible manner provided that they support that behavior. To disable this, set reproducible to false:

[tool.hatch.build]
reproducible = false

[build]
reproducible = false

When enabled, the SOURCE_DATE_EPOCH environment variable will be used for all build timestamps. If not set, then Hatch will use an unchanging default value.

Output directory¶

When the output directory is not provided to the build command, the dist directory will be used by default. You can change the default to a different directory using a relative or absolute path like so:

[tool.hatch.build]
directory = "<PATH>"

[build]
directory = "<PATH>"

Dev mode¶

By default for dev mode environment installations or editable installs, the wheel target will determine which directories should be added to Python's search path based on the selected files.

If you want to override this detection or perhaps instruct other build targets as well, you can use the dev-mode-dirs option:

[tool.hatch.build]
dev-mode-dirs = ["."]

[build]
dev-mode-dirs = ["."]

If you don't want to add entire directories to Python's search path, you can enable a more targeted mechanism with the mutually exclusive dev-mode-exact option:

[tool.hatch.build]
dev-mode-exact = true

[build]
dev-mode-exact = true

Build targets¶

A build target can be provided by any builder plugin. There are three built-in build targets: wheel, sdist, and custom.

Dependencies¶

You can specify additional dependencies that will be installed in each build environment, such as for third party builders:

[tool.hatch.build.targets.your-target-name]
dependencies = [
  "your-builder-plugin"
]

[build.targets.your-target-name]
dependencies = [
  "your-builder-plugin"
]

You can also declare dependence on the project's runtime dependencies with the require-runtime-dependencies option:

[tool.hatch.build.targets.your-target-name]
require-runtime-dependencies = true

[build.targets.your-target-name]
require-runtime-dependencies = true

Additionally, you may declare dependence on specific runtime features of the project with the require-runtime-features option:

[tool.hatch.build.targets.your-target-name]
require-runtime-features = [
  "feature1",
  "feature2",
]

[build.targets.your-target-name]
require-runtime-features = [
  "feature1",
  "feature2",
]

Versions¶

If a build target supports multiple build strategies or if there are major changes over time, you can specify exactly which versions you want to build using the versions option, which may be defined as either an array of strings or a comma-separated string:

[tool.hatch.build.targets.<TARGET_NAME>]
versions = [
  "v1",
  "beta-feature",
]

[build.targets.<TARGET_NAME>]
versions = [
  "v1",
  "beta-feature",
]

See the wheel target for a real world example.

Build hooks¶

A build hook defines code that will be executed at various stages of the build process and can be provided by any build hook plugin. There is one built-in build hook: custom.

Build hooks can be applied either globally:

[tool.hatch.build.hooks.<HOOK_NAME>]

[build.hooks.<HOOK_NAME>]

or to specific build targets:

[tool.hatch.build.targets.<TARGET_NAME>.hooks.<HOOK_NAME>]

[build.targets.<TARGET_NAME>.hooks.<HOOK_NAME>]

Dependencies¶

You can specify additional dependencies that will be installed in each build environment, such as for third party build hooks:

[tool.hatch.build.hooks.your-hook-name]
dependencies = [
  "your-build-hook-plugin"
]

[build.hooks.your-hook-name]
dependencies = [
  "your-build-hook-plugin"
]

You can also declare dependence on the project's runtime dependencies with the require-runtime-dependencies option:

[tool.hatch.build.hooks.your-hook-name]
require-runtime-dependencies = true

[build.hooks.your-hook-name]
require-runtime-dependencies = true

Additionally, you may declare dependence on specific runtime features of the project with the require-runtime-features option:

[tool.hatch.build.hooks.your-hook-name]
require-runtime-features = [
  "feature1",
  "feature2",
]

[build.hooks.your-hook-name]
require-runtime-features = [
  "feature1",
  "feature2",
]

Order of execution¶

For each build target, build hooks execute in the order in which they are defined, starting with global hooks.

As an example, for the following configuration:

[tool.hatch.build.targets.foo.hooks.hook2]

[tool.hatch.build.hooks.hook3]
[tool.hatch.build.hooks.hook1]

[build.targets.foo.hooks.hook2]

[build.hooks.hook3]
[build.hooks.hook1]

When target foo is built, build hook hook3 will be executed first, followed by hook1, and then finally hook2.

Conditional execution¶

If you want to disable a build hook by default and control its use by environment variables, you can do so by setting the enable-by-default option to false:

[tool.hatch.build.hooks.<HOOK_NAME>]
enable-by-default = false

[build.hooks.<HOOK_NAME>]
enable-by-default = false

Environment variables¶