]> git.bitcoin.ninja Git - rust-lightning/blob - lightning-c-bindings/cbindgen.toml
SimpleArcPeerManager type: remove outer Arc for flexibility
[rust-lightning] / lightning-c-bindings / cbindgen.toml
1 # The language to output bindings in
2 #
3 # possible values: "C", "C++"
4 #
5 # default: "C++"
6 language = "C"
7
8
9
10
11 # Options for wrapping the contents of the header:
12
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. */"
16
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 */"
20
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"
24
25 # An optional string of text to output between major sections of the generated
26 # file as a warning against manual editing
27 #
28 # default: doesn't emit anything
29 autogen_warning = "/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */"
30
31 # Whether to include a comment with the version of cbindgen used to generate the file
32 # default: false
33 include_version = true
34
35 # An optional namespace to output around the generated bindings
36 # default: doesn't emit a namespace
37 namespace = "LDK"
38
39 # An optional list of namespaces to output around the generated bindings
40 # default: []
41 namespaces = []
42
43 # An optional list of namespaces to declare as using with "using namespace"
44 # default: []
45 using_namespaces = []
46
47 # A list of sys headers to #include (with angle brackets)
48 # default: []
49 # sys_includes = ["stdio", "string"]
50 # sys_includes = ["stdint"]
51
52 # A list of headers to #include (with quotes)
53 # default: []
54 # includes = ["my_great_lib.h"]
55
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:
59 #
60 # * for C: <stdarg.h>, <stdbool.h>, <stdint.h>, <stdlib.h>, <uchar.h>
61 #
62 # * for C++: <cstdarg>, <cstdint>, <cstdlib>, <new>, <cassert> (depending on config)
63 #
64 # default: false
65 no_includes = false
66
67
68
69
70
71 # Code Style Options
72
73 # The style to use for curly braces
74 #
75 # possible values: "SameLine", "NextLine"
76 #
77 # default: "SameLine"
78 braces = "SameLine"
79
80 # The desired length of a line to use when formatting lines
81 # default: 100
82 line_length = 80
83
84 # The amount of spaces to indent by
85 # default: 2
86 tab_width = 3
87
88 # How the generated documentation should be commented.
89 #
90 # possible values:
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
96 #
97 # default: "auto"
98 documentation_style = "doxy"
99
100
101
102
103
104 # Codegen Options
105
106 # When generating a C header, the kind of declaration style to use for structs
107 # or enums.
108 #
109 # possible values:
110 # * "type": typedef struct { ... } MyType;
111 # * "tag": struct MyType { ... };
112 # * "both": typedef struct MyType { ... } MyType;
113 #
114 # default: "both"
115 style = "both"
116
117 # A list of substitutions for converting cfg's to ifdefs. cfgs which aren't
118 # defined here will just be discarded.
119 #
120 # e.g.
121 # `#[cfg(target = "freebsd")] ...`
122 # becomes
123 # `#if defined(DEFINE_FREEBSD) ... #endif`
124 [defines]
125 "target_os = freebsd" = "DEFINE_FREEBSD"
126 "feature = serde" = "DEFINE_SERDE"
127
128
129
130
131
132 [export]
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.
135 #
136 # default: []
137 # include = ["MyOrphanStruct", "MyGreatTypeRename"]
138
139 # A list of items to not include in the generated bindings
140 # default: []
141 # exclude = ["Bad"]
142
143 # A prefix to add before the name of every item
144 # default: no prefix is added
145 prefix = "LDK"
146
147 # Types of items that we'll generate. If empty, then all types of item are emitted.
148 #
149 # possible items: (TODO: explain these in detail)
150 # * "constants":
151 # * "globals":
152 # * "enums":
153 # * "structs":
154 # * "unions":
155 # * "typedefs":
156 # * "opaque":
157 # * "functions":
158 #
159 # default: []
160 item_types = ["constants", "globals", "enums", "structs", "unions", "typedefs", "opaque", "functions"]
161
162 # Whether applying rules in export.rename prevents export.prefix from applying.
163 #
164 # e.g. given this toml:
165 #
166 # [export]
167 # prefix = "capi_"
168 # [export.rename]
169 # "MyType" = "my_cool_type"
170 #
171 # You get the following results:
172 #
173 # renaming_overrides_prefixing = true:
174 # "MyType" => "my_cool_type"
175 #
176 # renaming_overrides_prefixing = false:
177 # "MyType => capi_my_cool_type"
178 #
179 # default: false
180 renaming_overrides_prefixing = true
181
182 # Table of name conversions to apply to item names (lhs becomes rhs)
183 # [export.rename]
184 # "MyType" = "my_cool_type"
185 # "my_function" = "BetterFunctionName"
186
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
190 [export.pre_body]
191 "MyType" = """
192   MyType() = delete;
193 private:
194 """
195
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.
198 [export.body]
199 "MyType" = """
200   void cppMethod() const;
201 """
202
203 [layout]
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
208 # way. e.g. "PACKED"
209 #
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.
212 packed = "PACKED"
213
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
219 # gcc/clang.
220 #
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"
224
225
226 [fn]
227 # An optional prefix to put before every function declaration
228 # default: no prefix added
229 # prefix = "WR_START_FUNC"
230
231 # An optional postfix to put after any function declaration
232 # default: no postix added
233 # postfix = "WR_END_FUNC"
234
235 # How to format function arguments
236 #
237 # possible values:
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
241 #
242 # default: "auto"
243 args = "horizontal"
244
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"
252
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"
259
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.
263 #
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
270 #
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
276 #
277 # default: "None"
278 rename_args = "None"
279
280 # This rule specifies if the order of functions will be sorted in some way.
281 #
282 # "Name": sort by the name of the function
283 # "None": keep order in which the functions have been parsed
284 #
285 # default: "Name"
286 sort_by = "None"
287
288 [struct]
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.
292 #
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
299 #
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
305 #
306 # default: "None"
307 rename_fields = "None"
308
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"
314 #
315 # default: nothing is emitted for must_use structs
316 must_use = "MUST_USE_STRUCT"
317
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
322 #
323 # default: false
324 # associated_constants_in_body: false
325
326 # Whether to derive a simple constructor that takes a value for every field.
327 # default: false
328 derive_constructor = true
329
330 # Whether to derive an operator== for all structs
331 # default: false
332 derive_eq = false
333
334 # Whether to derive an operator!= for all structs
335 # default: false
336 derive_neq = false
337
338 # Whether to derive an operator< for all structs
339 # default: false
340 derive_lt = false
341
342 # Whether to derive an operator<= for all structs
343 # default: false
344 derive_lte = false
345
346 # Whether to derive an operator> for all structs
347 # default: false
348 derive_gt = false
349
350 # Whether to derive an operator>= for all structs
351 # default: false
352 derive_gte = false
353
354
355
356
357
358 [enum]
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.
365 #
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
374 #
375 # technically possible values (that shouldn't have a purpose for the variants):
376 # * "PascalCase": apply no renaming
377 # * "GeckoCase": apply no renaming
378 #
379 # default: "None"
380 rename_variants = "None"
381
382 # Whether an extra "sentinel" enum variant should be added to all generated enums.
383 # Firefox uses this for their IPC serialization library.
384 #
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.
387 #
388 # default: false
389 add_sentinel = true
390
391 # Whether enum variant names should be prefixed with the name of the enum.
392 # default: false
393 prefix_with_name = true
394
395 # Whether to emit enums using "enum class" when targeting C++.
396 # default: true
397 enum_class = true
398
399 # Whether to generate static `::MyVariant(..)` constructors and `bool IsMyVariant()`
400 # methods for enums with fields.
401 #
402 # default: false
403 derive_helper_methods = false
404
405 # Whether to generate `const MyVariant& AsMyVariant() const` methods for enums with fields.
406 # default: false
407 derive_const_casts = false
408
409 # Whether to generate `MyVariant& AsMyVariant()` methods for enums with fields
410 # default: false
411 derive_mut_casts = false
412
413 # The name of the macro/function to use for asserting `IsMyVariant()` in the body of
414 # derived `AsMyVariant()` cast methods.
415 #
416 # default: "assert" (but also causes `<cassert>` to be included by default)
417 cast_assert_name = "MOZ_RELEASE_ASSERT"
418
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"
424 #
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.
427 #
428 # default: nothing is emitted for must_use enums
429 must_use = "MUST_USE_ENUM"
430
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.
435 #
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
440 # C++ and Rust.
441 #
442 # default: false
443 derive_tagged_enum_destructor = false
444
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.
447 #
448 # default: false
449 derive_tagged_enum_copy_constructor = false
450 # Whether enums with fields should generate copy-assignment operators.
451 #
452 # This depends on also deriving copy-constructors, and it is highly encouraged
453 # for this to be set to true.
454 #
455 # default: false
456 derive_tagged_enum_copy_assignment = false
457
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.
462 #
463 # default: false
464 private_default_tagged_enum_constructor = false
465
466
467
468
469
470 [const]
471 # Whether a generated constant can be a static const in C++ mode. I have no
472 # idea why you would turn this off.
473 #
474 # default: true
475 allow_static_const = true
476
477 # Whether a generated constant can be constexpr in C++ mode.
478 #
479 # default: false
480
481
482
483
484
485 [macro_expansion]
486 # Whether bindings should be generated for instances of the bitflags! macro.
487 # default: false
488 bitflags = true
489
490
491
492
493
494
495 # Options for how your Rust library should be parsed
496
497 [parse]
498 # Whether to parse dependent crates and include their types in the output
499 # default: false
500 parse_deps = true
501
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.
504 #
505 # default: there is no whitelist (NOTE: this is the opposite of [])
506 include = ["webrender", "webrender_traits"]
507
508 # A black list of crate names that are not allowed to be parsed.
509 # default: []
510 exclude = ["libc"]
511
512 # Whether to use a new temporary target directory when running `rustc --pretty=expanded`.
513 # This may be required for some build processes.
514 #
515 # default: false
516 clean = false
517
518 # Which crates other than the top-level binding crate we should generate
519 # bindings for.
520 #
521 # default: []
522 extra_bindings = ["my_awesome_dep"]
523
524 [parse.expand]
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.
528 #
529 # default: []
530 crates = ["euclid"]
531
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.
535 #
536 # default: false
537 all_features = false
538
539 # When `all_features` is disabled and this is also disabled, use the
540 # `--no-default-features` option when expanding.
541 #
542 # default: true
543 default_features = true
544
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
550 #
551 # default: []
552 features = ["cbindgen"]
553
554 [ptr]
555 non_null_attribute = "NONNULL_PTR"