Commit c9eadb88 authored by Ryan Hunt's avatar Ryan Hunt
Browse files

Update the config documentation in README.md

parent 3fdeb457
......@@ -45,24 +45,97 @@ fn main() {
## Configuration
There are some options that can be used to configure the binding generation. They can be specified by creating a `cbindgen.toml` with the options in the binding crate root. Alternatively, build scripts can specify them using `cbindgen::generate_with_config`.
Some useful options:
1. `header` - optional text to output at the beginning of the file
2. `trailer` - optional text to output at the end of the file
3. `include_guard` - optional name to use for an include guard
4. `autogen_warning` - optional text to output at major sections to deter manual editing
5. `include_version` - whether to include a comment with the version of cbindgen used to generate the file
6. `braces` - the style to use for braces (can be either SameLine or NextLine)
7. `line_length` - the preferred length of a line, used when auto breaking function arguments
8. `tab_width` - the amount of spaces in an indentation
9. `language` - the language to generate bindings in (can be either C++ or C)
10. `parse_deps` - whether to parse dependent crates
11. `include` - an optional whitelist to use when parsing dependent crates
12. `exclude` - an optional blacklist to use when parsing dependent crates
There are some options that can be used to configure the binding generation. They can be specified by creating a `cbindgen.toml` with the options in the binding crate root or at a path manually specified through the command line. Alternatively, build scripts can specify them using `cbindgen::generate_with_config`.
Here is a description of the options available in a config.
```toml
# An optional string of text to output at the beginning of the generated file
header = <string>
# An optional string of text to output at the end of the generated file
trailer = <string>
# An optional name to use as an include guard
include_guard = <string>
# An optional string of text to output between major sections of the generated
# file as a warning against manual editing
autogen_warning = <string>
# Whether to include a comment with the version of cbindgen used to generate the
# file
include_version = <bool>
# An optional namespace to output around the generated bindings
namespace = <string>
# An optional list of namespaces to output around the generated bindings
namespaces = [<string>]
# The style to use for curly braces
braces = <curly>
# The desired length of a line to use when formatting lines
line_length = <integer>
# The amount of spaces in a tab
tab_width = <integer>
# The language to output bindings in
language = <language>
[parse]
# Whether to parse dependent crates and include their types in the generated
# bindings
parse_deps = <bool>
# A white list of crate names that are allowed to be parsed
include = [<string>]
# A black list of crate names that are not allowed to be parsed
exclude = [<string>]
# A list of crate names that should be run through `cargo expand` before
# parsing to expand any macros
expand = [<string>]
[fn]
# An optional prefix to put before every function declaration
prefix = <string>
# An optional postfix to put after any function declaration
postfix = <string>
# How to format function arguments
args = <layout>
# A rule to use to rename function argument names
rename_args = <rename-rule>
[struct]
# A rule to use to rename field names
rename_fields = <rename-rule>
# Whether to derive an operator== for all structs
derive_eq = <bool>
# Whether to derive an operator!= for all structs
derive_neq = <bool>
# Whether to derive an operator< for all structs
derive_lt = <bool>
# Whether to derive an operator<= for all structs
derive_lte = <bool>
# Whether to derive an operator> for all structs
derive_gt = <bool>
# Whether to derive an operator>= for all structs
derive_gte = <bool>
[enum]
# A rule to use to rename enum variants
rename_variants = <rename-rule>
# With
<curly> = ["SameLine" | "NextLine"]
<language> = ["C++" | "C"]
<layout> = ["Auto" |
"Vertical" |
"Horizontal"]
<rename-rule> = ["None" |
"GeckoCase" |
"LowerCase" |
"UpperCase" |
"PascalCase" |
"CamelCase" |
"SnakeCase" |
"ScreamingSnakeCase" |
"QualifiedScreamingSnakeCase"]
```
A full listing of options can be found in `src/bindgen/config.rs`
A full listing of options can be found in `src/bindgen/config.rs`.
## Examples
......@@ -74,7 +147,7 @@ See `compile-tests/` for some examples of rust source that can be handled.
2. A dependency graph is built using the extern "C" functions as roots
* This removes unneeded types from the bindings and sorts the structs that depend on each other
3. Some code generation is done to specialize generics that are specified as type aliases
3. The items are printed in dependency order in C syntax
4. The items are printed in dependency order in C syntax
## Future work
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment