Build configuration¶
Build targetsは、tool.hatch.build.targets内のセクションとして定義されます:
[tool.hatch.build.targets.<TARGET_NAME>]
[build.targets.<TARGET_NAME>]
Tip
推奨されませんが、tool.hatch.buildテーブルでグローバル設定を定義できます。キーはターゲット設定によって上書きされる場合があります。
Build system¶
より広範なPython packaging ecosystemと互換性を持たせるには、build systemを次のように定義する必要があります。:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
ここで定義された「hatchling」のバージョンは、すべてのターゲットを構築するために使用されます。
Hatchlingは標準に準拠した1ビルドバックエンドであり、Hatch自体の依存関係です。
File selection¶
VCS¶
デフォルトでは、Hatchはプロジェクトのルートディレクトリまたは親ディレクトリにある最初の.gitignoreまたは.hgignoreファイルを尊重します。この動作を無効にするには、ignore-vcsをtrueに設定します。:
[tool.hatch.build.targets.sdist]
ignore-vcs = true
[build.targets.sdist]
ignore-vcs = true
Note
.hgignoreファイルではglob構文のみがサポートされています。
Patterns¶
includeとexcludeオプションを設定して、各ビルドでどのファイルを出荷するかを正確に選択できます。excludeが優先されます。すべてのエントリはGit-style glob patternを表します。
たとえば、次のように設定します。:
[tool.hatch.build.targets.sdist]
include = [
"pkg/*.py",
"/tests",
]
exclude = [
"*.json",
"pkg/_compat.py",
]
[build.targets.sdist]
include = [
"pkg/*.py",
"/tests",
]
exclude = [
"*.json",
"pkg/_compat.py",
]
は、.json拡張子を持つすべてのファイルを除外し、ルートにあるtestsディレクトリの下にあるすべてのファイルと、_compat.pyを除いてルートにあるpkgディレクトリの直下にある.py拡張子を持つすべてのファイルを含みます。
Artifacts¶
build hooksによって作成される可能性のあるファイルなど、ignored by your VCSファイルを含める場合は、artifactsオプションを使用できます。このオプションは、意味的にはincludeと同等です。
アーティファクトはexcludeオプションの影響を受けないことに注意してください。アーティファクトは、より明示的なパスを使用するか、!否定演算子を使用して除外できます。
!演算子を使用する場合、否定されたパターンはより一般的なパターンの後に来る必要があります。
[tool.hatch.build.targets.wheel]
artifacts = [
"*.so",
"*.dll",
"!/foo/*.so",
]
[build.targets.wheel]
artifacts = [
"*.so",
"*.dll",
"!/foo/*.so",
]
Explicit selection¶
Generic¶
only-includeオプションを使用すると、ディレクトリトラバーサルがプロジェクトのルートから開始されるのを防ぎ、ディレクトリまたはファイルへの特定の相対パスのみを選択できます。このオプションを使用すると、定義されたinclude patternは無視されます。
[tool.hatch.build.targets.sdist]
only-include = ["pkg", "tests/unit"]
[build.targets.sdist]
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オプションを使用すると、含める必要があるファイルシステム上の任意の場所から特定のファイルまたはディレクトリを選択し、それらを目的の相対配布パスにマッピングできます。
たとえば、ホームディレクトリにlib.soという名前のファイルとlib.hという名前のファイルを含むartifactsという名前のプロジェクトルートの横にディレクトリがある場合、次の構成で両方のファイルをpkgディレクトリに配置できます。:
[tool.hatch.build.targets.wheel.force-include]
"../artifacts" = "pkg"
"~/lib.h" = "pkg/lib.h"
[build.targets.wheel.force-include]
"../artifacts" = "pkg"
"~/lib.h" = "pkg/lib.h"
Note
- ファイルは、ディレクトリではなく、目的のパスに正確にマッピングする必要があります。
- ディレクトリソースの内容が再帰的に含まれます。
- ディレクトリの内容を直接ルートにマッピングするには、
/(スラッシュ)を使用します。 - ソースが存在しない場合はエラーが発生します。
Warning
このオプションを使用してインクルードされたファイルは、他のファイル選択オプションによってすでにインクルードされているファイルパスを上書きします。
Default file selection¶
ファイル選択オプションが指定されていない場合、何が含まれるかは、各build targetによって決まります。
Excluding files outside packages¶
Pythonパッケージ内に存在しないartifact以外のファイルを除外する場合は、only-packagesをtrueに設定します。:
[tool.hatch.build.targets.wheel]
only-packages = true
[build.targets.wheel]
only-packages = true
Rewriting paths¶
ディレクトリへの相対パスは、sourcesオプションを使用して書き換えることができます。たとえば、次のように設定します。:
[tool.hatch.build.targets.wheel.sources]
"src/foo" = "bar"
[build.targets.wheel.sources]
"src/foo" = "bar"
would distribute the file src/foo/file.ext as bar/file.ext.
ファイルsrc/foo/file.extをbar/file.extとして配布します。
それぞれを空の文字列に設定するのではなく、パスプレフィックス全体を削除したい場合は、sourcesを配列として定義できます。:
[tool.hatch.build.targets.wheel]
sources = ["src"]
[build.targets.wheel]
sources = ["src"]
パスに接頭辞を追加する場合は、空の文字列を使用できます。たとえば、次のように構成します。:
[tool.hatch.build.targets.wheel.sources]
"" = "foo"
[build.targets.wheel.sources]
"" = "foo"
はファイルbar/file.extをfoo/bar/file.extとして配布します。
packagesオプション自体はソースに依存します。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¶
デフォルトでは、検出されたすべてのディレクトリが走査されます。除外されているartifact以外のディレクトリをスキップするには、skip-excluded-dirsをtrueに設定します:
[tool.hatch.build]
skip-excluded-dirs = true
[build]
skip-excluded-dirs = true
Warning
これにより、必要なファイルが出荷されない可能性があります。たとえば、ファイルa/b/c.txtを含めたいが、VCS ignoresa/bの場合、親ディレクトリが入力されないため、ファイルc.txtは表示されません。このような場合は、force-includeオプションを使用できます。
Reproducible builds¶
デフォルトでは、build targetsは、その動作をサポートしていれば、再現可能な方法でビルドします。これを無効にするには、reproducibleをfalseに設定します:
[tool.hatch.build]
reproducible = false
[build]
reproducible = false
有効にすると、SOURCE_DATE_EPOCH環境変数がすべてのビルドタイムスタンプに使用されます。設定されていない場合、Hatchはunchanging default valueを使用します。
Output directory¶
出力ディレクトリがbuildコマンドに提供されていない場合、デフォルトではdistディレクトリが使用されます。次のように相対パスまたは絶対パスを使用して、デフォルトを別のディレクトリに変更できます。:
[tool.hatch.build]
directory = "<PATH>"
[build]
directory = "<PATH>"
Dev mode¶
デフォルトでは、dev mode環境インストールまたはeditable installsの場合、wheelターゲットはselected filesに基づいてPythonの検索パスに追加するディレクトリを決定します。
この検出を無効にするか、他のビルドターゲットにも指示する場合は、dev-mode-dirsオプションを使用できます。:
[tool.hatch.build]
dev-mode-dirs = ["."]
[build]
dev-mode-dirs = ["."]
ディレクトリ全体をPythonの検索パスに追加したくない場合は、相互に排他的なdev-mode-exactオプションを使用して、よりターゲットを絞ったメカニズムを有効にできます。:
[tool.hatch.build]
dev-mode-exact = true
[build]
dev-mode-exact = true
Warning
dev-mode-exactメカニズムは、静的分析ツールとIDEによってnot supportedため、自動補完などの機能は機能しない可能性がある。
Build targets¶
ビルドターゲットは、任意のbuilder pluginによって提供されます。wheel、sdist、およびcustomの3つの組み込みビルドターゲットがあります。
Dependencies¶
各ビルド環境にインストールされる追加の依存関係を指定できます。たとえば、サードパーティビルダー用に次のように指定できます。:
[tool.hatch.build.targets.your-target-name]
dependencies = [
"your-builder-plugin"
]
[build.targets.your-target-name]
dependencies = [
"your-builder-plugin"
]
require-runtime-dependenciesオプションを使用して、プロジェクトのruntime dependenciesへの依存関係を宣言することもできます。:
[tool.hatch.build.targets.your-target-name]
require-runtime-dependencies = true
[build.targets.your-target-name]
require-runtime-dependencies = true
さらに、require-runtime-featuresオプションを使用して、プロジェクトの特定のruntime featuresへの依存性を宣言することもできます。:
[tool.hatch.build.targets.your-target-name]
require-runtime-features = [
"feature1",
"feature2",
]
[build.targets.your-target-name]
require-runtime-features = [
"feature1",
"feature2",
]
Versions¶
ビルドターゲットが複数のビルド戦略をサポートしている場合、または時間の経過とともに大きな変更がある場合は、versionsオプションを使用してビルドするバージョンを正確に指定できます。:
[tool.hatch.build.targets.<TARGET_NAME>]
versions = [
"v1",
"beta-feature",
]
[build.targets.<TARGET_NAME>]
versions = [
"v1",
"beta-feature",
]
実際の例については、wheelターゲットを参照してください。
Build hooks¶
ビルドフックは、ビルドプロセスのさまざまな段階で実行され、任意のbuild hook pluginによって提供されるコードを定義します。customという組み込みビルドフックが1つあります。
ビルドフックは、次のいずれかにグローバルに適用できます。:
[tool.hatch.build.hooks.<HOOK_NAME>]
[build.hooks.<HOOK_NAME>]
または特定のビルドターゲット:
[tool.hatch.build.targets.<TARGET_NAME>.hooks.<HOOK_NAME>]
[build.targets.<TARGET_NAME>.hooks.<HOOK_NAME>]
Dependencies¶
サード・パーティのビルド・フックなど、各ビルド環境にインストールされる追加の依存関係を指定できます。:
[tool.hatch.build.hooks.your-hook-name]
dependencies = [
"your-build-hook-plugin"
]
[build.hooks.your-hook-name]
dependencies = [
"your-build-hook-plugin"
]
require-runtime-dependenciesオプションを使用して、プロジェクトのruntime dependenciesへの依存関係を宣言することもできます。:
[tool.hatch.build.hooks.your-hook-name]
require-runtime-dependencies = true
[build.hooks.your-hook-name]
require-runtime-dependencies = true
さらに、require-runtime-featuresオプションを使用して、プロジェクトの特定のruntime featuresへの依存性を宣言することもできます。:
[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¶
ビルドターゲットごとに、ビルドフックは定義された順序で実行され、グローバルフックから開始されます。
たとえば、次の設定では:
[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]
ターゲットfooが構築されると、構築フックhook3が最初に実行され、続いてhook1が実行され、最後にhook2が実行されます。
Conditional execution¶
デフォルトでビルドフックを無効にし、environment variablesによってその使用を制御したい場合は、enable-by-defaultオプションをfalseに設定することでそれを行うことができます。:
[tool.hatch.build.hooks.<HOOK_NAME>]
enable-by-default = false
[build.hooks.<HOOK_NAME>]
enable-by-default = false
Environment variables¶
| 変数 | デフォルト | 説明 |
|---|---|---|
HATCH_BUILD_CLEAN | false | 既存のアーティファクトを最初に削除するかどうか |
HATCH_BUILD_CLEAN_HOOKS_AFTER | false | 各ビルド後にビルドフックアーティファクトを削除するかどうか |
HATCH_BUILD_HOOKS_ONLY | false | ビルドフックのみを実行するかどうか |
HATCH_BUILD_NO_HOOKS | false | すべてのビルドフックを無効にするかどうか。これは他のオプションよりも優先されます。 |
HATCH_BUILD_HOOKS_ENABLE | false | すべてのビルドフックを有効にするかどうか |
HATCH_BUILD_HOOK_ENABLE_<HOOK_NAME> | false | <HOOK_NAME>という名前のビルドフックを有効にするかどうか |
HATCH_BUILD_LOCATION | dist | ターゲットを構築する場所。buildコマンドでのみ使用されます。 |