Package: cl-bindgen
cl-bindgenA command line tool and library for creating Common Lisp language bindings
from C header files.Features:Generates CFFI bindings for function declarations, enums, variables, unions,
and structures.Handles nested and anonymous structures, unions, and enums.Warns when it cannot produce a correct binding.Documentation comments from the C source files are lispified and
included with the generated bindings when available.Provides a powerful way to customize how names are translated into
lisp symbols.Installationcl-bindgen requireslibclang, which is not installed with the other Python
dependencies and not available on PyPi. It is recommended to install it first before installing
cl-bindgen. Use your distribution's package manager to install it.Oncelibclangis installed, you can then installcl-bindgenfrom
source or from PyPI.From PyPI:pipinstallcl-bindgenFrom source:gitclone--depth=1https://github.com/sdilts/cl-bindgencdcl-bindgen
pipinstall--user.Processing individual filesTo process individual files, use thefcommand and specify one or
more files to process. By default, output will be printed to
stdout, but the output file can be specified with the-ooption. To see
a full list of options, runcl-bindgen f -h.# Process test.h and print the results to stdout:cl-bindgenftest.h# Process the files test1.h, test2.h, and place the output in output.lisp:cl-bindgenf-ooutput.lisptest1.htest2.hBatch file processingcl-bindgen can use a yaml file to process many header
files with a single invocation. Use thebcommand
to specify one or more batch files to process:cl-bindgenbmy_library.yamlBatch file formatBatch files use the YAML format. Multiple documents can be contained in each input file.Required Fields:output: where to place the generated codefiles: a list of files to processOptional Fields:package: The name of the Common Lisp package of the generated filearguments: Arguments to pass to clangforce: Ignore errors while parsing. Valid values areTrueorFalsepkg-config: A list of package names needed by the library. Adds
the flags needed to compile the given header files as told bypkg-config --cflagspointer_expansion(experimental): Used to provide either a regex
or a list of pointer types to expand or not expand in the output.To see example batch files, look in theexamplesdirectory.Handling Include Directories and Clang ArgumentsIf you need to specify additional command line arguments to the clang
processor, you can use the-aoption, and list any clang arguments after.cl-bindgenbbatch_file.yaml-a-Iinclude_dir1-Iinclude_dir2# Use -- to stop collecting clang arguments:# Note that instead of directly calling pkg-config when using a batch# file, you can use the pkg-config option instead.cl-bindgenf-a`pkg-config--cflagsmylibrary`--header.hIf a header file isn't found while processing the input files,
cl-bindgen will halt and produce no output. This is to avoid producing
incorrect bindings: while bindings can still be produced when header
files are missing, they are likely to be incorrect. To ignore missing
header files and other fatal errors, the-fflag can be used:cl-bindgenb-fbatch_file.yaml
cl-bindgenf-fheader.cCustomizing the behavior of cl-bindgencl-bindgen attempts to provide a reasonable interface that is usable
in most cases. However, if you need to customize how C names are
converted into lisp names or embed cl-bindgen into another
application, cl-bindgen is available as a library.Thecl_bindgenpackage is broken up into modules: theprocessfile,mangler,utilandmacro_utilmodules. Theprocessfilemodule provides the
functions to generate the lisp bindings, themanglermodule provides
functions to convert C names into lisp names, and theutilmodule
provides functions to use batch files and cl-bingen's command line
interface.TheprocessfileModuleThis module exports two functions:process_fileandprocess_files,
which work on a single header file or many, respectively. Both
functions take two arguments: the file(s) to be processed and anProcessOptionsobject.TheProcessOptionsclass is the way to specify how the
processing functions generate their output. It has the following
fields:typedef_mangers,enum_manglers,type_manglers,name_manglersandconstant_manglers: See themangler module sectionfor what these do.output: The path of the file where the output is
placed.":stdout"or":stderr"can be specified to use standard
out or standard error.package: If notNone, this specifies the package the the
generated output should be placed in.arguments: The command line arguments that should be given to the
clang processor.force: If true, then ignore errors while parsing the input files.macro_detector: Themacro detctor functionused to detect header macrosexpand_pointer_p: A function that takes a typename and returns
whether or not pointers of this type should be fully expanded or
left as:pointer.ThemanglerModulecl-bindgen uses a set of classes called manglers to translate C
names so that they follow lisp naming conventions. Each mangler class
provides one or more transformations to a symbol. For example, theUnderscoreManglerclass converts underscores (_) into dashes
(-). A series of manglers are applied to each C name to make it
follow lisp naming conventions.To maximize customization, a list of manglers is associated with each
type of name that can be converted. enums, variable names, typedefs,
constants, and record types all use a different set of manglers.Built-in manglers:UnderscoreMangler: Converts underscores to dashes.ConstantMangler: Converts a string to follow Common Lisp's constant style
recomendation.KeywordMangler: Adds a:to the beginning of a string to make it a symbol.
Doesn't perform any action if the string has a package prefix.RegexSubMangler: Substitutes the substring matched by a regex with the given string.Mangler InterfaceMangler classes follow a simple interface:can_mangle(string): returns true if the mangler can perform its
operations on the given stringmangle(string): returns a string with the desired transformations
applied.TheutilModuleTheutilmodule provides two functions:process_batch_fileanddispatch_from_arguments.process_batch_file(batch_file, options): Processes the given
batch file usingoptionsas the default options.dispatch_from_arguments(arguments, options): Uses the provided
command line arguments to perform the actions of cl-bindgen usingoptionsas the default options.Themacro_utilModuleThis module provides themacro_matches_file_pathfunction that is used
by default to check if a macro is a header guard, and theconvert_literal_tokenthat converts literal tokens into CL literals.Themacro_matches_file_pathis a macro detector function. Macro
detector functions are used to determine if a C macro is a header
guard. They take two arguments: the location of the file and the name
of the file as a string.ExamplesThe best example of how to use cl-bindgen as a library is to look at its main
function found incl_bindgen/__main__.py.
In it, cl-bindgen's default options are set, then passed todispatch_from_argumentsto run the utility.