Skip to content

Commit 9acd15b

Browse files
authored
Enhance README with bindgen and csbindgen details
Updated README to clarify usage of bindgen and csbindgen for generating Rust and C# bindings, including details on enum handling and type inclusion.
1 parent 194a089 commit 9acd15b

File tree

1 file changed

+16
-0
lines changed

1 file changed

+16
-0
lines changed

README.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,12 +119,16 @@ fn main() -> Result<(), Box<dyn Error>> {
119119
// using bindgen, generate binding code
120120
bindgen::Builder::default()
121121
.header("c/lz4/lz4.h")
122+
.default_enum_style(bindgen::EnumVariation::Rust {
123+
non_exhaustive: false,
124+
})
122125
.generate()?
123126
.write_to_file("lz4.rs")?;
124127

125128
// csbindgen code, generate C# dll import
126129
csbindgen::Builder::default()
127130
.input_bindgen_file("lz4.rs") // read from bindgen generated code
131+
// .csharp_generate_const_filter(|x| x.starts_with("LZ4_")) // use csharp_generate_const_filter if you want to generate const
128132
.generate_csharp_file("../dotnet/NativeMethods.lz4.g.cs")?;
129133

130134
Ok(())
@@ -133,6 +137,10 @@ fn main() -> Result<(), Box<dyn Error>> {
133137

134138
In this case, you won't use the Rust binary built. Instead, build the C/C++ library separately using make, cmake, or other tools, and place it accordingly. When targeting OSS libraries, they typically come with make/cmake configurations, so it's best to follow their build procedures to generate the library.
135139

140+
bindgen's `default_enum_style` generates consts. When handling in C#, it would be more practical to generate them as enums. Also, csbindgen does not generate consts by default. By enabling `csharp_generate_const_filter`, consts will be generated on the C# side.
141+
142+
Additionally, types and enums that exist in the input file are all trimmed and not generated if they are not used in method definitions. If you want to generate types or enums on the C# side, you explicitly specify them using `always_included_types`. For example, `.always_included_types(["ZL_StandardGraphID", "ZL_StandardNodeID"])`.
143+
136144
#### C to Rust to C#
137145

138146
You can incorporate and build C code into a Rust library by using the [cc crate](https://crates.io/crates/cc) or [cmake crate](https://crates.io/crates/cmake). In that case, you need to create a flow where C# calls Rust, and Rust calls C. You can automate this entire flow by generating both Rust and C# files with `generate_to_file`.
@@ -144,6 +152,9 @@ fn main() -> Result<(), Box<dyn Error>> {
144152
// using bindgen, generate binding code
145153
bindgen::Builder::default()
146154
.header("c/lz4/lz4.h")
155+
.default_enum_style(bindgen::EnumVariation::Rust {
156+
non_exhaustive: false,
157+
})
147158
.generate().unwrap()
148159
.write_to_file("lz4.rs")?;
149160

@@ -156,6 +167,7 @@ fn main() -> Result<(), Box<dyn Error>> {
156167
.rust_file_header("use super::lz4::*;") // import bindgen generated modules(struct/method)
157168
.csharp_entry_point_prefix("csbindgen_") // adjust same signature of rust method and C# EntryPoint
158169
.csharp_dll_name("liblz4")
170+
// .csharp_generate_const_filter(|x| x.starts_with("LZ4_")) // use csharp_generate_const_filter if you want to generate const
159171
.generate_to_file("lz4_ffi.rs", "../dotnet/NativeMethods.lz4.g.cs")?;
160172
}
161173
```
@@ -235,6 +247,7 @@ csbindgen::Builder::default()
235247
"FfiConfiguration" => "Configuration".into(),
236248
_ => x,
237249
})
250+
.always_included_types(["ZL_StandardGraphID", "ZL_StandardNodeID"])` // optional, default: []
238251
.generate_csharp_file("../dotnet-sandbox/NativeMethods.cs") // required
239252
.unwrap();
240253
```
@@ -281,6 +294,8 @@ csbindgen::Builder::default()
281294

282295
also `csharp_imported_namespaces` can call multiple times.
283296

297+
`always_included_types` is optional. Types and enums that exist in the input file are all trimmed and not generated if they are not used in method definitions. If set name, do not trim and generate type to C#.
298+
284299
### Unity Callback
285300

286301
`csharp_use_function_pointer` configures how generate function pointer. The default is to generate a `delegate*`, but Unity does not support it; setting it to `false` will generate a `Func/Action` that can be used with `MonoPInvokeCallback`.
@@ -339,6 +354,7 @@ csbindgen::Builder::default()
339354
"FfiConfiguration" => "Configuration".into(),
340355
_ => x,
341356
})
357+
.always_included_types(["ZL_StandardGraphID", "ZL_StandardNodeID"])` // optional, default: []
342358
.csharp_file_header("#if !UNITY_WEBGL") // optional, default: ""
343359
.csharp_file_footer("#endif") // optional, default: ""
344360
.generate_to_file("src/lz4_ffi.rs", "../dotnet-sandbox/lz4_bindgen.cs") // for C to Rust to C#, if C to C#, use generate_csharp_file instead.

0 commit comments

Comments
 (0)