Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add function annotations and fix Clang error #1056

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ toml = "0.8.8"
proc-macro2 = "1.0.60"
quote = "1"
heck = "0.4"
regex = "1.11.1"

[dependencies.syn]
version = "2.0.85"
Expand Down
31 changes: 30 additions & 1 deletion docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -272,7 +272,7 @@ While output configuration is primarily done through the cbindgen.toml, in some
pub struct Point(pub f32, pub f32);
```

An annotation may be a bool, string (no quotes), or list of strings. If just the annotation's name is provided, `=true` is assumed. The annotation parser is currently fairly naive and lacks any capacity for escaping, so don't try to make any strings with `=`, `,`, `[` or `]`.
An annotation may be a bool, string (no quotes), or list of strings. If just the annotation's name is provided, `=true` is assumed. The annotation parser is somewhat naive. `,`, `]` and any opening brackets (`[`) after the initial one in lists can be escaped with a backslash. In other annotations values, like string, dict or bool those special character can not currently be escaped. `=` can not currently be escaped at all.

Most annotations are just local overrides for identical settings in the cbindgen.toml, but a few are unique because they don't make sense in a global context. The set of supported annotation are as follows:

Expand Down Expand Up @@ -306,6 +306,35 @@ pub struct Foo { .. }; // This won't be emitted by cbindgen in the header
fn bar() -> Foo { .. } // Will be emitted as `struct foo bar();`
```

### Function annotations

It's sometimes useful to add attributes or macros to functions in C and C++. This can be done by specifying one of the following annotations:

* function-arg-prefix\[arg\]
* function-prefix
* function-postfix
* function-ident-prefix

The following Rust code:

```rust
#[no_mangle]
/// cbindgen:function-prefix=PREFIX_MACRO
/// cbindgen:function-postfix=POSTFIX_MACRO
/// cbindgen:function-ident-prefix=IDENT_PREFIX_MACRO
/// cbindgen:function-arg-ident-prefix[input]=_Nonnull
/// cbindgen:function-arg-prefix[input]=_In_
pub extern "C" fn root(input: *const u64, input_size: u64) {}
```

will generate the following C code:

```c
PREFIX_MACRO void IDENT_PREFIX_MACRO root(_In_ const uint64_t *_Nonnull input, uint64_t input_size) POSTFIX_MACRO;
```

These annotations are not supported and will be ignored when using Cython.

### Struct Annotations

* field-names=\[field1, field2, ...\] -- sets the names of all the fields in the output struct. These names will be output verbatim, and are not eligible for renaming.
Expand Down
Loading