✨ feat(cli): surface debug paths when a backend build fails#1087
Merged
Conversation
gaborbernat
force-pushed
the
966-keep-backend-logs
branch
6 times, most recently
from
dccf3c1 to
664cb4f
Compare
gaborbernat
force-pushed
the
966-keep-backend-logs
branch
from
664cb4f to
3db5e62
Compare
When a build backend fails, build cleans up its temporary working directories before the user can inspect them, leaving nothing to debug from. Print a TIP on backend failure that points at --env-dir and --sdist-extract-dir (to keep the build environment and extracted sources) and links to a new "Debug a failed build" how-to. When those locations are already pinned, report where they were kept instead. The how-to also covers streaming backend output with -vv and where backends such as meson-python write their own log files, which build cannot capture itself since PEP 517 exposes no way to find them. Closes pypa#966
gaborbernat
force-pushed
the
966-keep-backend-logs
branch
from
3db5e62 to
b5a7c5c
Compare
henryiii
reviewed
Jun 13, 2026
Backend stdout/stderr is forwarded to the terminal regardless of verbosity; -vv only adds build's own diagnostics and live environment setup output. Drop the claim that -vv is needed to see compiler invocations and tracebacks. Use the meson-python/scikit-build build-dir config setting and generalise the log-path note across backends.
henryiii
reviewed
Jun 13, 2026
Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>
for more information, see https://pre-commit.ci
henryiii
approved these changes
Jun 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A plain
python -m buildthat hits a backend failure deletes its temporary working directories before anyone can look inside them, so the first failure leaves nothing to debug from. This is what #966 ran into with meson-python: the error was visible but the meson log lived in a directory that was already gone. 🔍On any backend failure build now prints a
TIPline. When no working directory is pinned it tells you to re-run with--env-dirand--sdist-extract-dirso the environment and the extracted sources survive the next run; when they are already pinned it reports where they were kept. The line links to a newDebug a failed buildhow-to that walks through streaming backend output with-vv, keeping both working directories, and reaching the backend's own log files. That last part stays the backend's job: PEP 517 gives the frontend no way to discover where a backend writes its logs, so the guide shows the meson-pythonbuilddirsetting as the worked example rather than pretending build can capture them. ✨The behavior change is limited to the failure path, where build now emits one extra hint before exiting; successful builds are untouched.
Stacked on #1083 (
--env-dir) and #1085 (--sdist-extract-dir) — the hint reuses both flags and should merge after them. Depends on #1083 and #1085.Closes #966