Repository files navigation

Features of this package are now available ashttps://github.com/analytech-solutions/CBinding.jl

Use C.jl to automatically create C library bindings with Julia at runtime!

Package C support features:

• fully supports C'sstruct,union, andenum types
• alignment strategies
• bit fields
• nested types
• anonymous types
• type qualifiers
• variadic functions
• unknown-length arrays
• inline functions (todo)
• typed function pointers
• function calling conventions
• automatic callback function pointers
• documentation generation
• macros (work-in-progress)
• fully supports insane C (i.e.extern struct { int i; } g[2], func();)

Read on to learn how to automatically create C library bindings, orlearn how to use the generated bindings.

First, set up a compiler context to collect C expressions (at the module scope, or at the REPL).

julia>using Cjulia>c``

Notice thatc`...` is a command macro (with the backticks) and is the means of specifying command line arguments to the Clang parser.Each time such a command macro is used, a new compiler context is started for the module creating it.A more real-life example might look like:

julia> libpath=find_libpath();julia>c`-std=c99 -Wall -DGO_FAST=1 -Imylib/include -L$(libpath) -lmylib`

The compiler context also finds the paths of all specified libraries so it can use them in any bindings that are created.

Next thec"..." string macro can be used to input C code and automatically create the equivalent Julia types, global variable bindings, and function bindings.It is often the case that the C code will span multiple lines, so the triple-quoted variant (c"""...""") is most effective for this usage.

julia>c"""         struct S;         struct T {           int i;           struct S *s;           struct T *t;         };         extern void func(struct S *s, struct T t);""";

That's it...That's all that is needed to create a couple C types and a function binding in Julia, but actually, it gets even easier!

C API's usually come with header files, so let's just use those to create the Julia bindings and save some effort.By default, bindings are generated from the code directly written in C string macros and header files explicitly included in them, but not headers included by those headers.See thei string macro option) to allow parsing certain implicitly included headers as well.

julia>c"""         #include <mylib/header.h>""";

• all C types are defined in Julia
• C function and global variable bindings defined
• the C API is documented and exported by the enclosing module

All done in just a few lines of code!Take a look at the complete example below or continue reading to learn about some more details.

The C expressions are parsed and immediately converted to Julia code.In fact, the generated Julia code can be inspected using@macroexpand, like this:

julia>@macroexpandc"""         struct S;         struct T {           int i;           struct S *s;           struct T *t;         };         extern void func(struct S *s, struct T t);"""⋮YIKES!⋮

In order to support the fully automatic conversion and avoid name collisions, the names of C types or functions are mangled a bit to work in Julia.Therefore everything generated by C.jl can be accessed with thec"..." string macro (more about this below) to indicate that it lives in C-land.As an example, the functionfunc above is available in Julia asc"func".It is possible to store the generated bindings to more user-friendly names (this can sometimes be automated,see thej option).Placing each C declaration in its own macro helps when doing this manually, like:

julia>const S=c"""         struct S;""";julia>const T=c"""         struct T {           int i;           struct S *s;           struct T *t;         };""";julia>c"""         extern void func(struct S *s, struct T t);"""j;

Constructs from the standard C library headers are currently not being emitted by C.jl, but other packages may be developed to provide a unified source for them.For now, dependencies on C library or other libraries should be placed before any C code blocks referencing them.Most often it is only a fewusing andconst statements.

Finally, an example of what a package using C.jl might look like:

module LibFoomodule libfooimport Foo_jllusing C# libfoo has libbar as a dep, and LibBar has bindings for itusing LibBar: libbar# set up the parserlet      incdir=joinpath(dirname(dirname(Foo_jll.libfoo_path)),"include")      libdir=dirname(Foo_jll.libfoo_path)c`-std=c99 -fparse-all-comments -I$(incdir) -L$(libdir) -lfoo`end# libfoo refers to some std C sized types (eventually made available with something like `using C99`)constc"int32_t"= Int32constc"int64_t"= Int64constc"uint32_t"= UInt32constc"uint64_t"= UInt64# generate bindings for libfooc"""      #include <libfoo/header-1.h>      #include <libfoo/header-2.h>"""# any other bindings not in headersc"""      struct FooStruct {        struct BarStruct bs;      };      extern struct FooStruct *foo_like_its_the_80s(int i);"""end# high-level Julian interface to libfoousing Cusing.libfoofunctionfoo(i)    ptr=c"foo_like_its_the_80s"(Cint(i-1))tryreturnJulianFoo(ptr[])finally      Libc.free(ptr)endendend

