Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
448 lines (413 sloc) 20.4 KB
# Configuration template - Base your bindgen configuration on this!
# A note on templates: Some values are "templated". This means they're of type
# `String`. All occurences of the percent-sign ("%") will be replaced by a
# computed value.
# Additionally, templated strings allow access to environment variables using
# curly braces: `{CC}` would be expanded to the value of `ENV["CC"]`. It's
# possible to provide a fall back value, which is used only if the given
# environment variable doesn't exist: `{CC|gcc}` would expand to `ENV["CC"]`,
# or if it is not set, to `gcc`. You can also put a percent-sign in there:
# `{LIBRARY_PATH|%}` will expand to `ENV["LIBRARY_PATH"]`, or to the replacement
# value otherwise.
# Defines the `module X` into which *all* code will be put.
# Mandatory!
module: MyStuff
# Defines how conversions in C/C++ shall happen. Use `boehmgc-cpp` for C++,
# or `boehmgc-c` for pure C.
#
# Don't worry too much about this setting at first.
cookbook: boehmgc-cpp # Default!
# Defines the `ld_flags` value for the `@[Link]` directive of the generated `lib`.
# `%` will be replaced by the path to the base-directory of your project,
# relative to the path of the generated `.cr` file.
library: "%/ext/binding.a"
# Processors pipeline. See `README.md` for details on each.
# Defaults to the following:
processors:
# Graph-refining processors:
- default_constructor # Create default constructors where possible
- function_class # Turn OOP-y C APIs into real classes
- inheritance # Mirror inheritance hierarchy from C++
- copy_structs # Copy structures as marked
- macros # Support for macro mapping
- functions # Add non-class functions
- filter_methods # Throw out filtered methods
- extern_c # Directly bind to pure C functions
- instantiate_containers # Actually instantiate containers
- enums # Add enums
# Preliminary generation processors:
- crystal_wrapper # Create Crystal wrappers
- virtual_override # Allow overriding C++ virtual methods
- cpp_wrapper # Create C++ <-> C wrappers
- crystal_binding # Create `lib` bindings for the C wrapper
- sanity_check # Shows issues, if any
# Generator configuration. These write the actual output to disk.
generators:
# C++ generator
cpp:
# Output file path (Mandatory)
output: ext/my_bindings.cpp
# Output file preamble (Optional)
preamble: |-
#include "bindgen_helper.hpp"
# Command to run after the generator. (Optional!)
# Will be executed as-written in the output directory.
# If the command signals failure, bindgen will halt too.
build: make
# Small-ish bindings may get away without a custom Makefile:
# build: "{CXX|c++} -std=c++11 -c -o binding.o -lMyLib my_bindings.cpp"
# Do you have complex dependencies? Use a conditional!
# if_os_is_windows: # Read the `YAML configuration` section in README.md
# build: mingw-make
# Crystal generator. Configuration style is exactly the same.
crystal:
# You'll most likely only need the `output` option.
output: src/my_lib/binding.cr
# This lets you find paths to your dependencies. If you don't need it, just
# omit it.
find_paths:
# The key is the environment variable a match will be put into. These are
# exposed to build-steps, so you can access them in e.g. a Makefile. You can
# also access these in all templated strings, just as if you set it right
# away.
# If an environment variable of this name is already set, and is not empty,
# the match will *not* run! This allows your users to supply a path easily
# to non-standard installations.
#
# The searches are run in the order they're defined. Thus, later searches
# have access to the result of previous searches by accessing the environment
# variable they assigned to.
#
# Attention when using conditionals: The conditionals are evaluated first,
# then these paths are found. This means that you can't check for a found
# path in a conditional!
#
# All regular expressions in this section are matche case-sensitive and are
# in multi-line mode (`^` will always match at the beginning of a line).
ENV_VAR_NAME:
# The "thing" you're looking for: A directory or a file.
# Defaults to `Directory`.
kind: Directory | File | Executable
# If finding this match is optional or not. If not found, it'll be not
# set.
# Defaults to `false`, making a match mandatory by default.
optional: true | false
# If no match was found, you can output a helpful message to the user.
# For example, a link to your wiki where you say what to install to make it
# work.
# If not found, and `optional:` is `true`, it'll still output the message,
# but will continue.
error_message: Please install MyLib: http://example.com/
# Accept multiple paths? If `true`, all matching paths will be combined
# into a list separated by a colon (`:`), or a semi-colon (`;`) on Windows.
# A list formatted like this can also be used as `search_path` in a later
# path search. If combined with a version check (See below), the list will
# be sorted from the best candidate first downwards.
# Defaults to `false` to only accept a single path.
list: true | false
# You can also configure how the multi-path combination should happen:
list:
# Element separator, added between elements. Think of `Array#join`.
# Defaults to the platforms default separator.
separator: " "
# Template for each element. `%` will be expanded to the current element. This option is mandatory.
template: "-L%"
# List of paths to try. These are tried in the order they appear in the
# list.
try:
# Strings indicate a normal path to try. These strings accept glob
# patterns, like `*` and `**`. `%` is expanded to the project root.
- /usr/include/mylib*
# Or you can call out to a tool which outputs the path. The command is
# expected to exit with a successful status code (`0`). The output to
# standard output (`STDOUT`) is captured, standard error is not changed
# and will be shown to the user.
# Commands have access to (previously set) environment variables. `%`
# will be expanded to the project root.
- shell: some-tool --some-arg
# The regular expression used to match the path. Uses the first capture
# group if one is used. Uses the whole match instead.
# An empty match is treated as no match.
# This is optional: If not given, the first line of output from the
# program is taken as-is, and tried as path.
regex: "^INCLUDE_DIR=([^ ]+)"
# By default, the `regex` is matched once. To match multiple times,
# set this to `true`. Also see the `list` option above!
multiple: true | false
# Optional: Search paths for relative try paths. Most useful to find
# executables. Entries are split on semi-colons (`;`) on Windows and
# colons (`:`) everywhere else.
# Entries also have access to environment variables.
# For `kind: Executable`, defaults to the `PATH` environment variable.
# Defaults to an empty list otherwise.
search_paths:
- "%" # Search relative to the project root.
# Do additional checks on the found paths. For a successful match, all
# checks have to pass. If no checks are required, omit this.
checks:
# Checks that the given sub-path exists. The `path:` is ignored if the
# expected `kind:` from above isn't `Directory`.
- path: relative/to/the/tested/path/my_lib_version.h
# The expected kind. Defaults to `File`. Ignored if the `kind:` above
# isn't `Directory`.
kind: Directory | File | Executable
# Optional: Makes sure that the given string exists in the file. Useful
# to do a quick version string check.
contains: '#define MYLIB_VERSION "1\.[123]"'
# Optional: If `true`, then the `contains` string is treated as regular
# expression. Defaults to `false`.
regex: true
# You can also call a program to check the path. `%` will expand to the
# tried path. If the programs exit code signals success (`0`), the path
# is used. The standard output (`STDOUT`) will be hidden, the standard
# error (`STDERR`) is shown to the user.
- shell: "some-tool %"
# You can also `OR` combine multiple checks. This checker matches if any
# one checker in it matches. Useful if your library renamed critical
# files in a newer version. You can use any checker in here:
- any_of:
- path: either_this.cpp
- path: or_this.cpp
# You can also do a version check, on the path itself, or using a command.
# `min` and `max` are optional. Omit them if you want an unbounded check.
# If you don't need a version check, omit this section.
version:
# Min version. The lowest, still accepted version string.
min: "4.0"
# Max version. The highest, still accepted version string.
max: "6.0"
# Optional: You can capture the version string of the selected candidate
# in a variable. If The selected candidate has an empty version string,
# the variable will be empty too. If used with the `list:` feature, only
# the version string of the best candidate (The first one in the list)
# will be captured.
# If no candidate was selected, this variable will not be set.
variable: ENV_VAR_NAME
# If figuring out the version number failed, should this be accepted
# anyway? Some systems don't use version strings in their executable
# names (Or not always), so this may help.
# `Fail` fails the check, `Accept` passes the check, and `Prefer` would
# not only pass, but also prefer the unversioned one over versioned
# candidates. Defaults to `Fail`.
fallback: Fail | Accept | Prefer
# Which version to prefer if faced with multiple valid candidates.
# Defaults to `Highest`.
prefer: Lowest | Highest
# Regular expression applied on the file path to grab the version
# string. Must have a capture group containing the name.
# Defaults to the Debian-style version suffix:
regex: "-([0-9.]+)$"
# Optional: A command to run to figure out the version. `%` expands to
# the currently tested executable. `regex:` will be applied on the
# output of the command. The command is expected to return
# successfully.
#
# WARNING: This calls random commands on the users system, so please use
# with caution!
command: "% --version"
# Map of classes to bind to. A class inheriting another class should follow
# *after* that base-class.
classes:
# Maps from the name of the C++ class, to the Crystal class.
CppClassName: CrystalClassName
MayBeEqual: MayBeEqual # This is fine, too.
# Map of enums to copy.
enums:
# Maps from the name of the C++ enum, to the Crystal enum.
# `CrystalEnumName` can reside in a wrapped class.
CppEnumName: Crystal::Enum::Name
# Or the full configuration:
CppEnumName:
# Destintation path of the enum. Can be in a class too.
destination: Crystal::Enum::Name
# Prefix removal: If `true`, the prefix is detected automatically. If a
# string, it's used as prefix. A prefix of a constant name is only removed
# if the given prefix matches the constants name. Else, it's left alone.
# Defaults to `false` for no prefix removal.
prefix: true | false | ThePrefixString_
# If to force a specific `@[Flags]` behaviour. If `true`, will force it to
# be a flags enum. `false` will force it to *not* be a flags enum.
# Omitting this option (Leaving it literally unset) will default to what the
# clang parser decided it to be.
# Flags detection is Qt specific: A enum is only then detected to be a flags
# enum, if it's used in a `QFlags<E>` template.
# Defaults to being unset.
flags: true | false | unset
# Map of macros (`#define`s) to copy. Requires the `macros` processor.
macros:
# Maps from a *regular expression*. Rules are tried in the order they're
# defined in the configuration file. The expression must match the whole name
# of the macro case-sensitively to be copied.
"FOO_BAR_(.*)":
# How to map matching macros: Either put all into an enum, or as constant.
map_as: Enum | Constant
# Only if mapping as enum: Treat as @[Flags] enum?
# Defaults to `false`.
flags: true | false
# If mapping as Enum, the type of the enumeration. Defaults to "int".
# If mapping as Constant, forces the type of all matched constants.
# Otherwise defaults to automatic type deduction, done per constant.
type: C++ type name
# How the enum constants, or constants, name should end up. Access to
# capture groups in the regular expression is done using `\\n` to access the
# n-th capture group. The name will be post-processed automatically.
#
# If left out, the first capture group will be used.
name: "\\1"
# Where to store the matching constants. For a enum, this is the path to
# the enum itself (So, including the enums name). For a constant, this is
# the path to the class (or module) it will be stored in.
destination: Foo::Bar
# Map functions outside of classes. Useful to map C functions and C++
# namespaced functions as well. Requires the `functions` (and `function_class`)
# processor.
functions:
# Matches all functions whose fully-qualified name matches the key.
# The qualified name of functions in the global scope is the function name
# itself: The qualified name of `void foo();` is `foo`. For C++ namespaced
# methods, the qualified name includes the complete namespace path: The
# qualified name of `namespace foo { void bar(); }` is thus `foo::bar`.
#
# Just like macros, the first capture group defaults to be the resulting
# function name. Without a capture group, the function name is copied.
"net_(.*)": Util::Net # Equal to: `"net_(.*)": { destination: "Util::Net" }`
# If you want more control:
"string_(.*)":
# Set a custom name for the function. You can access capture groups from
# the regular expression above. You can omit this option.
name: "string_\\1" # E.g., transform `strlen()` to `string_len()`
# Names also support further nesting, if you don't use `class:`:
# name: "\1::\2"
# Destination module or class the functions should be put into. If using
# `class:`, the name of the class itself.
destination: Util::StringBuffer
# Method names are always underscored: `setTheThing` will be rewritten to
# `set_the_thing`. You can also rewrite the names to be more Crystal-style:
# `setTheThing` would turn into `the_thing=`.
# The value defaults to `true` if `class:` is used. It is `false` otherwise.
crystalize_names: true | false
# You can also map all matched functions as class: With a little help,
# bindgen can generate full wrapper classes! If you don't want this,
# leave the whole `class:` option out.
# This feature requires the `function_class` processor.
class:
# Name of the backing structure. The non-static functions take a pointer
# to the structure as first argument. Other functions are treated as
# being static.
structure: string_buffer
# If this C library supports "inheritance", and you're also wrapping the
# base class, put the name here. Else, leave this out.
inherit_from: Crystal::Type::Name
# Name of constructor functions. They're expected to *return* a pointer
# to a new `structure:`.
constructors:
- string_new_empty
- string_new_from_string
# Name of the destructor (The "free" function). The generated wrapper
# will call this function in `#finalize`.
destructor: string_free
# List of container-types to wrap. (Keyword: C++ Templates)
# Requires the `instantiate_containers` processor. Optionally, you can also use
# the `auto_container_instantiation` processor before.
containers:
- class: Name of the C++ class
type: "Sequential" or "Associative"
# access_method: C++ item access method. Defaults to `at`.
# size_method: C++ container size method. Defaults to `size`.
# push_method: C++ item append method. Defaults to `push_back`.
instantiations: # All wanted instantiations of this container
# If using the `auto_container_instantiation` processor, this whole map
# can be omitted. It's still required to define the container classes.
- [ "C++ type name" ]
# - [ "..." ]
# Configuration for the C++ parser.
parser:
# List of files to include. Can be relative to search-paths.
# This is the only required option:
files:
- my_lib.h
# All of the following are optional:
#
# List of include search-paths. If omitted, only the systems default paths
# will be searched.
includes:
- %/ext/include # `%` expands to the absolute project root path.
# Path to the `bindgen-clang` binary.
binary: path/to/bindgen-clang
# Additional Clang flags. Defaults to C++11:
flags: [ "-x", "c++", "-std=c++11" ]
# Additional "#define"s passed to Clang. Defaults to the following:
defines:
- __STDC_CONSTANT_MACROS
- __STDC_LIMIT_MACROS
# Additional type configuration, of both explicitly wrapped types and all other
# found types. All fields are optional.
# Commonly referred to "type rules", or just "rules" in the source code.
#
# The matched type names (The mapping keys) are best-matched: You can have
# separate rules for type `T*` and `T`. If no matching rule is found, the match
# is retried after decaying the type: `const T*&` to `T*&` to `T**` to `T*` to
# `T`.
types:
FullCppTypeName: # Full name of the C++ Type (Like `std::string`)
# Ignore everything else in this map, and look-up the other type for rules.
alias_for: FullCppTypeName
# If all methods found using this type shall be ignored.
# Useful to quickly get started.
ignore: true | false
# Override the kind of this type. Changes passing-behaviour.
# Defaults to `Class`.
kind: Class | Struct | Value | Enum
# Name of this type in the wrapper.
crystal_type: CrystalTypeName
# Name of this type in the C++ binding. Useful when used with converters.
cpp_type: CppTypeName
# Name of this type in `lib Binding`.
binding_type: CrystalTypeName
# Inserted into C++ to turn the type into something the `binding_type` will
# be able to understand. Template value is the whole C++ call.
from_cpp: "convert_from_cpp(%)"
# Inserted into C++ to turn the `binding_type` into something C++ can
# understand. Template value is the C++ argument name.
to_cpp: "convert_to_cpp(%)"
# Crystal converter module used to turn the binding-type into a crystal-type
# and back.
#
# module TheConverter
# def wrap(value : CrystalType) : BindingType
# def unwrap(value : BindingType) : CrystalType
# end
converter: TheConverter
# Pendant to `to_cpp` in Crystal. `converter` takes precedence.
# Template value is the whole binding call.
to_crystal: "CrystalType.from_cpp(%)"
# Pendant to `from_cpp` in Crystal. `converter` takes precedence.
# Template value is the wrapper argument.
from_crystal: "%.to_cpp"
# Override of the pass-by semantics. Use with caution. Usually not
# required. Defaults to `Original`.
pass_by: Original | Reference | Pointer | Value
# Override of the pass-by semantics only in the user-facing wrapper code.
# Defaults to the value of `pass_by:` from above.
wrapper_pass_by: Original | Reference | Pointer | Value
# Enable or disable check if this type should be sub-classed to allow
# overriding virtual methods of the wrapped type in Crystal.
# If the type has no virtual methods, no sub-class will be generated.
# Defaults to `true`.
sub_class: true | false
# Copy the read structure fields over to Crystal. Useful for simple C-style
# structures. `struct` will end up in `Binding::BindingName`.
# Defaults to `false`.
copy_structure: true | false
# Treat this type as built-in type in C++ and Crystal.
# Defaults to `false`.
builtin: true | false
# Generate the user-facing wrapper class for this type.
# Defaults to `true`.
generate_wrapper: true | false
# Generate the `fun` bindings of all wrapped methods of this type.
# Defaults to `true`.
generate_binding: true | false
# List of methods to ignore in only this type when wrapping.
ignore_methods:
- some_method_name