Automatically generate Julia bindings to C API's! We are developing CBindingGen.jl and CBinding.jl to support the use of arbitrary local C libraries, such as those provided by your Linux distribution, from Julia.
CBindingGen.jl seeks to be a comprehensive and automatic C bindings generation framework. The bindings utilize the CBinding.jl capabilities to precisely interface Julia with C.
This package should only be used at package build time when you wish to generate bindings to a particular C library on the system or one built and installed at build time. The generated bindings file can then be included from your package code. Bindings files created by this package should not be committed with your package and they are not meant for editing by lowly humans once generated. Se let's get started with an example!
To start, you must add
CBinding = "^0.9" as a dependency to your package, and
CBindingGen = "^0.3" as a build dependency.
CBindingGen.jl relies on the artifacts distributed with
LLVM_jll for providing a
libclang.so library and header files for your system, so we will use those to demonstrate.
The following code shows what is necessary to generate bindings to
libclang.so, and something like it would normally be placed in your package's
(another example found in PLCTag.jl)
using CBindingGen import LLVM_jll incdir = joinpath(dirname(dirname(LLVM_jll.libclang_path)), "include") hdrs = map(hdr -> joinpath("clang-c", hdr), readdir(joinpath(incdir, "clang-c"))) cvts = convert_headers(hdrs, args = ["-I", incdir]) do cursor header = CodeLocation(cursor).file name = string(cursor) # only wrap the libclang headers startswith(header, "$(incdir)/") || return false # ignore function that uses time_t since we don't know what time_t is yet name == "clang_getFileTime" && return false return true end open("bindings.jl", "w+") do io generate(io, LLVM_jll.libclang_path => cvts) end
convert_headers function takes an array of header files and the command line arguments,
Any include directories, compiler options, or preprocessor definitions would be provided in
args in the same way they would be used in your
clang command line.
An important detail of
convert_headers is the filter function provided, here provided with the
The filter function allows you fine-grained control over what is converted to Julia as the C AST is traversed.
In our example, we filter out any C constructs not defined within the header files we are interested in.
CodeLocation(cursor) to get the
col for the start of the C expression, while
CodeRange(cursor) can be used to get the
stop locations of the expression.
string(cursor) will get the "spelling" of the expression if you wish to filter particular C symbols.
The result of
convert_headers is an array of
Converted objects contain the Julia expression strings, as
comments for storing exportable symbols an their comments ported from C.
generate function is used to write the converted expressions for one or more libraries into a bindings file.
In order to load the bindings file within your package, it is best to define a
baremodule within your package module to encapsulate the bindings.
The namespace within the
baremodule will have only a very few symbols that could conflict with those from C.
\bfj<tab>\bfl<tab>) to provide access to the CBinding types and macros without increasing the chance of naming conflicts.
(another example found in PLCTag.jl)
module MyModule baremodule LibClang using CBinding: 𝐣𝐥 const size_t = 𝐣𝐥.Csize_t 𝐣𝐥.Base.include((𝐣𝐥.@__MODULE__), "pre-bindings.jl")) # <-handwritten 𝐣𝐥.Base.include((𝐣𝐥.@__MODULE__), 𝐣𝐥.joinpath(𝐣𝐥.dirname(𝐣𝐥.@__DIR__), "deps", "libclang.jl")) # <-generated 𝐣𝐥.Base.include((𝐣𝐥.@__MODULE__), "post-bindings.jl")) # <-handwritten end # other module code, such as high-level Julian code wrapping the bindings... end
Next is a section defining dependencies of the bindings and should be composed of hand-written code or imported packages that export the required symbols. Finishing the bindings module is the inclusion of the bindings file generated at build-time.
CBindingGen.jl automatically imports comments from the C header files into Julia's
@doc string syntax.
If you find that C header comments are not imported, you should try adding
-fparse-all-comments to the list of
args in your call to
julia> import MyModule help?> MyModule.LibClang.clang_getClangVersion 𝐣𝐥.@cextern clang_getClangVersion()::CXString Return a version string, suitable for showing to a user, but not intended to be parsed (the format is not guaranteed to be stable). Reference =========== Index.h:5482 (./include/clang-c/Index.h:5482:25)
Use the generated bindings as you would any hand-written or generated
Remember, this is very low-level interfacing, and segmentation faults can result from misuse.
julia> cxstr = MyModule.LibClang.clang_getClangVersion(); julia> unsafe_string(MyModule.LibClang.clang_getCString(cxstr)) "clang version 8.0.1 " julia> MyModule.LibClang.clang_disposeString(cxstr)