Merge pull request #618 from TheBlueMatt/2020-05-sample-c-bindings
[rust-lightning] / lightning-c-bindings / cbindgen.toml
diff --git a/lightning-c-bindings/cbindgen.toml b/lightning-c-bindings/cbindgen.toml
new file mode 100644 (file)
index 0000000..4826778
--- /dev/null
@@ -0,0 +1,552 @@
+# The language to output bindings in
+#
+# possible values: "C", "C++"
+#
+# default: "C++"
+language = "C"
+
+
+
+
+# Options for wrapping the contents of the header:
+
+# An optional string of text to output at the beginning of the generated file
+# default: doesn't emit anything
+header = "/* Text to put at the beginning of the generated file. Probably a license. */"
+
+# An optional string of text to output at the end of the generated file
+# default: doesn't emit anything
+trailer = "/* Text to put at the end of the generated file */"
+
+# An optional name to use as an include guard
+# default: doesn't emit an include guard
+# include_guard = "mozilla_wr_bindings_h"
+
+# An optional string of text to output between major sections of the generated
+# file as a warning against manual editing
+#
+# default: doesn't emit anything
+autogen_warning = "/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */"
+
+# Whether to include a comment with the version of cbindgen used to generate the file
+# default: false
+include_version = true
+
+# An optional namespace to output around the generated bindings
+# default: doesn't emit a namespace
+namespace = "LDK"
+
+# An optional list of namespaces to output around the generated bindings
+# default: []
+namespaces = []
+
+# An optional list of namespaces to declare as using with "using namespace"
+# default: []
+using_namespaces = []
+
+# A list of sys headers to #include (with angle brackets)
+# default: []
+# sys_includes = ["stdio", "string"]
+# sys_includes = ["stdint"]
+
+# A list of headers to #include (with quotes)
+# default: []
+# includes = ["my_great_lib.h"]
+
+# Whether cbindgen's default C/C++ standard imports should be suppressed. These
+# imports are included by default because our generated headers tend to require
+# them (e.g. for uint32_t). Currently, the generated imports are:
+#
+# * for C: <stdarg.h>, <stdbool.h>, <stdint.h>, <stdlib.h>, <uchar.h>
+#
+# * for C++: <cstdarg>, <cstdint>, <cstdlib>, <new>, <cassert> (depending on config)
+#
+# default: false
+no_includes = false
+
+
+
+
+
+# Code Style Options
+
+# The style to use for curly braces
+#
+# possible values: "SameLine", "NextLine"
+#
+# default: "SameLine"
+braces = "SameLine"
+
+# The desired length of a line to use when formatting lines
+# default: 100
+line_length = 80
+
+# The amount of spaces to indent by
+# default: 2
+tab_width = 3
+
+# How the generated documentation should be commented.
+#
+# possible values:
+# * "c": /* like this */
+# * "c99": // like this
+# * "c++": /// like this
+# * "doxy": like C, but with leading *'s on each line
+# * "auto": "c++" if that's the language, "doxy" otherwise
+#
+# default: "auto"
+documentation_style = "doxy"
+
+
+
+
+
+# Codegen Options
+
+# When generating a C header, the kind of declaration style to use for structs
+# or enums.
+#
+# possible values:
+# * "type": typedef struct { ... } MyType;
+# * "tag": struct MyType { ... };
+# * "both": typedef struct MyType { ... } MyType;
+#
+# default: "both"
+style = "both"
+
+# A list of substitutions for converting cfg's to ifdefs. cfgs which aren't
+# defined here will just be discarded.
+#
+# e.g.
+# `#[cfg(target = "freebsd")] ...`
+# becomes
+# `#if defined(DEFINE_FREEBSD) ... #endif`
+[defines]
+"target_os = freebsd" = "DEFINE_FREEBSD"
+"feature = serde" = "DEFINE_SERDE"
+
+
+
+
+
+[export]
+# A list of additional items to always include in the generated bindings if they're
+# found but otherwise don't appear to be used by the public API.
+#
+# default: []
+# include = ["MyOrphanStruct", "MyGreatTypeRename"]
+
+# A list of items to not include in the generated bindings
+# default: []
+# exclude = ["Bad"]
+
+# A prefix to add before the name of every item
+# default: no prefix is added
+prefix = "LDK"
+
+# Types of items that we'll generate. If empty, then all types of item are emitted.
+#
+# possible items: (TODO: explain these in detail)
+# * "constants":
+# * "globals":
+# * "enums":
+# * "structs":
+# * "unions":
+# * "typedefs":
+# * "opaque":
+# * "functions":
+#
+# default: []
+item_types = ["constants", "globals", "enums", "structs", "unions", "typedefs", "opaque", "functions"]
+
+# Whether applying rules in export.rename prevents export.prefix from applying.
+#
+# e.g. given this toml:
+#
+# [export]
+# prefix = "capi_"
+# [export.rename]
+# "MyType" = "my_cool_type"
+#
+# You get the following results:
+#
+# renaming_overrides_prefixing = true:
+# "MyType" => "my_cool_type"
+#
+# renaming_overrides_prefixing = false:
+# "MyType => capi_my_cool_type"
+#
+# default: false
+renaming_overrides_prefixing = true
+
+# Table of name conversions to apply to item names (lhs becomes rhs)
+# [export.rename]
+# "MyType" = "my_cool_type"
+# "my_function" = "BetterFunctionName"
+
+# Table of things to prepend to the body of any struct, union, or enum that has the
+# given name. This can be used to add things like methods which don't change ABI,
+# mark fields private, etc
+[export.pre_body]
+"MyType" = """
+  MyType() = delete;
+private:
+"""
+
+# Table of things to append to the body of any struct, union, or enum that has the
+# given name. This can be used to add things like methods which don't change ABI.
+[export.body]
+"MyType" = """
+  void cppMethod() const;
+"""
+
+[layout]
+# A string that should come before the name of any type which has been marked
+# as `#[repr(packed)]`. For instance, "__attribute__((packed))" would be a
+# reasonable value if targeting gcc/clang. A more portable solution would
+# involve emitting the name of a macro which you define in a platform-specific
+# way. e.g. "PACKED"
+#
+# default: `#[repr(packed)]` types will be treated as opaque, since it would
+# be unsafe for C callers to use a incorrectly laid-out union.
+packed = "PACKED"
+
+# A string that should come before the name of any type which has been marked
+# as `#[repr(align(n))]`. This string must be a function-like macro which takes
+# a single argument (the requested alignment, `n`). For instance, a macro
+# `#define`d as `ALIGNED(n)` in `header` which translates to
+# `__attribute__((aligned(n)))` would be a reasonable value if targeting
+# gcc/clang.
+#
+# default: `#[repr(align(n))]` types will be treated as opaque, since it
+# could be unsafe for C callers to use a incorrectly-aligned union.
+aligned_n = "ALIGNED"
+
+
+[fn]
+# An optional prefix to put before every function declaration
+# default: no prefix added
+# prefix = "WR_START_FUNC"
+
+# An optional postfix to put after any function declaration
+# default: no postix added
+# postfix = "WR_END_FUNC"
+
+# How to format function arguments
+#
+# possible values:
+# * "horizontal": place all arguments on the same line
+# * "vertical": place each argument on its own line
+# * "auto": only use vertical if horizontal would exceed line_length
+#
+# default: "auto"
+args = "horizontal"
+
+# An optional string that should prefix function declarations which have been
+# marked as `#[must_use]`. For instance, "__attribute__((warn_unused_result))"
+# would be a reasonable value if targeting gcc/clang. A more portable solution
+# would involve emitting the name of a macro which you define in a
+# platform-specific way. e.g. "MUST_USE_FUNC"
+# default: nothing is emitted for must_use functions
+must_use = "MUST_USE_RES"
+
+# An optional string that, if present, will be used to generate Swift function
+# and method signatures for generated functions, for example "CF_SWIFT_NAME".
+# If no such macro is available in your toolchain, you can define one using the
+# `header` option in cbindgen.toml
+# default: no swift_name function attributes are generated
+# swift_name_macro = "CF_SWIFT_NAME"
+
+# A rule to use to rename function argument names. The renaming assumes the input
+# is the Rust standard snake_case, however it accepts all the different rename_args
+# inputs. This means many options here are no-ops or redundant.
+#
+# possible values (that actually do something):
+# * "CamelCase": my_arg => myArg
+# * "PascalCase": my_arg => MyArg
+# * "GeckoCase": my_arg => aMyArg
+# * "ScreamingSnakeCase": my_arg => MY_ARG
+# * "None": apply no renaming
+#
+# technically possible values (that shouldn't have a purpose here):
+# * "SnakeCase": apply no renaming
+# * "LowerCase": apply no renaming (actually applies to_lowercase, is this bug?)
+# * "UpperCase": same as ScreamingSnakeCase in this context
+# * "QualifiedScreamingSnakeCase" => same as ScreamingSnakeCase in this context
+#
+# default: "None"
+rename_args = "None"
+
+# This rule specifies if the order of functions will be sorted in some way.
+#
+# "Name": sort by the name of the function
+# "None": keep order in which the functions have been parsed
+#
+# default: "Name"
+sort_by = "None"
+
+[struct]
+# A rule to use to rename struct field names. The renaming assumes the input is
+# the Rust standard snake_case, however it acccepts all the different rename_args
+# inputs. This means many options here are no-ops or redundant.
+#
+# possible values (that actually do something):
+# * "CamelCase": my_arg => myArg
+# * "PascalCase": my_arg => MyArg
+# * "GeckoCase": my_arg => mMyArg
+# * "ScreamingSnakeCase": my_arg => MY_ARG
+# * "None": apply no renaming
+#
+# technically possible values (that shouldn't have a purpose here):
+# * "SnakeCase": apply no renaming
+# * "LowerCase": apply no renaming (actually applies to_lowercase, is this bug?)
+# * "UpperCase": same as ScreamingSnakeCase in this context
+# * "QualifiedScreamingSnakeCase" => same as ScreamingSnakeCase in this context
+#
+# default: "None"
+rename_fields = "None"
+
+# An optional string that should come before the name of any struct which has been
+# marked as `#[must_use]`. For instance, "__attribute__((warn_unused))"
+# would be a reasonable value if targeting gcc/clang. A more portable solution
+# would involve emitting the name of a macro which you define in a
+# platform-specific way. e.g. "MUST_USE_STRUCT"
+#
+# default: nothing is emitted for must_use structs
+must_use = "MUST_USE_STRUCT"
+
+# Whether a Rust type with associated consts should emit those consts inside the
+# type's body. Otherwise they will be emitted trailing and with the type's name
+# prefixed. This does nothing if the target is C, or if
+# [const]allow_static_const = false
+#
+# default: false
+# associated_constants_in_body: false
+
+# Whether to derive a simple constructor that takes a value for every field.
+# default: false
+derive_constructor = true
+
+# Whether to derive an operator== for all structs
+# default: false
+derive_eq = false
+
+# Whether to derive an operator!= for all structs
+# default: false
+derive_neq = false
+
+# Whether to derive an operator< for all structs
+# default: false
+derive_lt = false
+
+# Whether to derive an operator<= for all structs
+# default: false
+derive_lte = false
+
+# Whether to derive an operator> for all structs
+# default: false
+derive_gt = false
+
+# Whether to derive an operator>= for all structs
+# default: false
+derive_gte = false
+
+
+
+
+
+[enum]
+# A rule to use to rename enum variants, and the names of any fields those
+# variants have. This should probably be split up into two separate options, but
+# for now, they're the same! See the documentation for `[struct]rename_fields`
+# for how this applies to fields. Renaming of the variant assumes that the input
+# is the Rust standard PascalCase. In the case of QualifiedScreamingSnakeCase,
+# it also assumed that the enum's name is PascalCase.
+#
+# possible values (that actually do something):
+# * "CamelCase": MyVariant => myVariant
+# * "SnakeCase": MyVariant => my_variant
+# * "ScreamingSnakeCase": MyVariant => MY_VARIANT
+# * "QualifiedScreamingSnakeCase": MyVariant => ENUM_NAME_MY_VARIANT
+# * "LowerCase": MyVariant => myvariant
+# * "UpperCase": MyVariant => MYVARIANT
+# * "None": apply no renaming
+#
+# technically possible values (that shouldn't have a purpose for the variants):
+# * "PascalCase": apply no renaming
+# * "GeckoCase": apply no renaming
+#
+# default: "None"
+rename_variants = "None"
+
+# Whether an extra "sentinel" enum variant should be added to all generated enums.
+# Firefox uses this for their IPC serialization library.
+#
+# WARNING: if the sentinel is ever passed into Rust, behaviour will be Undefined.
+# Rust does not know about this value, and will assume it cannot happen.
+#
+# default: false
+add_sentinel = true
+
+# Whether enum variant names should be prefixed with the name of the enum.
+# default: false
+prefix_with_name = true
+
+# Whether to emit enums using "enum class" when targeting C++.
+# default: true
+enum_class = true
+
+# Whether to generate static `::MyVariant(..)` constructors and `bool IsMyVariant()`
+# methods for enums with fields.
+#
+# default: false
+derive_helper_methods = false
+
+# Whether to generate `const MyVariant& AsMyVariant() const` methods for enums with fields.
+# default: false
+derive_const_casts = false
+
+# Whether to generate `MyVariant& AsMyVariant()` methods for enums with fields
+# default: false
+derive_mut_casts = false
+
+# The name of the macro/function to use for asserting `IsMyVariant()` in the body of
+# derived `AsMyVariant()` cast methods.
+#
+# default: "assert" (but also causes `<cassert>` to be included by default)
+cast_assert_name = "MOZ_RELEASE_ASSERT"
+
+# An optional string that should come before the name of any enum which has been
+# marked as `#[must_use]`. For instance, "__attribute__((warn_unused))"
+# would be a reasonable value if targeting gcc/clang. A more portable solution
+# would involve emitting the name of a macro which you define in a
+# platform-specific way. e.g. "MUST_USE_ENUM"
+#
+# Note that this refers to the *output* type. That means this will not apply to an enum
+# with fields, as it will be emitted as a struct. `[struct]must_use` will apply there.
+#
+# default: nothing is emitted for must_use enums
+must_use = "MUST_USE_ENUM"
+
+# Whether enums with fields should generate destructors. This exists so that generic
+# enums can be properly instantiated with payloads that are C++ types with
+# destructors. This isn't necessary for structs because C++ has rules to
+# automatically derive the correct constructors and destructors for those types.
+#
+# Care should be taken with this option, as Rust and C++ cannot
+# properly interoperate with eachother's notions of destructors. Also, this may
+# change the ABI for the type. Either your destructor-full enums must live
+# exclusively within C++, or they must only be passed by-reference between
+# C++ and Rust.
+#
+# default: false
+derive_tagged_enum_destructor = false
+
+# Whether enums with fields should generate copy-constructor. See the discussion on
+# derive_tagged_enum_destructor for why this is both useful and very dangerous.
+#
+# default: false
+derive_tagged_enum_copy_constructor = false
+# Whether enums with fields should generate copy-assignment operators.
+#
+# This depends on also deriving copy-constructors, and it is highly encouraged
+# for this to be set to true.
+#
+# default: false
+derive_tagged_enum_copy_assignment = false
+
+# Whether enums with fields should generate an empty, private destructor.
+# This allows the auto-generated constructor functions to compile, if there are
+# non-trivially constructible members. This falls in the same family of
+# dangerousness as `derive_tagged_enum_copy_constructor` and co.
+#
+# default: false
+private_default_tagged_enum_constructor = false
+
+
+
+
+
+[const]
+# Whether a generated constant can be a static const in C++ mode. I have no
+# idea why you would turn this off.
+#
+# default: true
+allow_static_const = true
+
+# Whether a generated constant can be constexpr in C++ mode.
+#
+# default: false
+
+
+
+
+
+[macro_expansion]
+# Whether bindings should be generated for instances of the bitflags! macro.
+# default: false
+bitflags = true
+
+
+
+
+
+
+# Options for how your Rust library should be parsed
+
+[parse]
+# Whether to parse dependent crates and include their types in the output
+# default: false
+parse_deps = true
+
+# A white list of crate names that are allowed to be parsed. If this is defined,
+# only crates found in this list will ever be parsed.
+#
+# default: there is no whitelist (NOTE: this is the opposite of [])
+include = ["webrender", "webrender_traits"]
+
+# A black list of crate names that are not allowed to be parsed.
+# default: []
+exclude = ["libc"]
+
+# Whether to use a new temporary target directory when running `rustc --pretty=expanded`.
+# This may be required for some build processes.
+#
+# default: false
+clean = false
+
+# Which crates other than the top-level binding crate we should generate
+# bindings for.
+#
+# default: []
+extra_bindings = ["my_awesome_dep"]
+
+[parse.expand]
+# A list of crate names that should be run through `cargo expand` before
+# parsing to expand any macros. Note that if a crate is named here, it
+# will always be parsed, even if the blacklist/whitelist says it shouldn't be.
+#
+# default: []
+crates = ["euclid"]
+
+# If enabled,  use the `--all-features` option when expanding. Ignored when
+# `features` is set. For backwards-compatibility, this is forced on if
+# `expand = ["euclid"]` shorthand is used.
+#
+# default: false
+all_features = false
+
+# When `all_features` is disabled and this is also disabled, use the
+# `--no-default-features` option when expanding.
+#
+# default: true
+default_features = true
+
+# A list of feature names that should be used when running `cargo expand`. This
+# combines with `default_features` like in your `Cargo.toml`. Note that the features
+# listed here are features for the current crate being built, *not* the crates
+# being expanded. The crate's `Cargo.toml` must take care of enabling the
+# appropriate features in its dependencies
+#
+# default: []
+features = ["cbindgen"]