Denote types with unused template params. #3148
Draft
Conversation
This file contains 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
This extends the existing discovery callback mechanism to report on functions and methods. At this stage, we don't say much about them, in order to be consistent with other discovery callbacks. Subsequent PRs will add extra callbacks to provide information especially about methods (virtualness, C++ visibility, etc.) Please request changes if you think that sort of information should arrive in these callbacks. Because methods are a fundamentally C++ thing, this splits the current ParseCallbacks test to cover both a .h and a .hpp header. Part of google/autocxx#124
No functional change - just deduplicating the logic which calls this callback, which will make it easier to make further changes in future. Part of google/autocxx#124
This adds more information to ParseCallbacks which indicates the location in the original source code at which a given item was found. This has proven to be useful in downstream code generators in providing diagnostics to explain why a given item can't be represented in Rust. (There are lots of reasons why this might not be the case - autocxx has around 100 which can be found here - https://github.com/google/autocxx/blob/d85eac76c9b3089d0d86249e857ff0e8c36b988f/engine/src/conversion/convert_error.rs#L39 - but irrespective of the specific reasons, it's useful to be able to point to the original location when emitting diagnostics). Should we make this a new callback or include this information within the existing callback? Pros of making it a new callback: * No compatibility breakage. Pros of including it in this existing callback: * No need to specify and test a policy about whether such callbacks always happen together, or may arrive individually * Easier for recipients (including bindgen's own test suite) to keep track of the source code location received. * Because we add new items to the DiscoveryItem enum anyway, we seem to have accepted it's OK to break compatibility in this callback (for now at least). Therefore I'm adding it as a parameter to the existing callback. If it's deemed acceptable to break compatibility in this way, I will follow the same thought process for some other changes too. Part of google/autocxx#124.
This makes two complementary improvements to the ParseCallbacks. The first is that Mods are now announced, as a new type of DiscoveredItem. The second is that the parentage of each item is announced. The parent of an item is often a mod (i.e. a C++ namespace) but not necessarily - it might be a struct within a struct, or similar. The reported information here is dependent on two pre-existing bindgen options: * whether to report C++ namespaces at all * whether to report inline namespaces conservatively. For that reason, the test suite gains two new tests. Part of google/autocxx#124
This change reports extra C++ information about items: * Whether methods are virtual or pure virtual or neither * Whether a method is a "special member", e.g. a move constructor * Whether a method is defaulted or deleted * C++ visibility (for structs, enums, unions and methods) It builds on top of rust-lang#3145. A follow up PR should enhance the tests once rust-lang#3139 is merged. Part of google/autocxx#124
Downstream postprocessors such as autocxx may want to use bindgen's representation of types to generate additional C++ code. bindgen is remarkably faithful at passing through enough information to make this possible - but for some C++ types, bindgen chooses to elide some template parameters. It's not safe for additional C++ code to be generated which references that type. This adds a callback by which such tools can recognize types where template parameters have been elided like this, so that extra C++ is avoided. This information could be provided in the existing `new_item_found` callback, but it's very niche and unlikely to be used by the majority of consumers, so a new callback is added instead. An alternative approach here is to provide a mode to bindgen where it *always* uses all template params, by adding additional PhantomData fields to structs where those params are not currently used. This is being prototyped in google/autocxx#1425 but is unlikely to be successful, on the assumption that lots of the templated types can't actually be properly represented by bindgen/Rust, so the current strategy of discarding them is more likely to work in the broad strokes. Part of google/autocxx#124
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Downstream postprocessors such as autocxx may want to use bindgen's
representation of types to generate additional C++ code. bindgen is remarkably
faithful at passing through enough information to make this possible - but for
some C++ types, bindgen chooses to elide some template parameters. It's not
safe for additional C++ code to be generated which references that type.
This adds a callback by which such tools can recognize types where template
parameters have been elided like this, so that extra C++ is avoided.
This information could be provided in the existing
new_item_foundcallback, but it's very niche and unlikely to be used bythe majority of consumers, so a new callback is added instead.
An alternative approach here is to provide a mode to bindgen where it
always uses all template params, by adding additional
PhantomDatafields to structs where those params are not currently used.
This is being prototyped in google/autocxx#1425
but is unlikely to be successful, on the assumption that lots of the
templated types can't actually be properly represented by bindgen/Rust,
so the current strategy of discarding them is more likely to work
in the broad strokes.
This PR is built on top of #3146, which in turn is on top of various others.
Part of google/autocxx#124