Build hooks#
It is rather easy to write a build hook, pdm-backend
now provides 6 hooks for you to customize the every step of the build process, and you don't need to implement them all. Let's learn it with some examples.
Modify the project metadata#
1 2 3 |
|
The metadata can be accessed like a dictionary, and any update to the object will take effect immediately.
For sdist builds, the modified pyproject.toml
will be written into the tarball.
Tip
As you can see, you don't need to import any specific stuff from pdm.backend
. Of course, you may need to when you want
to type-annotate your hook function.
Add more files or change the collected files#
There are two ways to achieve this.
- Any files generated under
context.build_dir
, unless excluded byexcludes
setting, will be collected automatically.
1 2 3 4 |
|
- The file will be packed as
COPYING.md
inside the artifact.
Or, you can generate it anywhere and include the path explicitly.
1 2 3 |
|
- The file path inside the artifact will be
myconfig.yaml
.
Call setup() function to build extensions#
1 2 |
|
1 2 3 4 5 6 |
|
Enable the hook for a specific build target#
Sometimes you only want to activate the hook for a specific hook, you can define the pdm_build_hook_enabled()
hook:
1 2 3 |
|
You can also look at the context
object inside a specific hook to determine it should be called.
Change the build directory#
By default, build files will be written to .pdm-build
directory under the project root. You can change it by setting context.build_dir
.
However, since the build clean will be run before pdm_build_initialize
, this must be done in the pdm_build_clean
hook:
1 2 |
|
Build hooks flow#
The hooks are called in the following order:
flowchart TD
A{{pdm_build_hook_enabled?}} --> pdm_build_clean
pdm_build_clean --> pdm_build_initialize
pdm_build_initialize --> B{{run-setuptools?}}
B --> |yes|C[pdm_build_update_setup_kwargs]
B --> |no|D[pdm_build_update_files]
C --> D
D --> pdm_build_finalize
Read the API reference for more details.
Distribute the hook as a plugin#
If you want to share your hook with others, you can change the hook script file into a Python package and upload it to PyPI.
File structure:
1 2 3 4 5 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
1 2 3 4 5 6 7 |
|
The plugin must be distributed with an entry point under pdm.build.hook
group. The entry point value can be any of the following:
- A module containing hook functions
- A class object which implements the hook functions as methods
- An instance of the above class object
After it is published, another user can enable this hook by including the package name in build-system.requires
:
1 2 3 |
|