1 # The language to output bindings in
3 # possible values: "C", "C++"
11 # Options for wrapping the contents of the header:
13 # An optional string of text to output at the beginning of the generated file
14 # default: doesn't emit anything
15 header = "/* Text to put at the beginning of the generated file. Probably a license. */"
17 # An optional string of text to output at the end of the generated file
18 # default: doesn't emit anything
19 trailer = "/* Text to put at the end of the generated file */"
21 # An optional name to use as an include guard
22 # default: doesn't emit an include guard
23 # include_guard = "mozilla_wr_bindings_h"
25 # An optional string of text to output between major sections of the generated
26 # file as a warning against manual editing
28 # default: doesn't emit anything
29 autogen_warning = "/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */"
31 # Whether to include a comment with the version of cbindgen used to generate the file
33 include_version = true
35 # An optional namespace to output around the generated bindings
36 # default: doesn't emit a namespace
39 # An optional list of namespaces to output around the generated bindings
43 # An optional list of namespaces to declare as using with "using namespace"
47 # A list of sys headers to #include (with angle brackets)
49 # sys_includes = ["stdio", "string"]
50 # sys_includes = ["stdint"]
52 # A list of headers to #include (with quotes)
54 # includes = ["my_great_lib.h"]
56 # Whether cbindgen's default C/C++ standard imports should be suppressed. These
57 # imports are included by default because our generated headers tend to require
58 # them (e.g. for uint32_t). Currently, the generated imports are:
60 # * for C: <stdarg.h>, <stdbool.h>, <stdint.h>, <stdlib.h>, <uchar.h>
62 # * for C++: <cstdarg>, <cstdint>, <cstdlib>, <new>, <cassert> (depending on config)
73 # The style to use for curly braces
75 # possible values: "SameLine", "NextLine"
80 # The desired length of a line to use when formatting lines
84 # The amount of spaces to indent by
88 # How the generated documentation should be commented.
91 # * "c": /* like this */
92 # * "c99": // like this
93 # * "c++": /// like this
94 # * "doxy": like C, but with leading *'s on each line
95 # * "auto": "c++" if that's the language, "doxy" otherwise
98 documentation_style = "doxy"
106 # When generating a C header, the kind of declaration style to use for structs
110 # * "type": typedef struct { ... } MyType;
111 # * "tag": struct MyType { ... };
112 # * "both": typedef struct MyType { ... } MyType;
117 # A list of substitutions for converting cfg's to ifdefs. cfgs which aren't
118 # defined here will just be discarded.
121 # `#[cfg(target = "freebsd")] ...`
123 # `#if defined(DEFINE_FREEBSD) ... #endif`
125 "target_os = freebsd" = "DEFINE_FREEBSD"
126 "feature = serde" = "DEFINE_SERDE"
133 # A list of additional items to always include in the generated bindings if they're
134 # found but otherwise don't appear to be used by the public API.
137 # include = ["MyOrphanStruct", "MyGreatTypeRename"]
139 # A list of items to not include in the generated bindings
143 # A prefix to add before the name of every item
144 # default: no prefix is added
147 # Types of items that we'll generate. If empty, then all types of item are emitted.
149 # possible items: (TODO: explain these in detail)
160 item_types = ["constants", "globals", "enums", "structs", "unions", "typedefs", "opaque", "functions"]
162 # Whether applying rules in export.rename prevents export.prefix from applying.
164 # e.g. given this toml:
169 # "MyType" = "my_cool_type"
171 # You get the following results:
173 # renaming_overrides_prefixing = true:
174 # "MyType" => "my_cool_type"
176 # renaming_overrides_prefixing = false:
177 # "MyType => capi_my_cool_type"
180 renaming_overrides_prefixing = true
182 # Table of name conversions to apply to item names (lhs becomes rhs)
184 # "MyType" = "my_cool_type"
185 # "my_function" = "BetterFunctionName"
187 # Table of things to prepend to the body of any struct, union, or enum that has the
188 # given name. This can be used to add things like methods which don't change ABI,
189 # mark fields private, etc
196 # Table of things to append to the body of any struct, union, or enum that has the
197 # given name. This can be used to add things like methods which don't change ABI.
200 void cppMethod() const;
204 # A string that should come before the name of any type which has been marked
205 # as `#[repr(packed)]`. For instance, "__attribute__((packed))" would be a
206 # reasonable value if targeting gcc/clang. A more portable solution would
207 # involve emitting the name of a macro which you define in a platform-specific
210 # default: `#[repr(packed)]` types will be treated as opaque, since it would
211 # be unsafe for C callers to use a incorrectly laid-out union.
214 # A string that should come before the name of any type which has been marked
215 # as `#[repr(align(n))]`. This string must be a function-like macro which takes
216 # a single argument (the requested alignment, `n`). For instance, a macro
217 # `#define`d as `ALIGNED(n)` in `header` which translates to
218 # `__attribute__((aligned(n)))` would be a reasonable value if targeting
221 # default: `#[repr(align(n))]` types will be treated as opaque, since it
222 # could be unsafe for C callers to use a incorrectly-aligned union.
223 aligned_n = "ALIGNED"
227 # An optional prefix to put before every function declaration
228 # default: no prefix added
229 # prefix = "WR_START_FUNC"
231 # An optional postfix to put after any function declaration
232 # default: no postix added
233 # postfix = "WR_END_FUNC"
235 # How to format function arguments
238 # * "horizontal": place all arguments on the same line
239 # * "vertical": place each argument on its own line
240 # * "auto": only use vertical if horizontal would exceed line_length
245 # An optional string that should prefix function declarations which have been
246 # marked as `#[must_use]`. For instance, "__attribute__((warn_unused_result))"
247 # would be a reasonable value if targeting gcc/clang. A more portable solution
248 # would involve emitting the name of a macro which you define in a
249 # platform-specific way. e.g. "MUST_USE_FUNC"
250 # default: nothing is emitted for must_use functions
251 must_use = "MUST_USE_RES"
253 # An optional string that, if present, will be used to generate Swift function
254 # and method signatures for generated functions, for example "CF_SWIFT_NAME".
255 # If no such macro is available in your toolchain, you can define one using the
256 # `header` option in cbindgen.toml
257 # default: no swift_name function attributes are generated
258 # swift_name_macro = "CF_SWIFT_NAME"
260 # A rule to use to rename function argument names. The renaming assumes the input
261 # is the Rust standard snake_case, however it accepts all the different rename_args
262 # inputs. This means many options here are no-ops or redundant.
264 # possible values (that actually do something):
265 # * "CamelCase": my_arg => myArg
266 # * "PascalCase": my_arg => MyArg
267 # * "GeckoCase": my_arg => aMyArg
268 # * "ScreamingSnakeCase": my_arg => MY_ARG
269 # * "None": apply no renaming
271 # technically possible values (that shouldn't have a purpose here):
272 # * "SnakeCase": apply no renaming
273 # * "LowerCase": apply no renaming (actually applies to_lowercase, is this bug?)
274 # * "UpperCase": same as ScreamingSnakeCase in this context
275 # * "QualifiedScreamingSnakeCase" => same as ScreamingSnakeCase in this context
280 # This rule specifies if the order of functions will be sorted in some way.
282 # "Name": sort by the name of the function
283 # "None": keep order in which the functions have been parsed
289 # A rule to use to rename struct field names. The renaming assumes the input is
290 # the Rust standard snake_case, however it acccepts all the different rename_args
291 # inputs. This means many options here are no-ops or redundant.
293 # possible values (that actually do something):
294 # * "CamelCase": my_arg => myArg
295 # * "PascalCase": my_arg => MyArg
296 # * "GeckoCase": my_arg => mMyArg
297 # * "ScreamingSnakeCase": my_arg => MY_ARG
298 # * "None": apply no renaming
300 # technically possible values (that shouldn't have a purpose here):
301 # * "SnakeCase": apply no renaming
302 # * "LowerCase": apply no renaming (actually applies to_lowercase, is this bug?)
303 # * "UpperCase": same as ScreamingSnakeCase in this context
304 # * "QualifiedScreamingSnakeCase" => same as ScreamingSnakeCase in this context
307 rename_fields = "None"
309 # An optional string that should come before the name of any struct which has been
310 # marked as `#[must_use]`. For instance, "__attribute__((warn_unused))"
311 # would be a reasonable value if targeting gcc/clang. A more portable solution
312 # would involve emitting the name of a macro which you define in a
313 # platform-specific way. e.g. "MUST_USE_STRUCT"
315 # default: nothing is emitted for must_use structs
316 must_use = "MUST_USE_STRUCT"
318 # Whether a Rust type with associated consts should emit those consts inside the
319 # type's body. Otherwise they will be emitted trailing and with the type's name
320 # prefixed. This does nothing if the target is C, or if
321 # [const]allow_static_const = false
324 # associated_constants_in_body: false
326 # Whether to derive a simple constructor that takes a value for every field.
328 derive_constructor = true
330 # Whether to derive an operator== for all structs
334 # Whether to derive an operator!= for all structs
338 # Whether to derive an operator< for all structs
342 # Whether to derive an operator<= for all structs
346 # Whether to derive an operator> for all structs
350 # Whether to derive an operator>= for all structs
359 # A rule to use to rename enum variants, and the names of any fields those
360 # variants have. This should probably be split up into two separate options, but
361 # for now, they're the same! See the documentation for `[struct]rename_fields`
362 # for how this applies to fields. Renaming of the variant assumes that the input
363 # is the Rust standard PascalCase. In the case of QualifiedScreamingSnakeCase,
364 # it also assumed that the enum's name is PascalCase.
366 # possible values (that actually do something):
367 # * "CamelCase": MyVariant => myVariant
368 # * "SnakeCase": MyVariant => my_variant
369 # * "ScreamingSnakeCase": MyVariant => MY_VARIANT
370 # * "QualifiedScreamingSnakeCase": MyVariant => ENUM_NAME_MY_VARIANT
371 # * "LowerCase": MyVariant => myvariant
372 # * "UpperCase": MyVariant => MYVARIANT
373 # * "None": apply no renaming
375 # technically possible values (that shouldn't have a purpose for the variants):
376 # * "PascalCase": apply no renaming
377 # * "GeckoCase": apply no renaming
380 rename_variants = "None"
382 # Whether an extra "sentinel" enum variant should be added to all generated enums.
383 # Firefox uses this for their IPC serialization library.
385 # WARNING: if the sentinel is ever passed into Rust, behaviour will be Undefined.
386 # Rust does not know about this value, and will assume it cannot happen.
391 # Whether enum variant names should be prefixed with the name of the enum.
393 prefix_with_name = true
395 # Whether to emit enums using "enum class" when targeting C++.
399 # Whether to generate static `::MyVariant(..)` constructors and `bool IsMyVariant()`
400 # methods for enums with fields.
403 derive_helper_methods = false
405 # Whether to generate `const MyVariant& AsMyVariant() const` methods for enums with fields.
407 derive_const_casts = false
409 # Whether to generate `MyVariant& AsMyVariant()` methods for enums with fields
411 derive_mut_casts = false
413 # The name of the macro/function to use for asserting `IsMyVariant()` in the body of
414 # derived `AsMyVariant()` cast methods.
416 # default: "assert" (but also causes `<cassert>` to be included by default)
417 cast_assert_name = "MOZ_RELEASE_ASSERT"
419 # An optional string that should come before the name of any enum which has been
420 # marked as `#[must_use]`. For instance, "__attribute__((warn_unused))"
421 # would be a reasonable value if targeting gcc/clang. A more portable solution
422 # would involve emitting the name of a macro which you define in a
423 # platform-specific way. e.g. "MUST_USE_ENUM"
425 # Note that this refers to the *output* type. That means this will not apply to an enum
426 # with fields, as it will be emitted as a struct. `[struct]must_use` will apply there.
428 # default: nothing is emitted for must_use enums
429 must_use = "MUST_USE_ENUM"
431 # Whether enums with fields should generate destructors. This exists so that generic
432 # enums can be properly instantiated with payloads that are C++ types with
433 # destructors. This isn't necessary for structs because C++ has rules to
434 # automatically derive the correct constructors and destructors for those types.
436 # Care should be taken with this option, as Rust and C++ cannot
437 # properly interoperate with eachother's notions of destructors. Also, this may
438 # change the ABI for the type. Either your destructor-full enums must live
439 # exclusively within C++, or they must only be passed by-reference between
443 derive_tagged_enum_destructor = false
445 # Whether enums with fields should generate copy-constructor. See the discussion on
446 # derive_tagged_enum_destructor for why this is both useful and very dangerous.
449 derive_tagged_enum_copy_constructor = false
450 # Whether enums with fields should generate copy-assignment operators.
452 # This depends on also deriving copy-constructors, and it is highly encouraged
453 # for this to be set to true.
456 derive_tagged_enum_copy_assignment = false
458 # Whether enums with fields should generate an empty, private destructor.
459 # This allows the auto-generated constructor functions to compile, if there are
460 # non-trivially constructible members. This falls in the same family of
461 # dangerousness as `derive_tagged_enum_copy_constructor` and co.
464 private_default_tagged_enum_constructor = false
471 # Whether a generated constant can be a static const in C++ mode. I have no
472 # idea why you would turn this off.
475 allow_static_const = true
477 # Whether a generated constant can be constexpr in C++ mode.
486 # Whether bindings should be generated for instances of the bitflags! macro.
495 # Options for how your Rust library should be parsed
498 # Whether to parse dependent crates and include their types in the output
502 # A white list of crate names that are allowed to be parsed. If this is defined,
503 # only crates found in this list will ever be parsed.
505 # default: there is no whitelist (NOTE: this is the opposite of [])
506 include = ["webrender", "webrender_traits"]
508 # A black list of crate names that are not allowed to be parsed.
512 # Whether to use a new temporary target directory when running `rustc --pretty=expanded`.
513 # This may be required for some build processes.
518 # Which crates other than the top-level binding crate we should generate
522 extra_bindings = ["my_awesome_dep"]
525 # A list of crate names that should be run through `cargo expand` before
526 # parsing to expand any macros. Note that if a crate is named here, it
527 # will always be parsed, even if the blacklist/whitelist says it shouldn't be.
532 # If enabled, use the `--all-features` option when expanding. Ignored when
533 # `features` is set. For backwards-compatibility, this is forced on if
534 # `expand = ["euclid"]` shorthand is used.
539 # When `all_features` is disabled and this is also disabled, use the
540 # `--no-default-features` option when expanding.
543 default_features = true
545 # A list of feature names that should be used when running `cargo expand`. This
546 # combines with `default_features` like in your `Cargo.toml`. Note that the features
547 # listed here are features for the current crate being built, *not* the crates
548 # being expanded. The crate's `Cargo.toml` must take care of enabling the
549 # appropriate features in its dependencies
552 features = ["cbindgen"]
555 non_null_attribute = "NONNULL_PTR"