fix(cuda.core): warn instead of silently dropping numba_debug on link paths - #2658
Merged
rparolin merged 4 commits intoAug 19, 2026
Merged
Conversation
github-actions
Bot
added
the
cuda.core
|
rparolin
marked this pull request as draft
August 18, 2026 01:01
Contributor
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
… paths `LinkerOptions` carries a public `numba_debug` field that no linking backend reads. nvJitLink rejects the option under every spelling and the driver's cuLink API has no corresponding `CUjit_option`, so setting it does nothing and reports nothing. It is not merely dead: `_translate_program_options` forwarded `numba_debug` from `ProgramOptions` into `LinkerOptions` on the `code_type="ptx"` path, so `Program(ptx, "ptx", ProgramOptions(numba_debug=True))` silently discarded an option the user explicitly set. Make the drop audible without breaking any caller: - `LinkerOptions.numba_debug` is deprecated. Setting it emits a `DeprecationWarning` from `__post_init__` and the value is still ignored. The field stays, so no constructor signature changes. - `_translate_program_options` no longer forwards it and emits a `UserWarning` saying it is ignored for `code_type="ptx"`. `UserWarning` rather than `DeprecationWarning` because `ProgramOptions.numba_debug` is not deprecated -- it is fully supported on NVVM and NVRTC and merely inapplicable to a linking backend. - The option builders are untouched; the linker needs no knowledge of `numba_debug` to ignore it. - `_LinkerBackend.validate` rejects nothing, and `numba_debug` stays out of `_LINKER_FIELD_GATES`: it cannot change PTX-path output, so it must not perturb the program-cache key. The warning gates differ on purpose. The linker field uses `is not None` -- the field itself is going away, so any explicit value earns the notice, including `False`. The PTX path uses truthiness, matching `_prepare_nvvm_options_impl`, because `False` asks for nothing. Removal of `LinkerOptions.numba_debug` is deferred to 2.0.0: the support policy confines breaking API changes to major-version boundaries and requires a deprecation notice at least one minor release ahead. Nothing in the repo tracks a scheduled removal -- the existing precedent (`Device.max_links`) only says "a future release" -- so a version-gated test fails the build once the version crosses 2.0. The NVVM and NVRTC paths are unchanged and still emit the option. Closes NVIDIA#2640 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
rparolin
force-pushed
the
fix/linker-numba-debug-silent-drop
branch
from
August 18, 2026 14:15
b2a45ad to
c063d2a
Compare
rparolin
changed the title
rparolin
marked this pull request as ready for review
August 18, 2026 14:50
rparolin
enabled auto-merge (squash)
August 18, 2026 14:50
rparolin
added
bug
mdboom
requested changes
Aug 18, 2026
Co-authored-by: Michael Droettboom <mdboom@gmail.com>
Co-authored-by: Michael Droettboom <mdboom@gmail.com>
The version-gated `test_numba_debug_removal_is_due_at_2_0` fails the build the moment `cuda.core.__version__` crosses 2.0. That bump lands on an ordinary release-prep PR during code freeze, so the test turns red at the worst possible time and is indistinguishable from a real regression to anyone who did not write it. Drop it, and put the reminder where release managers already look: - Remove the test and the now-unused `import cuda.core`. - Add a release-checklist item to sweep deprecations whose stated removal version has arrived, with matching guidance in RELEASE-core.md. The sweep greps `deprecated::` rather than `\.\. deprecated::` so it also catches the two `Device.max_links` sites, which spell the directive `.. version-deprecated::`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
mdboom
approved these changes
Aug 19, 2026
github-actions Bot
pushed a commit
that referenced
this pull request
Aug 20, 2026
Removed preview folders for the following PRs: - PR #2658
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.
Description
closes #2640
LinkerOptionscarries a publicnumba_debugfield that no linking backend reads. nvJitLink rejects the option under every spelling and the driver's cuLink API has no correspondingCUjit_option, so setting it does nothing and reports nothing.It is not merely dead.
_translate_program_optionsforwardednumba_debugfromProgramOptionsintoLinkerOptionson thecode_type="ptx"path, soProgram(ptx, "ptx", ProgramOptions(numba_debug=True))silently discarded an option the user explicitly set.This makes the drop audible without breaking any caller.
LinkerOptions(numba_debug=...)DeprecationWarning; value ignored_prepare_nvjitlink_options/_prepare_driver_optionsnumba_debugto ignore itProgram(ptx, "ptx", ProgramOptions(numba_debug=True))UserWarning; no longer forwardednumba_debugexcluded — it cannot change PTX-path output, so it must not perturb the keyNothing raises and nothing is removed. This follows existing precedent:
_prepare_driver_optionsalready handles six options the cuLink backend cannot honor (ftz,prec_div,prec_sqrt,fma,kernels_used,variables_used) by warning rather than raising.Two deliberate details
The warning categories differ.
LinkerOptions.numba_debuggets aDeprecationWarning— the field is going away. The PTX path gets aUserWarning, becauseProgramOptions.numba_debugis not deprecated: it is fully supported on NVVM/NVRTC and merely inapplicable to a linking backend. Marking itDeprecationWarningwould tell users a supported option is being removed.The gate polarities differ. The linker field gates on
is not None— the field itself is doomed, so any explicit value earns the notice, includingFalse. The PTX path gates on truthiness, matching_prepare_nvvm_options_impl, becausenumba_debug=Falseasks for nothing and there is no dropped intent to report.Removal
LinkerOptions.numba_debugis deprecated here and removed in 2.0.0, per the support policy: breaking API changes are confined to major-version boundaries, with a deprecation notice at least one minor release ahead.Nothing in this repo tracked a scheduled removal — the only prior public-attribute deprecation,
Device.max_links, says "a future release" with no version, issue, or test behind it. This adds the tracking to the release checklist (.github/ISSUE_TEMPLATE/release_checklist.yml, with matching guidance inRELEASE-core.md): before cutting a release, sweep for deprecations whose stated removal version has arrived and remove any that are due.The sweep greps
deprecated::rather than\.\. deprecated::, so it also catches the twoDevice.max_linkssites, which spell the directive.. version-deprecated::. Whether that spelling is a real Sphinx directive is worth a separate look — if it is not, those two blocks are not rendering as deprecation notices at all.Verification
Full
cuda_coresuite on CUDA 13: 3844 passed, 238 skipped, 4 xfailed, 127 subtests passed, verified against a rebuilt extension.pre-commitclean, including.pyistub regeneration andmypy-cuda-core.numba-cudais unaffected — it drives libNVVM directly via its owncudadrv/nvvm.pyand never routesnumba_debugthrough a cuda.core PTX path.Checklist
🤖 Generated with Claude Code