【免费下载链接】rust-bindgenAutomatically generates Rust FFI bindings to C (and some C) libraries.项目地址https://gitcode.com/gh_mirrors/ru/rust-bindgen点击查看免费下载Rust 语言本身不支持 C/C 中的位域bitfield语法rust-bindgen 在生成 FFI 绑定时会自动将位域结构体转换为「不透明物理字段 逻辑访问方法」的形式以保证内存布局与 C 侧完全一致。本文以book/src/using-bitfields.md为骨架结合仓库源码bindgen/codegen/mod.rs、bindgen/codegen/bitfield_unit.rs及bindgen-tests/tests/expectations/tests/struct_with_bitfields.rs等详解 bindgen 位域生成策略、getter/setter/构造器的使用方式、溢出行为以及如何通过--blocklist-type替换默认位域单元实现。位域策略概述C/C 允许在结构体中以unsigned int a : 1的形式声明按位存储的字段而 Rust 没有对应语法。为此bindgen 为每个含位域的结构体生成一套统一的代码形态具有以下特征与文档 book/src/using-bitfields.md 描述一致并可在源码 bindgen/codegen/mod.rs 中得到印证不可变 getter 方法为每个有名位域生成名为bitfield的方法例如fn a(self) - c_ushort内部通过get_const::offset, width()读取对应比特区间setter 方法为每个连续位域块生成名为set_bitfield的方法用于写入对应位域例如fn set_a(mut self, val: c_ushort)不透明物理字段对每个连续位域块bindgen 生成一个名为_bitfield_N的物理字段类型为__BindgenBitfieldUnit[u8; size]一个物理字段内可能承载多个逻辑位域静态构造器为每个物理字段生成new_bitfield_{1, 2, ...}构造器参数个数与该物理字段内包含的位域个数一一对应。以文档中的 C 类型为例typedef struct { unsigned int a: 1; unsigned int b: 1; unsigned int c: 2; } StructWithBitfields; // Create a default bitfield StructWithBitfields create_bitfield(); // Print a bitfield void print_bitfield(StructWithBitfields bfield);bindgen 会生成类似如下的 Rust 结构体三个 1/1/2 位的连续位域会被合并到同一个物理字段_bitfield_1: __BindgenBitfieldUnit[u8; 1usize]中并配套生成a()、b()、c()三个 getterset_a()、set_b()、set_c()三个 setter以及new_bitfield_1(a, b, c)构造器。真实生成形态可参考仓库中的期望输出 bindgen-tests/tests/expectations/tests/struct_with_bitfields.rs。注意上述create_bitfield()/print_bitfield()为文档中的演示函数用于说明位域字段的读写效果实际项目中这些函数由你正在绑定的 C 库提供。__BindgenBitfieldUnit位域单元的实现原理__BindgenBitfieldUnit是 bindgen 在位域场景下自动发射的位域单元类型其模板实现在 bindgen/codegen/bitfield_unit.rs 中#[repr(C)] #[derive(Copy, Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)] pub struct __BindgenBitfieldUnitStorage { storage: Storage, }该类型以泛型参数Storage承载原始字节通常实例化为[u8; N]N为物理字段占用的字节数并实现了完整的位级读写接口get(bit_offset, bit_width)/set(bit_offset, bit_width, val)运行时参数形式的读写适用于 union 场景见 bindgen/codegen/mod.rsget_const::BIT_OFFSET, BIT_WIDTH()/set_const::BIT_OFFSET, BIT_WIDTH()基于 const 泛型编译期优化的读写位偏移与宽度在编译期已知时可直接内联是普通结构体位域 getter/setter 的默认实现见 bindgen/codegen/mod.rs 与 bindgen/codegen/bitfield_unit.rsraw_get/raw_set/raw_get_const/raw_set_const基于裸指针的版本供生成的field_raw/set_field_raw方法使用可在不持有self/mut self引用的场景如通过指针遍历数组下直接操作位域见 bindgen/codegen/mod.rsget_bit/set_bit单比特读写辅助方法。其中get/set的核心逻辑是按bit_offset定位起始字节按bit_width计算需要跨越的字节数bytes_needed (bit_width bit_shift 7) / 8逐字节拼装或掩码写入并在小端/大端cfg!(target_endian big)平台上分别做reverse_bits处理确保与 C 侧内存布局一致。set会先对写入值做val ((1 bit_width) - 1)掩码操作——这正是下文「溢出归零」行为的底层来源。该类型同样被单独测试覆盖见 bindgen/codegen/bitfield_unit_tests.rs其中验证了跨字节位域、移位偏移、大小端路径等边界情况。物理字段的命名与类型物理字段统一命名为_bitfield_N其类型由helpers::bitfield_unit生成__BindgenBitfieldUnit[u8; size]其中size为该连续位域块占用的字节数见 bindgen/codegen/helpers.rs。命名与编号逻辑位于 bindgen/codegen/mod.rslet unit_field_name format!(_bitfield_{}, self.nth());当启用 C 命名空间enable_cxx_namespaces时位域单元类型会以root::__BindgenBitfieldUnit...的形式生成。getter 与 setter 的使用示例生成绑定后可以在 Rust 侧像调用普通方法一样操作位域。文档给出的演示如下let mut bfield unsafe { create_bitfield() }; bfield.set_a(1); println!(a set to {}, bfield.a()); bfield.set_b(1); println!(b set to {}, bfield.b()); bfield.set_c(3); println!(c set to {}, bfield.c()); unsafe { print_bitfield(bfield) };输出a set to 1 b set to 1 c set to 3 StructWithBitfields: a:1, b:1, c:3这里set_a(1)的1是逻辑值bindgen 生成的 setter 内部会将其转换为对应比特区间的写入let val: u16 val as _; self._bitfield_1.set_const::0usize, 1u8(val as u64)getter 则反向读取并还原为逻辑值self._bitfield_1.get_const::0usize, 1u8() as u16 as _具体形态可对照期望输出 bindgen-tests/tests/expectations/tests/struct_with_bitfields.rs。与 C 位域同名方法的冲突处理若 C 侧同时存在位域字段和同名方法如char type_ : 3;与char type();bindgen 会通过命名规则避免冲突。相关测试见头文件 bindgen-tests/tests/headers/bitfield-method-same-name.hpp 与期望输出 bindgen-tests/tests/expectations/tests/bitfield-method-same-name.rs。位域溢出与 C/C 一致的归零行为对位域写入超过其位宽的值时行为与 C/C 一致位域将被置为 0。这是因为生成的 setter 与__BindgenBitfieldUnit::set会先执行掩码操作val ((1u64 bit_width) - 1)见 bindgen/codegen/bitfield_unit.rs超出位宽的高位被丢弃随后写回的低位恰好为零。文档演示的溢出场景let mut bfield unsafe { create_bitfield() }; bfield.set_a(1); bfield.set_b(1); bfield.set_c(12); println!(c set to {} due to overflow, bfield.c()); unsafe { print_bitfield(bfield) };输出c set to 0 due to overflow StructWithBitfields: a:1, b:1, c:0c位宽为 212二进制1100的低 2 位为0因此写入后c读回为 0同时不影响相邻位域a、b的值——掩码操作只作用于c所在的比特区间。在 Rust 中创建新的位域结构体除通过 FFI 函数获取位域值外还可以在 Rust 侧直接构造带位域的 struct。文档给出的方式是使用位域分配单元构造器new_bitfield_1let bfield StructWithBitfields{ _bitfield_1: StructWithBitfields::new_bitfield_1(0,0,0), ..Default::default() }; unsafe { print_bitfield(bfield) };输出StructWithBitfields: a:0, b:0, c:0前置条件必须开启derive_default注意使用该构造方式要求Builder的derive_default为true否则生成的结构体不会实现Default..Default::default()将无法编译。文档中对应的 Builder 方法为derive_default/// Whether we should derive Default when possible. pub fn derive_default(mut self, doit: bool) - Self { self.options.derive_default doit; self }对应命令行参数为--with-derive-default/--no-derive-default解析逻辑见 bindgen/options/cli.rs默认不派生Default。在build.rs中开启方式let bindings bindgen::Builder::default() .header(wrapper.h) .derive_default(true) .generate()?;构造器生成的边界条件构造器并非无条件生成。从 bindgen/codegen/mod.rs 可以看到两个限制物理字段的存储类型必须能实现AsRef[u8]/AsMut[u8]且能派生Default构造器内部通过Default::default()创建初始单元见new_bitfield_1的实现 bindgen-tests/tests/expectations/tests/struct_with_bitfields.rs物理字段大小需满足layout.size RUST_DERIVE_IN_ARRAY_LIMIT即默认 32 项限制larger_arrays选项不影响该判断且块内所有位域必须可表示为整数类型匿名位域无名字段不参与构造器参数但块内其他位域仍会生成。构造器命名由 bindgen/codegen/mod.rs 中的ctor_name决定fn ctor_name(self) - proc_macro2::TokenStream { let ctor_name Ident::new( format!(new_bitfield_{}, self.nth()), Span::call_site(), ); quote! { #ctor_name } }nth编号从 1 开始对应结构体中第 N 个连续位域块。每个参数会通过set_const::offset, width写入对应比特区间见extend_ctor_implbindgen/codegen/mod.rs。通过--blocklist-type替换位域单元类型__BindgenBitfieldUnit和其他类型一样可以通过--blocklist-type排除在生成绑定之外--blocklist-type __BindgenBitfieldUnit这在两种场景下特别有用自定义位域实现如果你的项目对位域读写有特殊的性能或语义要求可以自己实现一个同名同布局的位域单元类型并让它实现 getter/setter 所需的接口复用已有定义当生成的绑定需要导入一个预先存在的__BindgenBitfieldUnit定义例如多个绑定模块共享同一份位域工具代码时避免重复生成导致类型冲突。仓库中有对应的集成测试头文件 bindgen-tests/tests/headers/blocklist_bitfield_unit.h 通过--blocklist-type __BindgenBitfieldUnit配合--raw-line引入外部定义验证了 blocklist 后结构体仍能正确引用外部位域单元类型。位域行为相关的测试用例bindgen 的测试套件bindgen-tests/tests覆盖了位域的各种边界情况可作为理解与验证上述行为的参考基础读取与构造struct_with_bitfields.h → struct_with_bitfields.rs包含 4 个连续位域块、匿名位域:1、:2无名字段、32 位大位域unsigned int g : 32与两个物理字段_bitfield_1/_bitfield_2的完整 getter/setter/raw/构造器生成溢出行为bitfield-32bit-overflow.h、bitfield_large_overflow.hpp位域与枚举bitfield-enum-basic.hpp、bitfield-enum-repr-c.hpp、bitfield-enum-repr-transparent.hppgetter 会通过transmute将整数转换为枚举类型见 bindgen/codegen/mod.rs位域与 unionunion_bitfield.hunion 场景下 getter/setter 使用运行时参数的get/set并以unsafe包裹打包与对齐packed-bitfield.h、bitfield_align.h、bitfield_pack_offset.h、bitfield_pragma_packed.h模板与命名冲突bitfield-template.hpp、bitfield-method-same-name.hpp单元测试bindgen/codegen/bitfield_unit_tests.rs 直接验证__BindgenBitfieldUnit的跨字节读写、边界偏移与大端路径。小结bindgen 通过「__BindgenBitfieldUnit不透明物理字段 命名 getter/setter new_bitfield_N构造器」三件套把 C/C 位域完整地映射到 Rust FFI 层读取使用field()写入使用set_field(val)底层分别调用get_const/set_const或 union 场景下的get/set溢出行为与 C/C 一致置 0源自 setter 的按位宽掩码在 Rust 侧构造带位域结构体时使用new_bitfield_N(...)配合..Default::default()前提是开启derive_default(true)CLI 为--with-derive-default需要自定义或复用位域单元实现时用--blocklist-type __BindgenBitfieldUnit排除默认生成。掌握这套机制后你就可以放心地在 Rust 中读写任何来自 C/C 头文件的位域结构体而无需手动做比特运算。赞分享【免费下载链接】rust-bindgenAutomatically generates Rust FFI bindings to C (and some C) libraries.项目地址https://gitcode.com/gh_mirrors/ru/rust-bindgen点击查看免费下载相关推荐wasm-bindgen 属性指南用 getter 与 setter 在 Rust 中定义 JavaScript 类属性wasm bindgen 属性指南用 getter 与 setter 在 Rust 中定义 JavaScript 类属性 本文是 wasm bindgen 属开发工具wasm-bindgen 中 getter 与 setter 属性完全指南从 JavaScript 属性绑定到 Symbol 访问器wasm bindgen 中 getter 与 setter 属性完全指南从 JavaScript 属性绑定到 Symbol 访问器 本指南聚焦 wasm b开发工具Aptos Core Rebase 指南处理 cached-packages 框架工件冲突的完整实战Aptos Core Rebase 指南处理 cached packages 框架工件冲突的完整实战 导读 在 Aptos 仓库aptos core中修改开发工具上一篇HelloGitHub 第 24 期开源项目精选23 个入门级项目全景解读与实战代码下一篇终极指南用OpenCore Legacy Patcher让老Mac焕发新生轻松升级最新macOS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考