The string macro has some options to handle more complex use cases.Occasionally it is necessary to include or define C code that is just a dependency and should not be exported or perhaps excluded from the generated bindings altogether.These kinds of situations can be handled with combinations of the following string macro suffixes.

• i - also parse implicitly included headers that are related (in the same directory or subdirectories of it) to explicitly included headers
• j - also define bindings with Julian names (name collisions likely)
• p - mark the C code as "private" content that will not be exported
• q - quietly parse the block of C code, suppressing any compiler messages
• r - the C code is only a reference to something in C-land and bindings are not to be generated
• s - skip creating bindings for this block of C code
• u - leave this block of C code undocumented

julia>c"""         #include <stdio.h>  // provides FILE type, but skip emitting bindings for this block"""s;julia>c"""         struct File {  // do not include this type in module exports, and suppress compiler messages          FILE *f;         };"""pq;

Thec"..." string macro can be used to refer to any of the types, global variables, or functions generated by C.jl.When simply referencing the C content, setting up a compiler context (i.e. usingc`...`) is not necessary.

Thec"..." string macro can take on two meanings depending on the content placed in it.So to guarantee it is interpreted as a reference to something in C, rather than a block of C code to create bindings with, include anr in the string macro options.

julia>module MyLib# generally some C bindings are defined elsewhereusing Cc`-std=c99 -Wall -Imy/include`c"""           struct S;           struct T {             int i;             struct S *s;             struct T *t;           };           extern void func(struct S *s, struct T t);"""endjulia>using C,.MyLibjulia>c"struct T"<:Cstructtruejulia>c"struct T"r<:Cstruct# use 'r' option to guarantee it is treated as a referencetruejulia> t=c"struct T"(i=123);julia> t.i123

The user-defined types (enum,struct, andunion) are referenced just as they are in C (e.g.c"enum E",c"struct S", andc"union U").All other types, pointers, arrays, global variables, enumeration constants, functions, etc. are also referenced just as they are in C.Here is a quick reference for C string macro usage:

• c"int" - theCint type
• c"int[2]" - a length-2 static arrayCint's
• c"int[2][4]" - a length-2 static array of length-4 static arrays ofCint's
• c"int *" - pointer to aCint
• c"int **" - pointer to a pointer to aCint
• c"int const **" - pointer to a pointer to a read-onlyCint
• c"enum MyUnion" - a user-defined Cenum type
• c"union MyUnion" - a user-defined Cunion type
• c"struct MyStruct" - a user-defined Cstruct type
• c"struct MyStruct *" - a pointer to a user-defined Cstruct type
• c"struct MyStruct [2]" - a length-2 static array of user-defined Cstruct type
• c"MyStruct" - a user-definedtypedef-ed type
• c"MyStruct *" - a pointer to a user-definedtypedef-ed type
• c"printf" - the printf function
• c"int (*)(int, int)" - a function pointer
• c"int (*)(char const *, ...)" - a variadic function pointer

The following examples demonstrate how to refer to C-land content that resides in other modules and is not exported/imported:

• c"SomeModule.SubModule.enum MyUnion"
• c"SomeModule.SubModule.struct MyStruct *"
• c"SomeModule.SubModule.printf"
• c"int (*)(Some.Other.Module.struct MyStruct *, ...)"

The C string macro can also be used to expose Julia content to C-land.

julia>constc"IntPtr"= Cptr{Cint};julia>c"void (*)(IntPtr, IntPtr *, IntPtr[2])"<:Cptr{<:Cfunction}true

Type qualifiers are carried over from the C code.As an example,int const * is a pointer to a read-only integer in is represented by C.jl as the typeCptr{Cconst{Cint}}.Theunqualifiedtype(T) can be used to strip away the type qualifiers to get to the core type, sounqualifiedtype(Cconst{Cint}) === Cint.

