Debian Codegraph @

.cargo/vendor/bindgen/options/mod.rs

raw
1 //! Declarations and setter methods for `bindgen` options.
2 //!
3 //! The main entry point of this module is the `options` macro.
4 #[macro_use]
5 mod helpers;
6 mod as_args;
7
8 use crate::callbacks::ParseCallbacks;
9 use crate::codegen::{
10 AliasVariation, EnumVariation, MacroTypeVariation, NonCopyUnionStyle,
11 };
12 use crate::deps::DepfileSpec;
13 use crate::features::{RustFeatures, RustTarget};
14 use crate::regex_set::RegexSet;
15 use crate::Abi;
16 use crate::Builder;
17 use crate::CodegenConfig;
18 use crate::FieldVisibilityKind;
19 use crate::Formatter;
20 use crate::HashMap;
21 use crate::DEFAULT_ANON_FIELDS_PREFIX;
22
23 use std::env;
24 #[cfg(feature = "experimental")]
25 use std::path::Path;
26 use std::path::PathBuf;
27 use std::rc::Rc;
28
29 use as_args::AsArgs;
30 use helpers::ignore;
31
32 /// Macro used to generate the [`BindgenOptions`] type and the [`Builder`] setter methods for each
33 /// one of the fields of `BindgenOptions`.
34 ///
35 /// The input format of this macro resembles a `struct` pattern. Each field of the `BindgenOptions`
36 /// type is declared by adding the name of the field and its type using the `name: type` syntax and
37 /// a block of code with the following items:
38 ///
39 /// - `default`: The default value for the field. If this item is omitted, `Default::default()` is
40 /// used instead, meaning that the type of the field must implement `Default`.
41 /// - `methods`: A block of code containing methods for the `Builder` type. These methods should be
42 /// related to the field being declared.
43 /// - `as_args`: This item declares how the field should be converted into a valid CLI argument for
44 /// `bindgen` and is used in the [`Builder::command_line_flags`] method which is used to do a
45 /// roundtrip test of the CLI args in the `bindgen-test` crate. This item can take one of the
46 /// following:
47 /// - A string literal with the flag if the type of the field implements the [`AsArgs`] trait.
48 /// - A closure with the signature `|field, args: &mut Vec<String>| -> ()` that pushes arguments
49 /// into the `args` buffer based on the value of the field. This is used if the field does not
50 /// implement `AsArgs` or if the implementation of the trait is not logically correct for the
51 /// option and a custom behavior must be taken into account.
52 /// - The `ignore` literal, which does not emit any CLI arguments for this field. This is useful
53 /// if the field cannot be used from the `bindgen` CLI.
54 ///
55 /// As an example, this would be the declaration of a `bool` field called `be_fun` whose default
56 /// value is `false` (the `Default` value for `bool`):
57 /// ```rust,ignore
58 /// be_fun: bool {
59 /// methods: {
60 /// /// Ask `bindgen` to be fun. This option is disabled by default.
61 /// fn be_fun(mut self) -> Self {
62 /// self.options.be_fun = true;
63 /// self
64 /// }
65 /// },
66 /// as_args: "--be-fun",
67 /// }
68 /// ```
69 ///
70 /// However, we could also set the `be_fun` field to `true` by default and use a `--not-fun` flag
71 /// instead. This means that we have to add the `default` item and use a closure in the `as_args`
72 /// item:
73 /// ```rust,ignore
74 /// be_fun: bool {
75 /// default: true,
76 /// methods: {
77 /// /// Ask `bindgen` to not be fun. `bindgen` is fun by default.
78 /// fn not_fun(mut self) -> Self {
79 /// self.options.be_fun = false;
80 /// self
81 /// }
82 /// },
83 /// as_args: |be_fun, args| (!be_fun).as_args(args, "--not-fun"),
84 /// }
85 /// ```
86 /// More complex examples can be found in the sole invocation of this macro.
87 macro_rules! options {
88 ($(
89 $(#[doc = $docs:literal])+
90 $field:ident: $ty:ty {
91 $(default: $default:expr,)?
92 methods: {$($methods_tokens:tt)*}$(,)?
93 as_args: $as_args:expr$(,)?
94 }$(,)?
95 )*) => {
96 #[derive(Debug, Clone)]
97 pub(crate) struct BindgenOptions {
98 $($(#[doc = $docs])* pub(crate) $field: $ty,)*
99 }
100
101 impl Default for BindgenOptions {
102 fn default() -> Self {
103 Self {
104 $($field: default!($($default)*),)*
105 }
106 }
107 }
108
109 impl Builder {
110 /// Generates the command line flags used to create this [`Builder`].
111 pub fn command_line_flags(&self) -> Vec<String> {
112 let mut args = vec![];
113
114 let headers = match self.options.input_headers.split_last() {
115 Some((header, headers)) => {
116 // The last input header is passed as an argument in the first position.
117 args.push(header.clone());
118 headers
119 },
120 None => &[]
121 };
122
123 $({
124 let func: fn(&$ty, &mut Vec<String>) = as_args!($as_args);
125 func(&self.options.$field, &mut args);
126 })*
127
128 // Add the `--experimental` flag if `bindgen` is built with the `experimental`
129 // feature.
130 if cfg!(feature = "experimental") {
131 args.push("--experimental".to_owned());
132 }
133
134 // Add all the clang arguments.
135 args.push("--".to_owned());
136
137 if !self.options.clang_args.is_empty() {
138 args.extend_from_slice(&self.options.clang_args);
139 }
140
141 // We need to pass all but the last header via the `-include` clang argument.
142 for header in headers {
143 args.push("-include".to_owned());
144 args.push(header.clone());
145 }
146
147 args
148 }
149
150 $($($methods_tokens)*)*
151 }
152 };
153 }
154
155 options! {
156 /// Types that have been blocklisted and should not appear anywhere in the generated code.
157 blocklisted_types: RegexSet {
158 methods: {
159 regex_option! {
160 /// Do not generate any bindings for the given type.
161 pub fn blocklist_type<T: AsRef<str>>(mut self, arg: T) -> Builder {
162 self.options.blocklisted_types.insert(arg);
163 self
164 }
165 }
166 },
167 as_args: "--blocklist-type",
168 },
169 /// Functions that have been blocklisted and should not appear in the generated code.
170 blocklisted_functions: RegexSet {
171 methods: {
172 regex_option! {
173 /// Do not generate any bindings for the given function.
174 pub fn blocklist_function<T: AsRef<str>>(mut self, arg: T) -> Builder {
175 self.options.blocklisted_functions.insert(arg);
176 self
177 }
178 }
179 },
180 as_args: "--blocklist-function",
181 },
182 /// Items that have been blocklisted and should not appear in the generated code.
183 blocklisted_items: RegexSet {
184 methods: {
185 regex_option! {
186 /// Do not generate any bindings for the given item, regardless of whether it is a
187 /// type, function, module, etc.
188 pub fn blocklist_item<T: AsRef<str>>(mut self, arg: T) -> Builder {
189 self.options.blocklisted_items.insert(arg);
190 self
191 }
192 }
193 },
194 as_args: "--blocklist-item",
195 },
196 /// Files whose contents should be blocklisted and should not appear in the generated code.
197 blocklisted_files: RegexSet {
198 methods: {
199 regex_option! {
200 /// Do not generate any bindings for the contents of the given file, regardless of
201 /// whether the contents of the file are types, functions, modules, etc.
202 pub fn blocklist_file<T: AsRef<str>>(mut self, arg: T) -> Builder {
203 self.options.blocklisted_files.insert(arg);
204 self
205 }
206 }
207 },
208 as_args: "--blocklist-file",
209 },
210 /// Types that should be treated as opaque structures in the generated code.
211 opaque_types: RegexSet {
212 methods: {
213 regex_option! {
214 /// Treat the given type as opaque in the generated bindings.
215 ///
216 /// Opaque in this context means that none of the generated bindings will contain
217 /// information about the inner representation of the type and the type itself will
218 /// be represented as a chunk of bytes with the alignment and size of the type.
219 pub fn opaque_type<T: AsRef<str>>(mut self, arg: T) -> Builder {
220 self.options.opaque_types.insert(arg);
221 self
222 }
223 }
224 },
225 as_args: "--opaque-type",
226 },
227 /// The explicit `rustfmt` path.
228 rustfmt_path: Option<PathBuf> {
229 methods: {
230 /// Set an explicit path to the `rustfmt` binary.
231 ///
232 /// This option only comes into effect if `rustfmt` is set to be the formatter used by
233 /// `bindgen`. Check the documentation of the [`Builder::formatter`] method for more
234 /// information.
235 pub fn with_rustfmt<P: Into<PathBuf>>(mut self, path: P) -> Self {
236 self.options.rustfmt_path = Some(path.into());
237 self
238 }
239 },
240 // This option cannot be set from the CLI.
241 as_args: ignore,
242 },
243 /// The path to which we should write a Makefile-syntax depfile (if any).
244 depfile: Option<DepfileSpec> {
245 methods: {
246 /// Add a depfile output which will be written alongside the generated bindings.
247 pub fn depfile<H: Into<String>, D: Into<PathBuf>>(
248 mut self,
249 output_module: H,
250 depfile: D,
251 ) -> Builder {
252 self.options.depfile = Some(DepfileSpec {
253 output_module: output_module.into(),
254 depfile_path: depfile.into(),
255 });
256 self
257 }
258 },
259 as_args: |depfile, args| {
260 if let Some(depfile) = depfile {
261 args.push("--depfile".into());
262 args.push(depfile.depfile_path.display().to_string());
263 }
264 },
265 },
266 /// Types that have been allowlisted and should appear in the generated code.
267 allowlisted_types: RegexSet {
268 methods: {
269 regex_option! {
270 /// Generate bindings for the given type.
271 ///
272 /// This option is transitive by default. Check the documentation of the
273 /// [`Builder::allowlist_recursively`] method for further information.
274 pub fn allowlist_type<T: AsRef<str>>(mut self, arg: T) -> Builder {
275 self.options.allowlisted_types.insert(arg);
276 self
277 }
278 }
279 },
280 as_args: "--allowlist-type",
281 },
282 /// Functions that have been allowlisted and should appear in the generated code.
283 allowlisted_functions: RegexSet {
284 methods: {
285 regex_option! {
286 /// Generate bindings for the given function.
287 ///
288 /// This option is transitive by default. Check the documentation of the
289 /// [`Builder::allowlist_recursively`] method for further information.
290 pub fn allowlist_function<T: AsRef<str>>(mut self, arg: T) -> Builder {
291 self.options.allowlisted_functions.insert(arg);
292 self
293 }
294 }
295 },
296 as_args: "--allowlist-function",
297 },
298 /// Variables that have been allowlisted and should appear in the generated code.
299 allowlisted_vars: RegexSet {
300 methods: {
301 regex_option! {
302 /// Generate bindings for the given variable.
303 ///
304 /// This option is transitive by default. Check the documentation of the
305 /// [`Builder::allowlist_recursively`] method for further information.
306 pub fn allowlist_var<T: AsRef<str>>(mut self, arg: T) -> Builder {
307 self.options.allowlisted_vars.insert(arg);
308 self
309 }
310 }
311 },
312 as_args: "--allowlist-var",
313 },
314 /// Files whose contents have been allowlisted and should appear in the generated code.
315 allowlisted_files: RegexSet {
316 methods: {
317 regex_option! {
318 /// Generate bindings for the content of the given file.
319 ///
320 /// This option is transitive by default. Check the documentation of the
321 /// [`Builder::allowlist_recursively`] method for further information.
322 pub fn allowlist_file<T: AsRef<str>>(mut self, arg: T) -> Builder {
323 self.options.allowlisted_files.insert(arg);
324 self
325 }
326 }
327 },
328 as_args: "--allowlist-file",
329 },
330 /// The default style of for generated `enum`s.
331 default_enum_style: EnumVariation {
332 methods: {
333 /// Set the default style for generated `enum`s.
334 ///
335 /// If this method is not called, the [`EnumVariation::Consts`] style will be used by
336 /// default.
337 ///
338 /// To set the style for individual `enum`s, use [`Builder::bitfield_enum`],
339 /// [`Builder::newtype_enum`], [`Builder::newtype_global_enum`],
340 /// [`Builder::rustified_enum`], [`Builder::rustified_non_exhaustive_enum`],
341 /// [`Builder::constified_enum_module`] or [`Builder::constified_enum`].
342 pub fn default_enum_style(
343 mut self,
344 arg: EnumVariation,
345 ) -> Builder {
346 self.options.default_enum_style = arg;
347 self
348 }
349 },
350 as_args: |variation, args| {
351 if *variation != Default::default() {
352 args.push("--default-enum-style".to_owned());
353 args.push(variation.to_string());
354 }
355 },
356 },
357 /// `enum`s marked as bitfield-like. This is, newtypes with bitwise operations.
358 bitfield_enums: RegexSet {
359 methods: {
360 regex_option! {
361 /// Mark the given `enum` as being bitfield-like.
362 ///
363 /// This is similar to the [`Builder::newtype_enum`] style, but with the bitwise
364 /// operators implemented.
365 pub fn bitfield_enum<T: AsRef<str>>(mut self, arg: T) -> Builder {
366 self.options.bitfield_enums.insert(arg);
367 self
368 }
369 }
370 },
371 as_args: "--bitfield-enum",
372 },
373 /// `enum`s marked as newtypes.
374 newtype_enums: RegexSet {
375 methods: {
376 regex_option! {
377 /// Mark the given `enum` as a newtype.
378 ///
379 /// This means that an integer newtype will be declared to represent the `enum`
380 /// type and its variants will be represented as constants inside of this type's
381 /// `impl` block.
382 pub fn newtype_enum<T: AsRef<str>>(mut self, arg: T) -> Builder {
383 self.options.newtype_enums.insert(arg);
384 self
385 }
386 }
387 },
388 as_args: "--newtype-enum",
389 },
390 /// `enum`s marked as global newtypes .
391 newtype_global_enums: RegexSet {
392 methods: {
393 regex_option! {
394 /// Mark the given `enum` as a global newtype.
395 ///
396 /// This is similar to the [`Builder::newtype_enum`] style, but the constants for
397 /// each variant are free constants instead of being declared inside an `impl`
398 /// block for the newtype.
399 pub fn newtype_global_enum<T: AsRef<str>>(mut self, arg: T) -> Builder {
400 self.options.newtype_global_enums.insert(arg);
401 self
402 }
403 }
404 },
405 as_args: "--newtype-global-enum",
406 },
407 /// `enum`s marked as Rust `enum`s.
408 rustified_enums: RegexSet {
409 methods: {
410 regex_option! {
411 /// Mark the given `enum` as a Rust `enum`.
412 ///
413 /// This means that each variant of the `enum` will be represented as a Rust `enum`
414 /// variant.
415 ///
416 /// **Use this with caution**, creating an instance of a Rust `enum` with an
417 /// invalid value will cause undefined behaviour. To avoid this, use the
418 /// [`Builder::newtype_enum`] style instead.
419 pub fn rustified_enum<T: AsRef<str>>(mut self, arg: T) -> Builder {
420 self.options.rustified_enums.insert(arg);
421 self
422 }
423 }
424 },
425 as_args: "--rustified-enum",
426 },
427 /// `enum`s marked as non-exhaustive Rust `enum`s.
428 rustified_non_exhaustive_enums: RegexSet {
429 methods: {
430 regex_option! {
431 /// Mark the given `enum` as a non-exhaustive Rust `enum`.
432 ///
433 /// This is similar to the [`Builder::rustified_enum`] style, but the `enum` is
434 /// tagged with the `#[non_exhaustive]` attribute.
435 pub fn rustified_non_exhaustive_enum<T: AsRef<str>>(mut self, arg: T) -> Builder {
436 self.options.rustified_non_exhaustive_enums.insert(arg);
437 self
438 }
439 }
440 },
441 as_args: "--rustified-non-exhaustive-enums",
442 },
443 /// `enum`s marked as modules of constants.
444 constified_enum_modules: RegexSet {
445 methods: {
446 regex_option! {
447 /// Mark the given `enum` as a module with a set of integer constants.
448 pub fn constified_enum_module<T: AsRef<str>>(mut self, arg: T) -> Builder {
449 self.options.constified_enum_modules.insert(arg);
450 self
451 }
452 }
453 },
454 as_args: "--constified-enum-module",
455 },
456 /// `enum`s marked as a set of constants.
457 constified_enums: RegexSet {
458 methods: {
459 regex_option! {
460 /// Mark the given `enum` as a set o integer constants.
461 ///
462 /// This is similar to the [`Builder::constified_enum_module`] style, but the
463 /// constants are generated in the current module instead of in a new module.
464 pub fn constified_enum<T: AsRef<str>>(mut self, arg: T) -> Builder {
465 self.options.constified_enums.insert(arg);
466 self
467 }
468 }
469 },
470 as_args: "--constified-enum",
471 },
472 /// The default type signedness for C macro constants.
473 default_macro_constant_type: MacroTypeVariation {
474 methods: {
475 /// Set the default type signedness to be used for macro constants.
476 ///
477 /// If this method is not called, [`MacroTypeVariation::Unsigned`] is used by default.
478 ///
479 /// To set the type for individual macro constants, use the
480 /// [`ParseCallbacks::int_macro`] method.
481 pub fn default_macro_constant_type(mut self, arg: MacroTypeVariation) -> Builder {
482 self.options.default_macro_constant_type = arg;
483 self
484 }
485
486 },
487 as_args: |variation, args| {
488 if *variation != Default::default() {
489 args.push("--default-macro-constant-type".to_owned());
490 args.push(variation.to_string());
491 }
492 },
493 },
494 /// The default style of code generation for `typedef`s.
495 default_alias_style: AliasVariation {
496 methods: {
497 /// Set the default style of code generation for `typedef`s.
498 ///
499 /// If this method is not called, the [`AliasVariation::TypeAlias`] style is used by
500 /// default.
501 ///
502 /// To set the style for individual `typedefs`s, use [`Builder::type_alias`],
503 /// [`Builder::new_type_alias`] or [`Builder::new_type_alias_deref`].
504 pub fn default_alias_style(
505 mut self,
506 arg: AliasVariation,
507 ) -> Builder {
508 self.options.default_alias_style = arg;
509 self
510 }
511 },
512 as_args: |variation, args| {
513 if *variation != Default::default() {
514 args.push("--default-alias-style".to_owned());
515 args.push(variation.to_string());
516 }
517 },
518 },
519 /// `typedef` patterns that will use regular type aliasing.
520 type_alias: RegexSet {
521 methods: {
522 regex_option! {
523 /// Mark the given `typedef` as a regular Rust `type` alias.
524 ///
525 /// This is the default behavior, meaning that this method only comes into effect
526 /// if a style different from [`AliasVariation::TypeAlias`] was passed to the
527 /// [`Builder::default_alias_style`] method.
528 pub fn type_alias<T: AsRef<str>>(mut self, arg: T) -> Builder {
529 self.options.type_alias.insert(arg);
530 self
531 }
532 }
533 },
534 as_args: "--type-alias",
535 },
536 /// `typedef` patterns that will be aliased by creating a newtype.
537 new_type_alias: RegexSet {
538 methods: {
539 regex_option! {
540 /// Mark the given `typedef` as a Rust newtype by having the aliased
541 /// type be wrapped in a `struct` with `#[repr(transparent)]`.
542 ///
543 /// This method can be used to enforce stricter type checking.
544 pub fn new_type_alias<T: AsRef<str>>(mut self, arg: T) -> Builder {
545 self.options.new_type_alias.insert(arg);
546 self
547 }
548 }
549 },
550 as_args: "--new-type-alias",
551 },
552 /// `typedef` patterns that will be wrapped in a newtype implementing `Deref` and `DerefMut`.
553 new_type_alias_deref: RegexSet {
554 methods: {
555 regex_option! {
556 /// Mark the given `typedef` to be generated as a newtype that can be dereferenced.
557 ///
558 /// This is similar to the [`Builder::new_type_alias`] style, but the newtype
559 /// implements `Deref` and `DerefMut` with the aliased type as a target.
560 pub fn new_type_alias_deref<T: AsRef<str>>(mut self, arg: T) -> Builder {
561 self.options.new_type_alias_deref.insert(arg);
562 self
563 }
564 }
565 },
566 as_args: "--new-type-alias-deref",
567 },
568 /// The default style of code to generate for `union`s containing non-`Copy` members.
569 default_non_copy_union_style: NonCopyUnionStyle {
570 methods: {
571 /// Set the default style of code to generate for `union`s with non-`Copy` members.
572 ///
573 /// If this method is not called, the [`NonCopyUnionStyle::BindgenWrapper`] style is
574 /// used by default.
575 ///
576 /// To set the style for individual `union`s, use [`Builder::bindgen_wrapper_union`] or
577 /// [`Builder::manually_drop_union`].
578 pub fn default_non_copy_union_style(mut self, arg: NonCopyUnionStyle) -> Self {
579 self.options.default_non_copy_union_style = arg;
580 self
581 }
582 },
583 as_args: |style, args| {
584 if *style != Default::default() {
585 args.push("--default-non-copy-union-style".to_owned());
586 args.push(style.to_string());
587 }
588 },
589 },
590 /// The patterns marking non-`Copy` `union`s as using the `bindgen` generated wrapper.
591 bindgen_wrapper_union: RegexSet {
592 methods: {
593 regex_option! {
594 /// Mark the given `union` to use a `bindgen`-generated wrapper for its members if at
595 /// least one them is not `Copy`.
596 ///
597 /// This is the default behavior, meaning that this method only comes into effect
598 /// if a style different from [`NonCopyUnionStyle::BindgenWrapper`] was passed to
599 /// the [`Builder::default_non_copy_union_style`] method.
600 pub fn bindgen_wrapper_union<T: AsRef<str>>(mut self, arg: T) -> Self {
601 self.options.bindgen_wrapper_union.insert(arg);
602 self
603 }
604 }
605 },
606 as_args: "--bindgen-wrapper-union",
607 },
608 /// The patterns marking non-`Copy` `union`s as using the `ManuallyDrop` wrapper.
609 manually_drop_union: RegexSet {
610 methods: {
611 regex_option! {
612 /// Mark the given `union` to use [`::core::mem::ManuallyDrop`] for its members if
613 /// at least one of them is not `Copy`.
614 ///
615 /// The `ManuallyDrop` type was stabilized in Rust 1.20.0, do not use this option
616 /// if your target version is lower than this.
617 pub fn manually_drop_union<T: AsRef<str>>(mut self, arg: T) -> Self {
618 self.options.manually_drop_union.insert(arg);
619 self
620 }
621 }
622
623 },
624 as_args: "--manually-drop-union",
625 },
626
627
628 /// Whether we should generate built-in definitions.
629 builtins: bool {
630 methods: {
631 /// Generate Rust bindings for built-in definitions (for example `__builtin_va_list`).
632 ///
633 /// Bindings for built-in definitions are not emitted by default.
634 pub fn emit_builtins(mut self) -> Builder {
635 self.options.builtins = true;
636 self
637 }
638 },
639 as_args: "--builtins",
640 },
641 /// Whether we should dump the Clang AST for debugging purposes.
642 emit_ast: bool {
643 methods: {
644 /// Emit the Clang AST to `stdout` for debugging purposes.
645 ///
646 /// The Clang AST is not emitted by default.
647 pub fn emit_clang_ast(mut self) -> Builder {
648 self.options.emit_ast = true;
649 self
650 }
651 },
652 as_args: "--emit-clang-ast",
653 },
654 /// Whether we should dump our IR for debugging purposes.
655 emit_ir: bool {
656 methods: {
657 /// Emit the `bindgen` internal representation to `stdout` for debugging purposes.
658 ///
659 /// This internal representation is not emitted by default.
660 pub fn emit_ir(mut self) -> Builder {
661 self.options.emit_ir = true;
662 self
663 }
664 },
665 as_args: "--emit-ir",
666 },
667 /// Output path for the `graphviz` DOT file.
668 emit_ir_graphviz: Option<String> {
669 methods: {
670 /// Set the path for the file where the`bindgen` internal representation will be
671 /// emitted as a graph using the `graphviz` DOT language.
672 ///
673 /// This graph representation is not emitted by default.
674 pub fn emit_ir_graphviz<T: Into<String>>(mut self, path: T) -> Builder {
675 let path = path.into();
676 self.options.emit_ir_graphviz = Some(path);
677 self
678 }
679 },
680 as_args: "--emit-ir-graphviz",
681 },
682
683 /// Whether we should emulate C++ namespaces with Rust modules.
684 enable_cxx_namespaces: bool {
685 methods: {
686 /// Emulate C++ namespaces using Rust modules in the generated bindings.
687 ///
688 /// C++ namespaces are not emulated by default.
689 pub fn enable_cxx_namespaces(mut self) -> Builder {
690 self.options.enable_cxx_namespaces = true;
691 self
692 }
693 },
694 as_args: "--enable-cxx-namespaces",
695 },
696 /// Whether we should try to find unexposed attributes in functions.
697 enable_function_attribute_detection: bool {
698 methods: {
699 /// Enable detecting function attributes on C functions.
700 ///
701 /// This enables the following features:
702 /// - Add `#[must_use]` attributes to Rust items whose C counterparts are marked as so.
703 /// This feature also requires that the Rust target version supports the attribute.
704 /// - Set `!` as the return type for Rust functions whose C counterparts are marked as
705 /// diverging.
706 ///
707 /// This option can be quite slow in some cases (check [#1465]), so it is disabled by
708 /// default.
709 ///
710 /// [#1465]: https://github.com/rust-lang/rust-bindgen/issues/1465
711 pub fn enable_function_attribute_detection(mut self) -> Self {
712 self.options.enable_function_attribute_detection = true;
713 self
714 }
715
716 },
717 as_args: "--enable-function-attribute-detection",
718 },
719 /// Whether we should avoid mangling names with namespaces.
720 disable_name_namespacing: bool {
721 methods: {
722 /// Disable name auto-namespacing.
723 ///
724 /// By default, `bindgen` mangles names like `foo::bar::Baz` to look like `foo_bar_Baz`
725 /// instead of just `Baz`. This method disables that behavior.
726 ///
727 /// Note that this does not change the names used for allowlisting and blocklisting,
728 /// which should still be mangled with the namespaces. Additionally, this option may
729 /// cause `bindgen` to generate duplicate names.
730 pub fn disable_name_namespacing(mut self) -> Builder {
731 self.options.disable_name_namespacing = true;
732 self
733 }
734 },
735 as_args: "--disable-name-namespacing",
736 },
737 /// Whether we should avoid generating nested `struct` names.
738 disable_nested_struct_naming: bool {
739 methods: {
740 /// Disable nested `struct` naming.
741 ///
742 /// The following `struct`s have different names for C and C++. In C, they are visible
743 /// as `foo` and `bar`. In C++, they are visible as `foo` and `foo::bar`.
744 ///
745 /// ```c
746 /// struct foo {
747 /// struct bar {
748 /// } b;
749 /// };
750 /// ```
751 ///
752 /// `bindgen` tries to avoid duplicate names by default, so it follows the C++ naming
753 /// convention and it generates `foo` and `foo_bar` instead of just `foo` and `bar`.
754 ///
755 /// This method disables this behavior and it is indented to be used only for headers
756 /// that were written in C.
757 pub fn disable_nested_struct_naming(mut self) -> Builder {
758 self.options.disable_nested_struct_naming = true;
759 self
760 }
761 },
762 as_args: "--disable-nested-struct-naming",
763 },
764 /// Whether we should avoid embedding version identifiers into source code.
765 disable_header_comment: bool {
766 methods: {
767 /// Do not insert the `bindgen` version identifier into the generated bindings.
768 ///
769 /// This identifier is inserted by default.
770 pub fn disable_header_comment(mut self) -> Self {
771 self.options.disable_header_comment = true;
772 self
773 }
774
775 },
776 as_args: "--disable-header-comment",
777 },
778 /// Whether we should generate layout tests for generated `struct`s.
779 layout_tests: bool {
780 default: true,
781 methods: {
782 /// Set whether layout tests should be generated.
783 ///
784 /// Layout tests are generated by default.
785 pub fn layout_tests(mut self, doit: bool) -> Self {
786 self.options.layout_tests = doit;
787 self
788 }
789 },
790 as_args: |value, args| (!value).as_args(args, "--no-layout-tests"),
791 },
792 /// Whether we should implement `Debug` for types that cannot derive it.
793 impl_debug: bool {
794 methods: {
795 /// Set whether `Debug` should be implemented for types that cannot derive it.
796 ///
797 /// This option is disabled by default.
798 pub fn impl_debug(mut self, doit: bool) -> Self {
799 self.options.impl_debug = doit;
800 self
801 }
802
803 },
804 as_args: "--impl-debug",
805 },
806 /// Whether we should implement `PartialEq` types that cannot derive it.
807 impl_partialeq: bool {
808 methods: {
809 /// Set whether `PartialEq` should be implemented for types that cannot derive it.
810 ///
811 /// This option is disabled by default.
812 pub fn impl_partialeq(mut self, doit: bool) -> Self {
813 self.options.impl_partialeq = doit;
814 self
815 }
816 },
817 as_args: "--impl-partialeq",
818 },
819 /// Whether we should derive `Copy` when possible.
820 derive_copy: bool {
821 default: true,
822 methods: {
823 /// Set whether the `Copy` trait should be derived when possible.
824 ///
825 /// `Copy` is derived by default.
826 pub fn derive_copy(mut self, doit: bool) -> Self {
827 self.options.derive_copy = doit;
828 self
829 }
830 },
831 as_args: |value, args| (!value).as_args(args, "--no-derive-copy"),
832 },
833
834 /// Whether we should derive `Debug` when possible.
835 derive_debug: bool {
836 default: true,
837 methods: {
838 /// Set whether the `Debug` trait should be derived when possible.
839 ///
840 /// The [`Builder::impl_debug`] method can be used to implement `Debug` for types that
841 /// cannot derive it.
842 ///
843 /// `Debug` is derived by default.
844 pub fn derive_debug(mut self, doit: bool) -> Self {
845 self.options.derive_debug = doit;
846 self
847 }
848 },
849 as_args: |value, args| (!value).as_args(args, "--no-derive-debug"),
850 },
851
852 /// Whether we should derive `Default` when possible.
853 derive_default: bool {
854 methods: {
855 /// Set whether the `Default` trait should be derived when possible.
856 ///
857 /// `Default` is not derived by default.
858 pub fn derive_default(mut self, doit: bool) -> Self {
859 self.options.derive_default = doit;
860 self
861 }
862 },
863 as_args: |&value, args| {
864 let arg = if value {
865 "--with-derive-default"
866 } else {
867 "--no-derive-default"
868 };
869
870 args.push(arg.to_owned());
871 },
872 },
873 /// Whether we should derive `Hash` when possible.
874 derive_hash: bool {
875 methods: {
876 /// Set whether the `Hash` trait should be derived when possible.
877 ///
878 /// `Hash` is not derived by default.
879 pub fn derive_hash(mut self, doit: bool) -> Self {
880 self.options.derive_hash = doit;
881 self
882 }
883 },
884 as_args: "--with-derive-hash",
885 },
886 /// Whether we should derive `PartialOrd` when possible.
887 derive_partialord: bool {
888 methods: {
889 /// Set whether the `PartialOrd` trait should be derived when possible.
890 ///
891 /// Take into account that `Ord` cannot be derived for a type that does not implement
892 /// `PartialOrd`. For this reason, setting this method to `false` also sets
893 /// automatically [`Builder::derive_ord`] to `false`.
894 ///
895 /// `PartialOrd` is not derived by default.
896 pub fn derive_partialord(mut self, doit: bool) -> Self {
897 self.options.derive_partialord = doit;
898 if !doit {
899 self.options.derive_ord = false;
900 }
901 self
902 }
903 },
904 as_args: "--with-derive-partialord",
905 },
906 /// Whether we should derive `Ord` when possible.
907 derive_ord: bool {
908 methods: {
909 /// Set whether the `Ord` trait should be derived when possible.
910 ///
911 /// Take into account that `Ord` cannot be derived for a type that does not implement
912 /// `PartialOrd`. For this reason, the value set with this method will also be set
913 /// automatically for [`Builder::derive_partialord`].
914 ///
915 /// `Ord` is not derived by default.
916 pub fn derive_ord(mut self, doit: bool) -> Self {
917 self.options.derive_ord = doit;
918 self.options.derive_partialord = doit;
919 self
920 }
921 },
922 as_args: "--with-derive-ord",
923 },
924 /// Whether we should derive `PartialEq` when possible.
925 derive_partialeq: bool {
926 methods: {
927 /// Set whether the `PartialEq` trait should be derived when possible.
928 ///
929 /// Take into account that `Eq` cannot be derived for a type that does not implement
930 /// `PartialEq`. For this reason, setting this method to `false` also sets
931 /// automatically [`Builder::derive_eq`] to `false`.
932 ///
933 /// The [`Builder::impl_partialeq`] method can be used to implement `PartialEq` for
934 /// types that cannot derive it.
935 ///
936 /// `PartialEq` is not derived by default.
937 pub fn derive_partialeq(mut self, doit: bool) -> Self {
938 self.options.derive_partialeq = doit;
939 if !doit {
940 self.options.derive_eq = false;
941 }
942 self
943 }
944 },
945 as_args: "--with-derive-partialeq",
946 },
947 /// Whether we should derive `Eq` when possible.
948 derive_eq: bool {
949 methods: {
950 /// Set whether the `Eq` trait should be derived when possible.
951 ///
952 /// Take into account that `Eq` cannot be derived for a type that does not implement
953 /// `PartialEq`. For this reason, the value set with this method will also be set
954 /// automatically for [`Builder::derive_partialeq`].
955 ///
956 /// `Eq` is not derived by default.
957 pub fn derive_eq(mut self, doit: bool) -> Self {
958 self.options.derive_eq = doit;
959 if doit {
960 self.options.derive_partialeq = doit;
961 }
962 self
963 }
964 },
965 as_args: "--with-derive-eq",
966 },
967 /// Whether we should use `core` instead of `std`.
968 ///
969 /// If this option is enabled and the Rust target version is greater than 1.64, the prefix for
970 /// C platform-specific types will be `::core::ffi` instead of `::core::os::raw`.
971 use_core: bool {
972 methods: {
973 /// Use `core` instead of `std` in the generated bindings.
974 ///
975 /// `std` is used by default.
976 pub fn use_core(mut self) -> Builder {
977 self.options.use_core = true;
978 self
979 }
980
981 },
982 as_args: "--use-core",
983 },
984 /// An optional prefix for the C platform-specific types.
985 ctypes_prefix: Option<String> {
986 methods: {
987 /// Use the given prefix for the C platform-specific types instead of `::std::os::raw`.
988 ///
989 /// Alternatively, the [`Builder::use_core`] method can be used to set the prefix to
990 /// `::core::ffi` or `::core::os::raw`.
991 pub fn ctypes_prefix<T: Into<String>>(mut self, prefix: T) -> Builder {
992 self.options.ctypes_prefix = Some(prefix.into());
993 self
994 }
995 },
996 as_args: "--ctypes-prefix",
997 },
998 /// The prefix for anonymous fields.
999 anon_fields_prefix: String {
1000 default: DEFAULT_ANON_FIELDS_PREFIX.into(),
1001 methods: {
1002 /// Use the given prefix for the anonymous fields.
1003 ///
1004 /// An anonymous field, is a field of a C/C++ type that does not have a name. For
1005 /// example, in the following C code:
1006 /// ```c
1007 /// struct integer {
1008 /// struct {
1009 /// int inner;
1010 /// };
1011 /// }
1012 /// ```
1013 ///
1014 /// The only field of the `integer` `struct` is an anonymous field and its Rust
1015 /// representation will be named using this prefix followed by an integer identifier.
1016 ///
1017 /// The default prefix is `__bindgen_anon_`.
1018 pub fn anon_fields_prefix<T: Into<String>>(mut self, prefix: T) -> Builder {
1019 self.options.anon_fields_prefix = prefix.into();
1020 self
1021 }
1022 },
1023 as_args: |prefix, args| {
1024 if prefix != DEFAULT_ANON_FIELDS_PREFIX {
1025 args.push("--anon-fields-prefix".to_owned());
1026 args.push(prefix.clone());
1027 }
1028 },
1029 },
1030 /// Whether to measure the time for each one of the `bindgen` phases.
1031 time_phases: bool {
1032 methods: {
1033 /// Set whether to measure the elapsed time for each one of the `bindgen` phases. This
1034 /// information is printed to `stderr`.
1035 ///
1036 /// The elapsed time is not measured by default.
1037 pub fn time_phases(mut self, doit: bool) -> Self {
1038 self.options.time_phases = doit;
1039 self
1040 }
1041 },
1042 as_args: "--time-phases",
1043 },
1044 /// Whether to convert C float types to `f32` and `f64`.
1045 convert_floats: bool {
1046 default: true,
1047 methods: {
1048 /// Avoid converting C float types to `f32` and `f64`.
1049 pub fn no_convert_floats(mut self) -> Self {
1050 self.options.convert_floats = false;
1051 self
1052 }
1053 },
1054 as_args: |value, args| (!value).as_args(args, "--no-convert-floats"),
1055 },
1056 /// The set of raw lines to be prepended to the top-level module of the generated Rust code.
1057 raw_lines: Vec<String> {
1058 methods: {
1059 /// Add a line of Rust code at the beginning of the generated bindings. The string is
1060 /// passed through without any modification.
1061 pub fn raw_line<T: Into<String>>(mut self, arg: T) -> Self {
1062 self.options.raw_lines.push(arg.into());
1063 self
1064 }
1065 },
1066 as_args: |raw_lines, args| {
1067 for line in raw_lines {
1068 args.push("--raw-line".to_owned());
1069 args.push(line.clone());
1070 }
1071 },
1072 },
1073 /// The set of raw lines to prepend to different modules.
1074 module_lines: HashMap<String, Vec<String>> {
1075 methods: {
1076 /// Add a given line to the beginning of a given module.
1077 ///
1078 /// This option only comes into effect if the [`Builder::enable_cxx_namespaces`] method
1079 /// is also being called.
1080 pub fn module_raw_line<T, U>(mut self, module: T, line: U) -> Self
1081 where
1082 T: Into<String>,
1083 U: Into<String>,
1084 {
1085 self.options
1086 .module_lines
1087 .entry(module.into())
1088 .or_insert_with(Vec::new)
1089 .push(line.into());
1090 self
1091 }
1092 },
1093 as_args: |module_lines, args| {
1094 for (module, lines) in module_lines {
1095 for line in lines.iter() {
1096 args.push("--module-raw-line".to_owned());
1097 args.push(module.clone());
1098 args.push(line.clone());
1099 }
1100 }
1101 },
1102 },
1103 /// The input header files.
1104 input_headers: Vec<String> {
1105 methods: {
1106 /// Add an input C/C++ header to generate bindings for.
1107 ///
1108 /// This can be used to generate bindings for a single header:
1109 ///
1110 /// ```ignore
1111 /// let bindings = bindgen::Builder::default()
1112 /// .header("input.h")
1113 /// .generate()
1114 /// .unwrap();
1115 /// ```
1116 ///
1117 /// Or for multiple headers:
1118 ///
1119 /// ```ignore
1120 /// let bindings = bindgen::Builder::default()
1121 /// .header("first.h")
1122 /// .header("second.h")
1123 /// .header("third.h")
1124 /// .generate()
1125 /// .unwrap();
1126 /// ```
1127 pub fn header<T: Into<String>>(mut self, header: T) -> Builder {
1128 self.options.input_headers.push(header.into());
1129 self
1130 }
1131 },
1132 // This field is handled specially inside the macro.
1133 as_args: ignore,
1134 },
1135 /// The set of arguments to be passed straight through to Clang.
1136 clang_args: Vec<String> {
1137 methods: {
1138 /// Add an argument to be passed straight through to Clang.
1139 pub fn clang_arg<T: Into<String>>(self, arg: T) -> Builder {
1140 self.clang_args([arg.into()])
1141 }
1142
1143 /// Add several arguments to be passed straight through to Clang.
1144 pub fn clang_args<I: IntoIterator>(mut self, args: I) -> Builder
1145 where
1146 I::Item: AsRef<str>,
1147 {
1148 for arg in args {
1149 self.options.clang_args.push(arg.as_ref().to_owned());
1150 }
1151 self
1152 }
1153 },
1154 // This field is handled specially inside the macro.
1155 as_args: ignore,
1156 },
1157 /// Tuples of unsaved file contents of the form (name, contents).
1158 input_header_contents: Vec<(String, String)> {
1159 methods: {
1160 /// Add `contents` as an input C/C++ header named `name`.
1161 ///
1162 /// This can be used to inject additional C/C++ code as an input without having to
1163 /// create additional header files.
1164 pub fn header_contents(mut self, name: &str, contents: &str) -> Builder {
1165 // Apparently clang relies on having virtual FS correspondent to
1166 // the real one, so we need absolute paths here
1167 let absolute_path = env::current_dir()
1168 .expect("Cannot retrieve current directory")
1169 .join(name)
1170 .to_str()
1171 .expect("Cannot convert current directory name to string")
1172 .to_owned();
1173 self.options
1174 .input_header_contents
1175 .push((absolute_path, contents.into()));
1176 self
1177 }
1178 },
1179 // Header contents cannot be added from the CLI.
1180 as_args: ignore,
1181 },
1182 /// A user-provided visitor to allow customizing different kinds of situations.
1183 parse_callbacks: Vec<Rc<dyn ParseCallbacks>> {
1184 methods: {
1185 /// Add a new [`ParseCallbacks`] instance to configure types in different situations.
1186 pub fn parse_callbacks(mut self, cb: Box<dyn ParseCallbacks>) -> Self {
1187 self.options.parse_callbacks.push(Rc::from(cb));
1188 self
1189 }
1190 },
1191 as_args: |_callbacks, _args| {
1192 #[cfg(feature = "__cli")]
1193 for cb in _callbacks {
1194 _args.extend(cb.cli_args());
1195 }
1196 },
1197 },
1198 /// Which kind of items should we generate. We generate all of them by default.
1199 codegen_config: CodegenConfig {
1200 default: CodegenConfig::all(),
1201 methods: {
1202 /// Do not generate any functions.
1203 ///
1204 /// Functions are generated by default.
1205 pub fn ignore_functions(mut self) -> Builder {
1206 self.options.codegen_config.remove(CodegenConfig::FUNCTIONS);
1207 self
1208 }
1209
1210 /// Do not generate any methods.
1211 ///
1212 /// Methods are generated by default.
1213 pub fn ignore_methods(mut self) -> Builder {
1214 self.options.codegen_config.remove(CodegenConfig::METHODS);
1215 self
1216 }
1217
1218 /// Choose what to generate using a [`CodegenConfig`].
1219 ///
1220 /// This option overlaps with [`Builder::ignore_functions`] and
1221 /// [`Builder::ignore_methods`].
1222 ///
1223 /// All the items in `CodegenConfig` are generated by default.
1224 pub fn with_codegen_config(mut self, config: CodegenConfig) -> Self {
1225 self.options.codegen_config = config;
1226 self
1227 }
1228 },
1229 as_args: |codegen_config, args| {
1230 if !codegen_config.functions() {
1231 args.push("--ignore-functions".to_owned());
1232 }
1233
1234 args.push("--generate".to_owned());
1235
1236 //Temporary placeholder for the 4 options below.
1237 let mut options: Vec<String> = Vec::new();
1238 if codegen_config.functions() {
1239 options.push("functions".to_owned());
1240 }
1241
1242 if codegen_config.types() {
1243 options.push("types".to_owned());
1244 }
1245
1246 if codegen_config.vars() {
1247 options.push("vars".to_owned());
1248 }
1249
1250 if codegen_config.methods() {
1251 options.push("methods".to_owned());
1252 }
1253
1254 if codegen_config.constructors() {
1255 options.push("constructors".to_owned());
1256 }
1257
1258 if codegen_config.destructors() {
1259 options.push("destructors".to_owned());
1260 }
1261
1262 args.push(options.join(","));
1263
1264 if !codegen_config.methods() {
1265 args.push("--ignore-methods".to_owned());
1266 }
1267 },
1268 },
1269 /// Whether to treat inline namespaces conservatively.
1270 conservative_inline_namespaces: bool {
1271 methods: {
1272 /// Treat inline namespaces conservatively.
1273 ///
1274 /// This is tricky, because in C++ is technically legal to override an item
1275 /// defined in an inline namespace:
1276 ///
1277 /// ```cpp
1278 /// inline namespace foo {
1279 /// using Bar = int;
1280 /// }
1281 /// using Bar = long;
1282 /// ```
1283 ///
1284 /// Even though referencing `Bar` is a compiler error.
1285 ///
1286 /// We want to support this (arguably esoteric) use case, but we do not want to make
1287 /// the rest of `bindgen` users pay an usability penalty for that.
1288 ///
1289 /// To support this, we need to keep all the inline namespaces around, but then using
1290 /// `bindgen` becomes a bit more difficult, because you cannot reference paths like
1291 /// `std::string` (you'd need to use the proper inline namespace).
1292 ///
1293 /// We could complicate a lot of the logic to detect name collisions and, in the
1294 /// absence of collisions, generate a `pub use inline_ns::*` or something like that.
1295 ///
1296 /// That is probably something we can do to improve the usability of this option if we
1297 /// realize it is needed way more often. Our guess is that this extra logic is not
1298 /// going to be very useful.
1299 ///
1300 /// This option is disabled by default.
1301 pub fn conservative_inline_namespaces(mut self) -> Builder {
1302 self.options.conservative_inline_namespaces = true;
1303 self
1304 }
1305 },
1306 as_args: "--conservative-inline-namespaces",
1307 },
1308 /// Whether to keep documentation comments in the generated output.
1309 generate_comments: bool {
1310 default: true,
1311 methods: {
1312 /// Set whether the generated bindings should contain documentation comments.
1313 ///
1314 /// Documentation comments are included by default.
1315 ///
1316 /// Note that clang excludes comments from system headers by default, pass
1317 /// `"-fretain-comments-from-system-headers"` to the [`Builder::clang_arg`] method to
1318 /// include them.
1319 ///
1320 /// It is also possible to process all comments and not just documentation using the
1321 /// `"-fparse-all-comments"` flag. Check [these slides on clang comment parsing](
1322 /// https://llvm.org/devmtg/2012-11/Gribenko_CommentParsing.pdf) for more information
1323 /// and examples.
1324 pub fn generate_comments(mut self, doit: bool) -> Self {
1325 self.options.generate_comments = doit;
1326 self
1327 }
1328 },
1329 as_args: |value, args| (!value).as_args(args, "--no-doc-comments"),
1330 },
1331 /// Whether to generate inline functions.
1332 generate_inline_functions: bool {
1333 methods: {
1334 /// Set whether to generate inline functions.
1335 ///
1336 /// This option is disabled by default.
1337 ///
1338 /// Note that they will usually not work. However you can use `-fkeep-inline-functions`
1339 /// or `-fno-inline-functions` if you are responsible of compiling the library to make
1340 /// them callable.
1341 #[cfg_attr(
1342 features = "experimental",
1343 doc = "\nCheck the [`Builder::wrap_static_fns`] method for an alternative."
1344 )]
1345 pub fn generate_inline_functions(mut self, doit: bool) -> Self {
1346 self.options.generate_inline_functions = doit;
1347 self
1348 }
1349 },
1350 as_args: "--generate-inline-functions",
1351 },
1352 /// Whether to allowlist types recursively.
1353 allowlist_recursively: bool {
1354 default: true,
1355 methods: {
1356 /// Set whether to recursively allowlist items.
1357 ///
1358 /// Items are allowlisted recursively by default.
1359 ///
1360 /// Given that we have explicitly allowlisted the `initiate_dance_party` function in
1361 /// this C header:
1362 ///
1363 /// ```c
1364 /// typedef struct MoonBoots {
1365 /// int bouncy_level;
1366 /// } MoonBoots;
1367 ///
1368 /// void initiate_dance_party(MoonBoots* boots);
1369 /// ```
1370 ///
1371 /// We would normally generate bindings to both the `initiate_dance_party` function and
1372 /// the `MoonBoots` type that it transitively references. If `false` is passed to this
1373 /// method, `bindgen` will not emit bindings for anything except the explicitly
1374 /// allowlisted items, meaning that the definition for `MoonBoots` would not be
1375 /// generated. However, the `initiate_dance_party` function would still reference
1376 /// `MoonBoots`!
1377 ///
1378 /// **Disabling this feature will almost certainly cause `bindgen` to emit bindings
1379 /// that will not compile!** If you disable this feature, then it is *your*
1380 /// responsibility to provide definitions for every type that is referenced from an
1381 /// explicitly allowlisted item. One way to provide the missing definitions is by using
1382 /// the [`Builder::raw_line`] method, another would be to define them in Rust and then
1383 /// `include!(...)` the bindings immediately afterwards.
1384 pub fn allowlist_recursively(mut self, doit: bool) -> Self {
1385 self.options.allowlist_recursively = doit;
1386 self
1387 }
1388 },
1389 as_args: |value, args| (!value).as_args(args, "--no-recursive-allowlist"),
1390 },
1391 /// Whether to emit `#[macro_use] extern crate objc;` instead of `use objc;` in the prologue of
1392 /// the files generated from objective-c files.
1393 objc_extern_crate: bool {
1394 methods: {
1395 /// Emit `#[macro_use] extern crate objc;` instead of `use objc;` in the prologue of
1396 /// the files generated from objective-c files.
1397 ///
1398 /// `use objc;` is emitted by default.
1399 pub fn objc_extern_crate(mut self, doit: bool) -> Self {
1400 self.options.objc_extern_crate = doit;
1401 self
1402 }
1403 },
1404 as_args: "--objc-extern-crate",
1405 },
1406 /// Whether to generate proper block signatures instead of `void` pointers.
1407 generate_block: bool {
1408 methods: {
1409 /// Generate proper block signatures instead of `void` pointers.
1410 ///
1411 /// `void` pointers are used by default.
1412 pub fn generate_block(mut self, doit: bool) -> Self {
1413 self.options.generate_block = doit;
1414 self
1415 }
1416 },
1417 as_args: "--generate-block",
1418 },
1419 /// Whether to emit `#[macro_use] extern crate block;` instead of `use block;` in the prologue
1420 /// of the files generated from apple block files.
1421 block_extern_crate: bool {
1422 methods: {
1423 /// Emit `#[macro_use] extern crate block;` instead of `use block;` in the prologue of
1424 /// the files generated from apple block files.
1425 ///
1426 /// `use block;` is emitted by default.
1427 pub fn block_extern_crate(mut self, doit: bool) -> Self {
1428 self.options.block_extern_crate = doit;
1429 self
1430 }
1431 },
1432 as_args: "--block-extern-crate",
1433 },
1434 /// Whether to use the clang-provided name mangling.
1435 enable_mangling: bool {
1436 default: true,
1437 methods: {
1438 /// Set whether to use the clang-provided name mangling. This is probably needed for
1439 /// C++ features.
1440 ///
1441 /// The mangling provided by clang is used by default.
1442 ///
1443 /// We allow disabling this option because some old `libclang` versions seem to return
1444 /// incorrect results in some cases for non-mangled functions, check [#528] for more
1445 /// information.
1446 ///
1447 /// [#528]: https://github.com/rust-lang/rust-bindgen/issues/528
1448 pub fn trust_clang_mangling(mut self, doit: bool) -> Self {
1449 self.options.enable_mangling = doit;
1450 self
1451 }
1452
1453 },
1454 as_args: |value, args| (!value).as_args(args, "--distrust-clang-mangling"),
1455 },
1456 /// Whether to detect include paths using `clang_sys`.
1457 detect_include_paths: bool {
1458 default: true,
1459 methods: {
1460 /// Set whether to detect include paths using `clang_sys`.
1461 ///
1462 /// `clang_sys` is used to detect include paths by default.
1463 pub fn detect_include_paths(mut self, doit: bool) -> Self {
1464 self.options.detect_include_paths = doit;
1465 self
1466 }
1467 },
1468 as_args: |value, args| (!value).as_args(args, "--no-include-path-detection"),
1469 },
1470 /// Whether we should try to fit macro constants into types smaller than `u32` and `i32`.
1471 fit_macro_constants: bool {
1472 methods: {
1473 /// Set whether `bindgen` should try to fit macro constants into types smaller than `u32`
1474 /// and `i32`.
1475 ///
1476 /// This option is disabled by default.
1477 pub fn fit_macro_constants(mut self, doit: bool) -> Self {
1478 self.options.fit_macro_constants = doit;
1479 self
1480 }
1481 },
1482 as_args: "--fit-macro-constant-types",
1483 },
1484 /// Whether to prepend the `enum` name to constant or newtype variants.
1485 prepend_enum_name: bool {
1486 default: true,
1487 methods: {
1488 /// Set whether to prepend the `enum` name to constant or newtype variants.
1489 ///
1490 /// The `enum` name is prepended by default.
1491 pub fn prepend_enum_name(mut self, doit: bool) -> Self {
1492 self.options.prepend_enum_name = doit;
1493 self
1494 }
1495 },
1496 as_args: |value, args| (!value).as_args(args, "--no-prepend-enum-name"),
1497 },
1498 /// Version of the Rust compiler to target.
1499 rust_target: RustTarget {
1500 methods: {
1501 /// Specify the Rust target version.
1502 ///
1503 /// The default target is the latest stable Rust version.
1504 pub fn rust_target(mut self, rust_target: RustTarget) -> Self {
1505 self.options.set_rust_target(rust_target);
1506 self
1507 }
1508 },
1509 as_args: |rust_target, args| {
1510 args.push("--rust-target".to_owned());
1511 args.push((*rust_target).into());
1512 },
1513 },
1514 /// Features to be enabled. They are derived from `rust_target`.
1515 rust_features: RustFeatures {
1516 default: RustTarget::default().into(),
1517 methods: {},
1518 // This field cannot be set from the CLI,
1519 as_args: ignore,
1520 },
1521 /// Enable support for native Rust unions if they are supported.
1522 untagged_union: bool {
1523 default: true,
1524 methods: {
1525 /// Disable support for native Rust unions, if supported.
1526 ///
1527 /// The default value of this option is set based on the value passed to
1528 /// [`Builder::rust_target`].
1529 pub fn disable_untagged_union(mut self) -> Self {
1530 self.options.untagged_union = false;
1531 self
1532 }
1533 }
1534 as_args: |value, args| (!value).as_args(args, "--disable-untagged-union"),
1535 },
1536 /// Whether we should record which items in the regex sets did match any C items.
1537 record_matches: bool {
1538 default: true,
1539 methods: {
1540 /// Set whether we should record which items in our regex sets did match any C items.
1541 ///
1542 /// Matches are recorded by default.
1543 pub fn record_matches(mut self, doit: bool) -> Self {
1544 self.options.record_matches = doit;
1545 self
1546 }
1547
1548 },
1549 as_args: |value, args| (!value).as_args(args, "--no-record-matches"),
1550 },
1551 /// Whether `size_t` should be translated to `usize` automatically.
1552 size_t_is_usize: bool {
1553 default: true,
1554 methods: {
1555 /// Set whether `size_t` should be translated to `usize`.
1556 ///
1557 /// `size_t` is translated to `usize` by default.
1558 pub fn size_t_is_usize(mut self, is: bool) -> Self {
1559 self.options.size_t_is_usize = is;
1560 self
1561 }
1562 },
1563 as_args: |value, args| (!value).as_args(args, "--no-size_t-is-usize"),
1564 },
1565 /// The tool that should be used to format the generated bindings.
1566 formatter: Formatter {
1567 methods: {
1568 /// Set whether `rustfmt` should be used to format the generated bindings.
1569 ///
1570 /// `rustfmt` is used by default.
1571 ///
1572 /// This method overlaps in functionality with the more general [`Builder::formatter`].
1573 /// Thus, the latter should be preferred.
1574 #[deprecated]
1575 pub fn rustfmt_bindings(mut self, doit: bool) -> Self {
1576 self.options.formatter = if doit {
1577 Formatter::Rustfmt
1578 } else {
1579 Formatter::None
1580 };
1581 self
1582 }
1583
1584 /// Set which tool should be used to format the generated bindings.
1585 ///
1586 /// The default formatter is [`Formatter::Rustfmt`].
1587 ///
1588 /// To be able to use `prettyplease` as a formatter, the `"prettyplease"` feature for
1589 /// `bindgen` must be enabled in the Cargo manifest.
1590 pub fn formatter(mut self, formatter: Formatter) -> Self {
1591 self.options.formatter = formatter;
1592 self
1593 }
1594 },
1595 as_args: |formatter, args| {
1596 if *formatter != Default::default() {
1597 args.push("--formatter".to_owned());
1598 args.push(formatter.to_string());
1599 }
1600 },
1601 },
1602 /// The absolute path to the `rustfmt` configuration file.
1603 rustfmt_configuration_file: Option<PathBuf> {
1604 methods: {
1605 /// Set the absolute path to the `rustfmt` configuration file.
1606 ///
1607 /// The default `rustfmt` options are used if `None` is passed to this method or if
1608 /// this method is not called at all.
1609 ///
1610 /// Calling this method will set the [`Builder::rustfmt_bindings`] option to `true`
1611 /// and the [`Builder::formatter`] option to [`Formatter::Rustfmt`].
1612 pub fn rustfmt_configuration_file(mut self, path: Option<PathBuf>) -> Self {
1613 self = self.formatter(Formatter::Rustfmt);
1614 self.options.rustfmt_configuration_file = path;
1615 self
1616 }
1617 },
1618 as_args: "--rustfmt-configuration-file",
1619 },
1620 /// Types that should not derive `PartialEq`.
1621 no_partialeq_types: RegexSet {
1622 methods: {
1623 regex_option! {
1624 /// Do not derive `PartialEq` for a given type.
1625 pub fn no_partialeq<T: Into<String>>(mut self, arg: T) -> Builder {
1626 self.options.no_partialeq_types.insert(arg.into());
1627 self
1628 }
1629 }
1630 },
1631 as_args: "--no-partialeq",
1632 },
1633 /// Types that should not derive `Copy`.
1634 no_copy_types: RegexSet {
1635 methods: {
1636 regex_option! {
1637 /// Do not derive `Copy` and `Clone` for a given type.
1638 pub fn no_copy<T: Into<String>>(mut self, arg: T) -> Self {
1639 self.options.no_copy_types.insert(arg.into());
1640 self
1641 }
1642 }
1643 },
1644 as_args: "--no-copy",
1645 },
1646 /// Types that should not derive `Debug`.
1647 no_debug_types: RegexSet {
1648 methods: {
1649 regex_option! {
1650 /// Do not derive `Debug` for a given type.
1651 pub fn no_debug<T: Into<String>>(mut self, arg: T) -> Self {
1652 self.options.no_debug_types.insert(arg.into());
1653 self
1654 }
1655 }
1656 },
1657 as_args: "--no-debug",
1658 },
1659 /// Types that should not derive or implement `Default`.
1660 no_default_types: RegexSet {
1661 methods: {
1662 regex_option! {
1663 /// Do not derive or implement `Default` for a given type.
1664 pub fn no_default<T: Into<String>>(mut self, arg: T) -> Self {
1665 self.options.no_default_types.insert(arg.into());
1666 self
1667 }
1668 }
1669 },
1670 as_args: "--no-default",
1671 },
1672 /// Types that should not derive `Hash`.
1673 no_hash_types: RegexSet {
1674 methods: {
1675 regex_option! {
1676 /// Do not derive `Hash` for a given type.
1677 pub fn no_hash<T: Into<String>>(mut self, arg: T) -> Builder {
1678 self.options.no_hash_types.insert(arg.into());
1679 self
1680 }
1681 }
1682 },
1683 as_args: "--no-hash",
1684 },
1685 /// Types that should be annotated with `#[must_use]`.
1686 must_use_types: RegexSet {
1687 methods: {
1688 regex_option! {
1689 /// Annotate the given type with the `#[must_use]` attribute.
1690 pub fn must_use_type<T: Into<String>>(mut self, arg: T) -> Builder {
1691 self.options.must_use_types.insert(arg.into());
1692 self
1693 }
1694 }
1695 },
1696 as_args: "--must-use-type",
1697 },
1698 /// Whether C arrays should be regular pointers in rust or array pointers
1699 array_pointers_in_arguments: bool {
1700 methods: {
1701 /// Translate arrays `T arr[size]` into array pointers `*mut [T; size]` instead of
1702 /// translating them as `*mut T` which is the default.
1703 ///
1704 /// The same is done for `*const` pointers.
1705 pub fn array_pointers_in_arguments(mut self, doit: bool) -> Self {
1706 self.options.array_pointers_in_arguments = doit;
1707 self
1708 }
1709
1710 },
1711 as_args: "--use-array-pointers-in-arguments",
1712 },
1713 /// The name of the `wasm_import_module`.
1714 wasm_import_module_name: Option<String> {
1715 methods: {
1716 /// Adds the `#[link(wasm_import_module = import_name)]` attribute to all the `extern`
1717 /// blocks generated by `bindgen`.
1718 ///
1719 /// This attribute is not added by default.
1720 pub fn wasm_import_module_name<T: Into<String>>(
1721 mut self,
1722 import_name: T,
1723 ) -> Self {
1724 self.options.wasm_import_module_name = Some(import_name.into());
1725 self
1726 }
1727 },
1728 as_args: "--wasm-import-module-name",
1729 },
1730 /// The name of the dynamic library (if we are generating bindings for a shared library).
1731 dynamic_library_name: Option<String> {
1732 methods: {
1733 /// Generate bindings for a shared library with the given name.
1734 ///
1735 /// This option is disabled by default.
1736 pub fn dynamic_library_name<T: Into<String>>(
1737 mut self,
1738 dynamic_library_name: T,
1739 ) -> Self {
1740 self.options.dynamic_library_name = Some(dynamic_library_name.into());
1741 self
1742 }
1743 },
1744 as_args: "--dynamic-loading",
1745 },
1746 /// Whether to equire successful linkage for all routines in a shared library.
1747 dynamic_link_require_all: bool {
1748 methods: {
1749 /// Set whether to require successful linkage for all routines in a shared library.
1750 /// This allows us to optimize function calls by being able to safely assume function
1751 /// pointers are valid.
1752 ///
1753 /// This option only comes into effect if the [`Builder::dynamic_library_name`] option
1754 /// is set.
1755 ///
1756 /// This option is disabled by default.
1757 pub fn dynamic_link_require_all(mut self, req: bool) -> Self {
1758 self.options.dynamic_link_require_all = req;
1759 self
1760 }
1761 },
1762 as_args: "--dynamic-link-require-all",
1763 },
1764 /// Whether to only make generated bindings `pub` if the items would be publicly accessible by
1765 /// C++.
1766 respect_cxx_access_specs: bool {
1767 methods: {
1768 /// Set whether to respect the C++ access specifications.
1769 ///
1770 /// Passing `true` to this method will set the visibility of the generated Rust items
1771 /// as `pub` only if the corresponding C++ items are publicly accessible instead of
1772 /// marking all the items as public, which is the default.
1773 pub fn respect_cxx_access_specs(mut self, doit: bool) -> Self {
1774 self.options.respect_cxx_access_specs = doit;
1775 self
1776 }
1777
1778 },
1779 as_args: "--respect-cxx-access-specs",
1780 },
1781 /// Whether to translate `enum` integer types to native Rust integer types.
1782 translate_enum_integer_types: bool {
1783 methods: {
1784 /// Set whether to always translate `enum` integer types to native Rust integer types.
1785 ///
1786 /// Passing `true` to this method will result in `enum`s having types such as `u32` and
1787 /// `i16` instead of `c_uint` and `c_short` which is the default. The `#[repr]` types
1788 /// of Rust `enum`s are always translated to Rust integer types.
1789 pub fn translate_enum_integer_types(mut self, doit: bool) -> Self {
1790 self.options.translate_enum_integer_types = doit;
1791 self
1792 }
1793 },
1794 as_args: "--translate-enum-integer-types",
1795 },
1796 /// Whether to generate types with C style naming.
1797 c_naming: bool {
1798 methods: {
1799 /// Set whether to generate types with C style naming.
1800 ///
1801 /// Passing `true` to this method will add prefixes to the generated type names. For
1802 /// example, instead of a `struct` with name `A` we will generate a `struct` with
1803 /// `struct_A`. Currently applies to `struct`s, `union`s, and `enum`s.
1804 pub fn c_naming(mut self, doit: bool) -> Self {
1805 self.options.c_naming = doit;
1806 self
1807 }
1808 },
1809 as_args: "--c-naming",
1810 },
1811 /// Wether to always emit explicit padding fields.
1812 force_explicit_padding: bool {
1813 methods: {
1814 /// Set whether to always emit explicit padding fields.
1815 ///
1816 /// This option should be enabled if a `struct` needs to be serialized in its native
1817 /// format (padding bytes and all). This could be required if such `struct` will be
1818 /// written to a file or sent over the network, as anything reading the padding bytes
1819 /// of a struct may cause undefined behavior.
1820 ///
1821 /// Padding fields are not emitted by default.
1822 pub fn explicit_padding(mut self, doit: bool) -> Self {
1823 self.options.force_explicit_padding = doit;
1824 self
1825 }
1826 },
1827 as_args: "--explicit-padding",
1828 },
1829 /// Whether to emit vtable functions.
1830 vtable_generation: bool {
1831 methods: {
1832 /// Set whether to enable experimental support to generate virtual table functions.
1833 ///
1834 /// This option should mostly work, though some edge cases are likely to be broken.
1835 ///
1836 /// Virtual table generation is disabled by default.
1837 pub fn vtable_generation(mut self, doit: bool) -> Self {
1838 self.options.vtable_generation = doit;
1839 self
1840 }
1841 },
1842 as_args: "--vtable-generation",
1843 },
1844 /// Whether to sort the generated Rust items.
1845 sort_semantically: bool {
1846 methods: {
1847 /// Set whether to sort the generated Rust items in a predefined manner.
1848 ///
1849 /// Items are not ordered by default.
1850 pub fn sort_semantically(mut self, doit: bool) -> Self {
1851 self.options.sort_semantically = doit;
1852 self
1853 }
1854 },
1855 as_args: "--sort-semantically",
1856 },
1857 /// Whether to deduplicate `extern` blocks.
1858 merge_extern_blocks: bool {
1859 methods: {
1860 /// Merge all extern blocks under the same module into a single one.
1861 ///
1862 /// Extern blocks are not merged by default.
1863 pub fn merge_extern_blocks(mut self, doit: bool) -> Self {
1864 self.options.merge_extern_blocks = doit;
1865 self
1866 }
1867 },
1868 as_args: "--merge-extern-blocks",
1869 },
1870 /// Whether to wrap unsafe operations in unsafe blocks.
1871 wrap_unsafe_ops: bool {
1872 methods: {
1873 /// Wrap all unsafe operations in unsafe blocks.
1874 ///
1875 /// Unsafe operations are not wrapped by default.
1876 pub fn wrap_unsafe_ops(mut self, doit: bool) -> Self {
1877 self.options.wrap_unsafe_ops = doit;
1878 self
1879 }
1880 },
1881 as_args: "--wrap-unsafe-ops",
1882 },
1883 /// Patterns for functions whose ABI should be overriden.
1884 abi_overrides: HashMap<Abi, RegexSet> {
1885 methods: {
1886 regex_option! {
1887 /// Override the ABI of a given function.
1888 pub fn override_abi<T: Into<String>>(mut self, abi: Abi, arg: T) -> Self {
1889 self.options
1890 .abi_overrides
1891 .entry(abi)
1892 .or_default()
1893 .insert(arg.into());
1894 self
1895 }
1896 }
1897 },
1898 as_args: |overrides, args| {
1899 for (abi, set) in overrides {
1900 for item in set.get_items() {
1901 args.push("--override-abi".to_owned());
1902 args.push(format!("{}={}", item, abi));
1903 }
1904 }
1905 },
1906 },
1907 /// Whether to generate wrappers for `static` functions.
1908 wrap_static_fns: bool {
1909 methods: {
1910 #[cfg(feature = "experimental")]
1911 /// Set whether to generate wrappers for `static`` functions.
1912 ///
1913 /// Passing `true` to this method will generate a C source file with non-`static`
1914 /// functions that call the `static` functions found in the input headers and can be
1915 /// called from Rust once the source file is compiled.
1916 ///
1917 /// The path of this source file can be set using the [`Builder::wrap_static_fns_path`]
1918 /// method.
1919 pub fn wrap_static_fns(mut self, doit: bool) -> Self {
1920 self.options.wrap_static_fns = doit;
1921 self
1922 }
1923 },
1924 as_args: "--wrap-static-fns",
1925 },
1926 /// The suffix to be added to the function wrappers for `static` functions.
1927 wrap_static_fns_suffix: Option<String> {
1928 methods: {
1929 #[cfg(feature = "experimental")]
1930 /// Set the suffix added to the wrappers for `static` functions.
1931 ///
1932 /// This option only comes into effect if `true` is passed to the
1933 /// [`Builder::wrap_static_fns`] method.
1934 ///
1935 /// The default suffix is `__extern`.
1936 pub fn wrap_static_fns_suffix<T: AsRef<str>>(mut self, suffix: T) -> Self {
1937 self.options.wrap_static_fns_suffix = Some(suffix.as_ref().to_owned());
1938 self
1939 }
1940 },
1941 as_args: "--wrap-static-fns-suffix",
1942 },
1943 /// The path of the file where the wrappers for `static` functions will be emitted.
1944 wrap_static_fns_path: Option<PathBuf> {
1945 methods: {
1946 #[cfg(feature = "experimental")]
1947 /// Set the path for the source code file that would be created if any wrapper
1948 /// functions must be generated due to the presence of `static` functions.
1949 ///
1950 /// `bindgen` will automatically add the right extension to the header and source code
1951 /// files.
1952 ///
1953 /// This option only comes into effect if `true` is passed to the
1954 /// [`Builder::wrap_static_fns`] method.
1955 ///
1956 /// The default path is `temp_dir/bindgen/extern`, where `temp_dir` is the path
1957 /// returned by [`std::env::temp_dir`] .
1958 pub fn wrap_static_fns_path<T: AsRef<Path>>(mut self, path: T) -> Self {
1959 self.options.wrap_static_fns_path = Some(path.as_ref().to_owned());
1960 self
1961 }
1962 },
1963 as_args: "--wrap-static-fns-path",
1964 },
1965 /// Default visibility of fields.
1966 default_visibility: FieldVisibilityKind {
1967 methods: {
1968 /// Set the default visibility of fields, including bitfields and accessor methods for
1969 /// bitfields.
1970 ///
1971 /// This option only comes into effect if the [`Builder::respect_cxx_access_specs`]
1972 /// option is disabled.
1973 pub fn default_visibility(
1974 mut self,
1975 visibility: FieldVisibilityKind,
1976 ) -> Self {
1977 self.options.default_visibility = visibility;
1978 self
1979 }
1980 },
1981 as_args: |visibility, args| {
1982 if *visibility != Default::default() {
1983 args.push("--default-visibility".to_owned());
1984 args.push(visibility.to_string());
1985 }
1986 },
1987 },
1988 /// Whether to emit diagnostics or not.
1989 emit_diagnostics: bool {
1990 methods: {
1991 #[cfg(feature = "experimental")]
1992 /// Emit diagnostics.
1993 ///
1994 /// These diagnostics are emitted to `stderr` if you are using `bindgen-cli` or printed
1995 /// using `cargo:warning=` if you are using `bindgen` as a `build-dependency`.
1996 ///
1997 /// Diagnostics are not emitted by default.
1998 ///
1999 /// The layout and contents of these diagnostic messages are not covered by versioning
2000 /// and can change without notice.
2001 pub fn emit_diagnostics(mut self) -> Self {
2002 self.options.emit_diagnostics = true;
2003 self
2004 }
2005 },
2006 as_args: "--emit-diagnostics",
2007 }
2008 }