[Feature Request] Have cbindgen set a conditional compilation attribute when generating
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 3k
- Forks
- 386
- Avg merge
- 1h 43m
- Merged PRs (30d)
- 1
Description
Right now, there's no way to hide (or specifically include) code that only cbindgen needs to know about when parsing a file.
There should be a conditional compilation attribute, or some other way of specifying code that only cbindgen needs to see. This should work just like the #[cfg(rust_analyzer)] attribute, or #[cfg(doc)] attribute.
There are a few use cases for this, but one of them is to selectively generate documentation, or to omit certain code. There are cases where cbindgen:ignore is not sufficient.
For instance, I don't want the cbindgen annotations cluttering up the public documentation for my code, so I use this odd macro cfg like so:
#[cfg_attr(not(any(doc, rust_analyzer)), doc = "cbindgen:[annotation]"
Another use case is to get cbindgen to output the correct structure or type of something that it isn't doing properly otherwise.
For example, I have an issue where a renamed type does not play nicely with how cbindgen unravels *const T.
Specifically, I have a type, FfiStr, that is a wrapper for *const c_char. I am currently using renaming to have cbindgen treat this as a const char* (which is correct). But cbindgen doesn't play nicely with this when I need to pass around arrays of these. Typing *const FfiStr results in const const char *.
I can't use a type alias, which cbidngen will just translate to using _ as ... when it sees it. For other reasons, I also can't use a type wrapper in Rust. However, if I were provided an annotation, then I could conditionally define a type annotation that cbindgen never sees.
The feature flag option in cbindgen.toml isn't sufficient for this. For one, this can cause undesirable behavior when invoking other tools that want--features=all or similar. It also doesn't really convey the intent very well: that this code snippet is only meant to be seen by cbindgen.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No source file, test, or entry point is named; start by locating cbindgen's parsing and conditional-compilation handling. Define the behavior from the reported cases: support code visible only to cbindgen without affecting Rust documentation or other feature-based tools, including the pointer and renamed-type example, and add tests for the chosen syntax.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100