Using the Makefile

Using the Makefile#

make.bat on Windows, or Makefile on *nix, is often a handy companion in development. It makes development less dry, repetitive and error-prone, and the process as a whole more smooth-sailing. It can also pull in non-Python dependencies when needed and leaves behind automatically ignored marker files removable by a simple cleanup command. Tasks are effectively automated using the make <target> syntax.

The Makefile is intended to be used by developers, not end users, and it obviously requires GNU Make.

You are strongly advised to develop in cmd.exe on Windows. There shouldn’t be a need to run scripts\generate.ps1 manually.

Certain executables, some of which are entry points to Python dependencies, will be on PATH once make setup has been run and the environment activated. In this step, prek, uv, ruff, and ty will be automatically installed on your system if not present. For this to work, internet access is required, as well as cURL or GNU wget on *nix.

Target-specific dependencies#

Requires docker:

  • build

  • run

Requires uv:

  • lint

  • lock

Requires ruff:

  • lint

Requires ty:

  • lint

Requires prek:

  • pc

Requires gh:

  • rel

Requires cURL 7.66.0+ on *nix (for parallel downloads):

  • docs

  • links

Optional target-specific dependencies#

Some targets invoke executables only if they are found on the system.

All targets#

Below is the Makefile help as of $v:

Available targets:
 audit  - Run uv audit, (if present) zizmor (with online audits, getting token using gh auth token), and (if present) betterleaks sequentially
 badges - Run the test suite twice, exiting on any failure; generate static badges on success
 bug    - File a bug report in the browser with prefilled environment information
 build  - Build the Docker image for the asyncutils CLI locally
 clean  - Clean development artifacts and caches, including __pycache__/, build/, dist/, generated files, and coverage results
 dclean - Equivalent to git clean -dxf
 docs   - Build the documentation in HTML format in docs/build/html, exiting with a non-zero status on any warning; requires internet access
 help   - Show this help message; the default target
 links  - Check that links in the documents are valid using the Sphinx linkcheck builder
 lint   - Run ruff and ty sequentially, followed by CSpell, markdownlint-cli2 and sphinx-lint if found
 lock   - Update dependencies and regenerate uv.lock
 log    - Print Git history with colour using less in the terminal
 pc     - Run prek hooks on all files, unlike the run before each commit which only runs on modified files
 rel    - Make a release interactively using the GitHub CLI
 run    - Run the Docker image
 setup  - Create a virtual environment, install the package in editable mode with development dependencies inside and install prek hooks
 test   - Run tests, allowing up to AUTESTMAXFAIL failures (default 3) since any more would likely mean an obvious error
Targets may be added on popular demand.

Note

Preview generated by scripts/generate.sh at 2026-11-14 00:18:12 UTC. DO NOT COMMIT.