3.7 KiB
Build hook plugins
A build hook provides code that will be executed at various stages of the build process. See the documentation for build hook configuration.
Known third-party
- hatch-argparse-manpage - generate man pages for argparse-based CLIs
- hatch-autorun - used to inject code into an installation that will automatically run before the first import
- hatch-build-scripts - run arbitrary shell commands that create artifacts
- hatch-cython - build Cython extensions
- hatch-gettext - compiles multi-lingual messages with GNU
gettexttools - hatch-jupyter-builder - used for packages in the Project Jupyter ecosystem
- hatch-mypyc - compiles code with Mypyc
- hatch-odoo - package Odoo add-ons into the appropriate namespace
- scikit-build-core - build extension modules with CMake
Overview
Build hooks run for every selected version of build targets.
The initialization stage occurs immediately before each build and the finalization stage occurs immediately after. Each stage has the opportunity to view or modify build data.
Build data
Build data is a simple mapping whose contents can influence the behavior of builds. Which fields exist and are recognized depends on each build target.
The following fields are always present and recognized by the build system itself:
| Field | Type | Description |
|---|---|---|
artifacts |
#!python list[str] |
This is a list of extra artifact patterns and should generally only be appended to |
force_include |
#!python dict[str, str] |
This is a mapping of extra forced inclusion paths, with this mapping taking precedence in case of conflicts |
build_hooks |
#!python tuple[str, ...] |
This is an immutable sequence of the names of the configured build hooks and matches the order in which they run |
!!! attention While user-facing TOML options are hyphenated, build data fields should be named with underscores to allow plugins to use them as valid Python identifiers.
Notes
In some cases it may be necessary to use force_include rather than artifacts. For example, say that you want to install a lib.so directly at the root of site-packages and a project defines a package src/foo. If you create src/lib.so, there will never be a match because the directory traversal starts at src/foo rather than src. In that case you must do either:
build_data['force_include']['src/lib.so'] = 'src/lib.so'
or
build_data['force_include']['/absolute/path/to/src/lib.so'] = 'src/lib.so'
::: hatchling.builders.hooks.plugin.interface.BuildHookInterface options: members: - PLUGIN_NAME - app - root - config - build_config - target_name - directory - dependencies - clean - initialize - finalize