include

| | |

Goal

To directly #include C and C++ headers in (D)[https://dlang.org] files and have the same semantics and ease-of-use as if the file had been #included from C or C++ themselves. Warts and all, meaning that C enum declarations will pollute the global namespace, just as it does "back home".

Limitations

It currently only supports C headers, but C++ is planned, templates and all. See also "Translation Notes" below.
Packed structs are not supported yet.
C99 bitfields are not supported yet.

This is alpha sofware. It has however produced programs that compile that #included several "real-life" C headers:

nanomsg/nn.h, nanomsg/pubsub.h
curl/curl.h
stdio.h, stdlib.h
pthread.h
xlsxwriter.h
libvirt/libvirt.h, libvirt/virterror.h
libzfs
openssl/ssl.h
imapfilter.h
libetpan/libetpan.h

Compilation however doesn't guarantee they work as expected and YMMV. Please consult the examples.

Details

include is an executable that has as input a D file with C #include preprocessor directives and outputs a valid D file that can be compiled. The original can't be compiled since D has no integrated preprocessor.

The only supported preprocessor directive is #include.

The input file may also use C preprocessor macros defined in the file(s) it q#includes, just as a C/C++ program would. It may not, however, define macros of its own.

include goes through the input file line-by-line, and upon encountering an #include directive, parses the file to be included with libclang, loops over the definitions of data structures and functions therein and expands in-place the relevant D translations. e.g. if a header contains:

uint16_t foo(uin32_t a);

The output file will contain:

ushort foo(ushort a);

include will also enclose each one of these original #include directives with either extern(C) {} or extern(C++) {} depending on the header file name and/or command-line options.

As part of expanding the #include, and as well as translating declarations, include will also insert text to define macros originally defined in the #included translation unit so that these macros can be used by the D program. The reason for this is that nearly every non-trivial C API requires the preprocessor to use properly. It is possible to mimic this usage in D with enums and CTFE, but the result is not guaranteed to be the same. The only way to use a C or C++ API as it was intended is by leveraging the preprocessor.

As a final pass before writing the output file, include will run the C preprocessor on the intermediary result of expanding all the #include directives so that any used macros are expanded, and the result is a D file that can "natively" call into a C/C++ API by #includeing the appropriate header(s).

Example

// foo.h
#ifndef FOO_H
#define FOO_H

#define FOO_ID(x) (x*3)

int twice(int i);

#endif

// foo.dpp
#include "foo.h"
void main() {
    import std.stdio;
    writeln(twice(FOO_ID(5)));
}

At the shell:

$ ./include foo.dpp foo.d
$ dmd foo.d
$ ./foo
$ 30

Translation notes

Names of structs, enums and unions

C has a different namespace for the aforementioned user-defined types. As such, this is legal C:

struct foo { int i; };
extern int foo;

To accomodate for this, the translation generated by include is:

struct struct_foo { int i; };
extern __gshared int foo;

Changing the variable name would cause linker errors. struct_foo is close to C's struct foo (and similary for enum and union) and since most C structs have a typedef anyway, it shouldn't impact user code too much.

enum

For convenience, this declaration:

enum Enum { foo, bar, baz}

Will generate this translation:

enum { foo, bar, baz}
enum Enum { foo, bar, baz}

This is to mimic C semantics with regards to the global namespace whilst also allowing one to, say, reflect on the enum type.

Function parameters declared as an enum in C will also be an enum in D, i.e. it won't accept an int as C would, so:

void func(Enum e);
func(foo);

becomes:

void func(enum_Enum e);
// func(foo); // won't compile, func takes enum_Enum, not int
func(enum_Enum.foo);

Functions with a name that is a D keyword

Those get an underscore appended and a pragma(mangle) added so they link:

void debug(const char* msg);

Becomes:

pragma(mangle, "debug")
void debug_(const(char)*);

JonathanGerlach/include