Add a generation best-practices guide for ClangSharpPInvokeGenerator#752
Merged
tannergooding merged 4 commits intoJul 13, 2026
Merged
Conversation
Documents how to structure a ClangSharpPInvokeGenerator project, compose response files, choose options, regenerate incrementally, and avoid common pitfalls, grounded in the terrafx.interop.windows patterns. Addresses the documentation gap raised in dotnet#532. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Add a "More information:" footer to the tool help pointing at the guide so users can discover it from the command line. Relates to dotnet#532. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Gives Linux/macOS users a find + xargs command matching the PowerShell parallel-regeneration snippet. Relates to dotnet#532. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Replace a PowerShell-specific Push-Location reference in prose with a platform-neutral description so it applies to the bash driver too. Relates to dotnet#532. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
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
1 participant
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.
Adds an opinionated best-practices guide for driving
ClangSharpPInvokeGenerator, and wires it into the docs so it's discoverable. This addresses the documentation gap raised in #532 — the underlying need there was guidance on how to drive the generator well, not more logging (the existinglog-exclusions/log-potential-typedef-remappings/log-visited-filesflags already cover the diagnostics, and the guide points at them).Every recommendation is grounded in a real pattern from terrafx/terrafx.interop.windows or a real generator option — no invented features.
New doc —
docs/generating-bindings-best-practices.md, covering:generate.rspand regenerates in parallel, shown in both PowerShell and bash)@-include composition (generate.rsp→settings.rsp+remap.rsp→ topicalremap-*.rsp)Discoverability
README.md— Table-of-Contents entry + a link in the Generating Bindings sectionsources/ClangSharpPInvokeGenerator/README.md— link under More information--helpnow prints aMore information:footer pointing at the guideThe help link and the tool-README link reference
blob/main/docs/generating-bindings-best-practices.md(a stable branch URL rather than a commit permalink, which can't exist until this merges); happy to swap in a versioned/release permalink if preferred.dotnet build -c Releasestays green with 0 warnings.