mozilla / mozilla/cbindgen

[Feature Request] Have cbindgen set a conditional compilation attribute when generating

Open
#1,014 2 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.