As mentioned above, thebitstype(T) function can be used to acquire the concrete bits type of user-defined C types as well.

User-defined aggregate types (struct andunion) have several ways to be constructed.

• t = c"struct T"() - zero-ed immutable object
• t = c"struct T"(i = 123) - zero-ed immutable object with fieldi initialized to 123
• t = c"struct T"(t, i = 321) - copy oft with fieldi initialized to 321

These types are immutable structs and changing fields will have no effect.Nested calls are also possible, and performance should match that of accessing fields within standard Julia immutable structs.

julia>c`` ;c"""         struct A {           struct {             int i;           };           struct {             struct {               int i;             } c;           } b;         };""";julia> a=c"struct A"()julia> a.i0julia> a.b.c.i0julia> a=c"struct A"(i=123, b= (c= (i=321,),))julia> a.i123julia> a.b.c.i321

C.jl also works elegantly with pointers to aggregate types.Pointers are followed through fields and array elements as they are accessed, and they can be dereferenced withptr[] or written to withptr[] = val.

julia> ptr= Libc.malloc(a);# allocate a `struct A` as a copy of `a`julia> ptr.iCptr{Int32}(0x0000000003458810)julia> ptr.i[]123julia> ptr.b.c.iCptr{Int32}(0x0000000003458814)julia> ptr.b.c.i[]321julia> ptr.b.c.i[]=4242julia> Libc.free(ptr)# deallocate it

An exception to the rule is bitfields.It is not possible to refer to bitfields with a pointer, so access to bitfields is automatically dereferenced.

Included with C.jl is a static array type which works as one expects.However, when using a subscript with a pointer to an array, a properly typed pointer to the element specified is returned and must be dereferenced.

julia>c"""         typedef struct {           int i;         } IntArray[4];""";julia> ptr= Libc.malloc(c"IntArray");julia> ptr[4].iCptr{Int32}(0x00000000023d8194)julia> ptr[4].i[]=123123julia> Libc.free(ptr)# deallocate it

Bindings to global variables also behave as if they are pointers, and must be dereferenced to be read or written, but any fields and elements can be followed through with pointers.Bindings to functions are direct, but getting the pointer to a bound function can be done with thefunc[] syntax.

julia>c"func"(Cint(1),Cint(2));# call the C function directlyjulia> funcptr=c"func"[]Cptr{Cfunction{Int32, Tuple{Int32, Int32}, :cdecl}}(0x00007f8f50722b10)julia>funcptr(Cint(1),Cint(2));# call the C function pointer

Providing a Julia method to C as a callback function has never been easier!Just pass it as an argument to the C.jl function binding or function pointer.Assuming a binding to a C function, likevoid set_callback(int (*cb)(int, int)) exists:

julia>functionmyadd(a, b)# a callback function to give to Creturn a+bend;julia>c"set_callback"(myadd)# that's it!julia>functionsaferadd(a::Cint, b::Cint)::Cint# a safer callback function might require type paranoiareturn a+bend;julia>c"set_callback"(saferadd)

Inline functions and macros are not yet implemented, but they will be added in future releases.

Since Julia does not yet provideincomplete type (please voice your support of the feature here:JuliaLang/julia#269), abstract types are used to allow forward declarations in C.Therefore, referencing C types usually refers to the abstract type which can have significant implications when creating Julia arrays, usingccall, etc.The following example illustrates this kind of unexpected behavior:

julia>struct X         i::Cintendjulia>const Y=c"""         struct Y {           int i;         };"""julia> [X(123)]isa Vector{X}truejulia> [Y(i=123)]isa Vector{Y}falsejulia> [Y(i=123)]isa Vector{bitstype(Y)}true

Thebitstype(T) function can be used to acquire the concrete bits type of any C type when the distinction matters.

Another implementation detail worth noting is that function bindings are brought into Julia as singleton constants, not as actual functions.This approach allows a user to obtain function pointers from C functions in case one must be used as a callback function.Therefore, attaching other methods to a bound C function is not possible.

It is also sometimes necessary to use thec"..." mangled names directly in Julia (for instance in the REPL help mode).Until consistent, universal support for the string macro is available, the mangled names can be used directly asvar"c\"...\"", likehelp?> var"c\"struct Y\"".