This package provides a Julia language wrapper for libclang: the stable, C-exported interface to the LLVM Clang compiler. The libclang API documentation provides background on the functionality available through libclang, and thus through the Julia wrapper. The repository also hosts related tools built on top of libclang functionality.
Now, the package provides an out-of-box installation experience on Linux, macOS and Windows. You could simply install it by running:
pkg> add Clang
The package includes a generator to create Julia wrappers for C libraries from a collection of header files. The following declarations are currently supported:
- function: translated to Julia ccall(
va_list
and vararg argument are not supported) - struct: translated to Julia struct
- enum: translated to
CEnum
- union: translated to Julia struct
- typedef: translated to Julia typealias to underlying intrinsic type
- macro: limited support(see src/wrap_c.jl)
Here is a simple example:
using Clang
using Clang.LibClang.Clang_jll
# LIBCLANG_HEADERS are those headers to be wrapped.
const LIBCLANG_INCLUDE = joinpath(dirname(Clang_jll.libclang_path), "..", "include", "clang-c") |> normpath
const LIBCLANG_HEADERS = [joinpath(LIBCLANG_INCLUDE, header) for header in readdir(LIBCLANG_INCLUDE) if endswith(header, ".h")]
wc = init(; headers = LIBCLANG_HEADERS,
output_file = joinpath(@__DIR__, "libclang_api.jl"),
common_file = joinpath(@__DIR__, "libclang_common.jl"),
clang_includes = vcat(LIBCLANG_INCLUDE, CLANG_INCLUDE),
clang_args = ["-I", joinpath(LIBCLANG_INCLUDE, "..")],
header_wrapped = (root, current)->root == current,
header_library = x->"libclang",
clang_diagnostics = true,
)
run(wc)
Note that it might complain about missing some std headers, e.g. fatal error: 'time.h' file not found
,
which could be fixed by adding -Istdlib/include/on/your/specific/platform
to clang_args
, for example,
# on macOS
using Clang: find_std_headers
for header in find_std_headers()
push!(clang_args, "-I"*header)
end
If you miss those old behaviors before v0.8, please Pkg.pin
the package to v0.8 and
make the following change in your old generator script:
using Clang: CLANG_INCLUDE
using Clang.Deprecated.wrap_c
using Clang.Deprecated.cindex
A custom C-bindings generator tends to be used on large codebases, often with multiple API versions to support. Building a generator requires some customization effort, so for small libraries the initial investment may not pay off.
The above-mentioned C-bindings generator only exposes several entry points for customization.
In fact, it's actually not that hard to directly build your own C-bindings generator,
for example, the following script is used for generating LibClang
, you could refer to docs for
further details.
using Clang
using Clang.LibClang.Clang_jll
const LIBCLANG_INCLUDE = joinpath(dirname(Clang_jll.libclang_path), "..", "include", "clang-c") |> normpath
const LIBCLANG_HEADERS = [joinpath(LIBCLANG_INCLUDE, header) for header in readdir(LIBCLANG_INCLUDE) if endswith(header, ".h")]
# create a work context
ctx = DefaultContext()
# parse headers
parse_headers!(ctx, LIBCLANG_HEADERS,
args=["-I", joinpath(LIBCLANG_INCLUDE, "..")],
includes=vcat(LIBCLANG_INCLUDE, CLANG_INCLUDE),
)
# settings
ctx.libname = "libclang"
ctx.options["is_function_strictly_typed"] = false
ctx.options["is_struct_mutable"] = false
# write output
api_file = joinpath(@__DIR__, "libclang_api.jl")
api_stream = open(api_file, "w")
for trans_unit in ctx.trans_units
root_cursor = getcursor(trans_unit)
push!(ctx.cursor_stack, root_cursor)
header = spelling(root_cursor)
@info "wrapping header: $header ..."
# loop over all of the child cursors and wrap them, if appropriate.
ctx.children = children(root_cursor)
for (i, child) in enumerate(ctx.children)
child_name = name(child)
child_header = filename(child)
ctx.children_index = i
# choose which cursor to wrap
startswith(child_name, "__") && continue # skip compiler definitions
child_name in keys(ctx.common_buffer) && continue # already wrapped
child_header != header && continue # skip if cursor filename is not in the headers to be wrapped
wrap!(ctx, child)
end
@info "writing $(api_file)"
println(api_stream, "# Julia wrapper for header: $(basename(header))")
println(api_stream, "# Automatically generated using Clang.jl\n")
print_buffer(api_stream, ctx.api_buffer)
empty!(ctx.api_buffer) # clean up api_buffer for the next header
end
close(api_stream)
# write "common" definitions: types, typealiases, etc.
common_file = joinpath(@__DIR__, "libclang_common.jl")
open(common_file, "w") do f
println(f, "# Automatically generated using Clang.jl\n")
print_buffer(f, dump_to_buffer(ctx.common_buffer))
end
# uncomment the following code to generate dependency and template files
# copydeps(dirname(api_file))
# print_template(joinpath(dirname(api_file), "LibTemplate.jl"))
LibClang is a thin wrapper over libclang. It's one-to-one mapped to the libclang APIs.
By using Clang.LibClang
, all of the CX
/clang_
-prefixed libclang APIs are imported into the
current namespace, with which you could build up your own tools from the scratch. If you are
unfamiliar with the Clang AST, a good starting point is the Introduction to the Clang AST.