View source for D binding for C

While D cannot directly compile C source code, it can easily interface to C code, be linked with C object files, and call C functions in DLLs. The interface to C code is normally found in C '''.h''' files. So, the trick to connecting with C code is in converting C .h files to D modules. This turns out to be difficult to do mechanically since inevitably some human judgement must be applied. This is a guide to doing such conversions.

== Preprocessor ==
'''.h''' files can sometimes be a bewildering morass of layers of macros, '''#include''' files, '''#ifdef''''s, etc. D doesn't include a text preprocessor like the C preprocessor, so the first step is to remove the need for it by taking the preprocessed output. For DMC (the Digital Mars C/C++ compiler), the command:

<syntaxhighlight lang="bash">
dmc -c program.h -e -l
</syntaxhighlight>

will create a file '''program.lst''' which is the source file after all text preprocessing.

Remove all the '''#if''', '''#ifdef''', '''#include''', etc. statements.

== Linkage ==
Generally, surround the entire module with:

<syntaxhighlight lang="D">
extern (C)
{
     /* ...file contents... */
}
</syntaxhighlight>

to give it C linkage.

== Types ==

A little global search and replace will take care of renaming the C types to D types. The following tables show typical mappings for 32 bit and 64 bit C code.
Note that there is a difference between them according to the type long. For convencience D offers the type alias '''core.stdc.config.c_ulong''' and '''core.stdc.config.c_long'''.

For 32 bit systems:

{| class="wikitable"
|+Mapping C type to D type 
!C type 	
!D type
|-
|long double 	
|real
|-
|unsigned long long 	
|ulong
|-
|long long 	
|long
|-
|unsigned long 	
|uint
|-
|long 	
|int
|-
|unsigned 	
|uint
|-
|unsigned short 	
|ushort
|-
|signed char 	
|byte
|-
|unsigned char 	
|ubyte
|-
|wchar_t 	
|wchar or dchar
|-
|bool 	
|bool, byte, int
|-
|size_t 	
|size_t
|-
|ptrdiff_t 	
|ptrdiff_t 

|}

For 64 bit systems:

{| class="wikitable"
|+Mapping C type to D type 
!C type 	
!D type
|-
|long double 	
|real
|-
|unsigned long long 	
|ulong
|-
|long long 	
|long
|-
|unsigned long 	
|ulong
|-
|long 	
|long
|-
|unsigned 	
|uint
|-
|unsigned short 	
|ushort
|-
|signed char 	
|byte
|-
|unsigned char 	
|ubyte
|-
|wchar_t 	
|wchar or dchar
|-
|bool 	
|bool, byte, int
|-
|size_t 	
|size_t
|-
|ptrdiff_t 	
|ptrdiff_t 

|}

== NULL ==
'''NULL''' and '''((void*)0)''' should be replaced with '''null'''.
Numeric Literals
Any ‘L’ or ‘l’ numeric literal suffixes should be removed, as a C '''long''' is (usually) the same size as a D '''int'''. Similarly, ‘LL’ suffixes should be replaced with a single ‘L’. Any ‘u’ suffix will work the same in D.

== String Literals == 
In most cases, any ‘L’ prefix to a string can just be dropped, as D will implicitly convert strings to wide characters if necessary. However, one can also replace:

<syntaxhighlight lang="C">
L"string"
</syntaxhighlight>

with:

<syntaxhighlight lang="D">
"string"w	// for 16 bit wide characters
"string"d	// for 32 bit wide characters
</syntaxhighlight>

== Macros ==
Lists of macros like:

<syntaxhighlight lang="C">
#define FOO	1
#define BAR	2
#define ABC	3
#define DEF	40
</syntaxhighlight>

can be replaced with:

<syntaxhighlight lang="D">
enum
{   FOO = 1,
    BAR = 2,
    ABC = 3,
    DEF = 40
}
</syntaxhighlight>

or with:

<syntaxhighlight lang="D">
const int FOO = 1;
const int BAR = 2;
const int ABC = 3;
const int DEF = 40;
</syntaxhighlight>

Function style macros, such as:

<syntaxhighlight lang="C">
#define MAX(a,b) ((a) < (b) ? (b) : (a))
</syntaxhighlight>

can be replaced with functions:

<syntaxhighlight lang="D">
int MAX(int a, int b) { return (a < b) ? b : a; }
</syntaxhighlight>

The functions, however, won't work if they appear inside static initializers that must be evaluated at compile time rather than runtime. To do it at compile time, a template can be used:

<syntaxhighlight lang="C">
#define GT_DEPTH_SHIFT  (0)
#define GT_SIZE_SHIFT   (8)
#define GT_SCHEME_SHIFT (24)
#define GT_DEPTH_MASK   (0xffU << GT_DEPTH_SHIFT)
#define GT_TEXT         ((0x01) << GT_SCHEME_SHIFT)

/* Macro that constructs a graphtype */
#define GT_CONSTRUCT(depth,scheme,size) \
	((depth) | (scheme) | ((size) << GT_SIZE_SHIFT))

/* Common graphtypes */
#define GT_TEXT16  GT_CONSTRUCT(4, GT_TEXT, 16)
</syntaxhighlight>

The corresponding D version would be:

<syntaxhighlight lang="D">
const uint GT_DEPTH_SHIFT  = 0;
const uint GT_SIZE_SHIFT   = 8;
const uint GT_SCHEME_SHIFT = 24;
const uint GT_DEPTH_MASK   = 0xffU << GT_DEPTH_SHIFT;
const uint GT_TEXT         = 0x01 << GT_SCHEME_SHIFT;

// Template that constructs a graphtype
template GT_CONSTRUCT(uint depth, uint scheme, uint size)
{
 // notice the name of the const is the same as that of the template
 const uint GT_CONSTRUCT = (depth | scheme | (size << GT_SIZE_SHIFT));
}

// Common graphtypes
const uint GT_TEXT16 = GT_CONSTRUCT!(4, GT_TEXT, 16);
</syntaxhighlight>

== Declaration Lists ==
D doesn't allow declaration lists to change the type. Hence:

<syntaxhighlight lang="C">
int *p, q, t[3], *s;
</syntaxhighlight>

should be written as:

<syntaxhighlight lang="D">
int* p, s;
int q;
int[3] t;
</syntaxhighlight>

== Void Parameter Lists ==
Functions that take no parameters:

<syntaxhighlight lang="C">
int foo(void);
</syntaxhighlight>

are in D:

<syntaxhighlight lang="D">
int foo();
</syntaxhighlight>

== Extern Global C Variables ==
Whenever a global variable is declared in D, it is also defined. But if it's also defined by the C object file being linked in, there will be a multiple definition error. To fix this problem, use the extern storage class. For example, given a C header file named foo.h:

<syntaxhighlight lang="C">
struct Foo { };
struct Foo bar;
</syntaxhighlight>

It can be replaced with the D modules, foo.d:

<syntaxhighlight lang="D">
struct Foo { }
extern (C)
{
    extern Foo bar;
}
</syntaxhighlight>

== Typedef ==
alias is the D equivalent to the C typedef:

<syntaxhighlight lang="C">
typedef int foo;
</syntaxhighlight>

becomes:

<syntaxhighlight lang="D">
alias foo = int;
</syntaxhighlight>

== Structs ==
Replace declarations like:

<syntaxhighlight lang="C">
typedef struct Foo
{   int a;
    int b;
} Foo, *pFoo, *lpFoo;
</syntaxhighlight>

with:

<syntaxhighlight lang="D">
struct Foo
{   int a;
    int b;
}
alias pFoo  = Foo*;
alias lpFoo = Foo*;
</syntaxhighlight>

== Struct Member Alignment ==
A good D implementation by default will align struct members the same way as the C compiler it was designed to work with. But if the .h file has some #pragma's to control alignment, they can be duplicated with the D align attribute:

<syntaxhighlight lang="C">
#pragma pack(1)
struct Foo
{
    int a;
    int b;
};
#pragma pack()
</syntaxhighlight>

becomes:

<syntaxhighlight lang="D">
struct Foo
{
  align (1):
    int a;
    int b;
}
</syntaxhighlight>

== Nested Structs ==
<syntaxhighlight lang="C">
struct Foo
{
    int a;
    struct Bar
    {
	int c;
    } bar;
};

struct Abc
{
    int a;
    struct
    {
	int c;
    } bar;
};
</syntaxhighlight>

becomes:

<syntaxhighlight lang="D">
struct Foo
{
    int a;
    struct Bar
    {
	int c;
    }
    Bar bar;
}

struct Abc
{
    int a;
    struct
    {
	int c;
    }
}
</syntaxhighlight>

== __cdecl, __pascal, __stdcall ==

<syntaxhighlight lang="C">
int __cdecl x;
int __cdecl foo(int a);
int __pascal bar(int b);
int __stdcall abc(int c);
</syntaxhighlight>

becomes:

<syntaxhighlight lang="D">
extern (C) int x;
extern (C) int foo(int a);
extern (Pascal) int bar(int b);
extern (Windows) int abc(int c);
</syntaxhighlight>

== __declspec(dllimport) ==

<syntaxhighlight lang="C">
__declspec(dllimport) int __stdcall foo(int a);
</syntaxhighlight>

becomes:

<syntaxhighlight lang="D">
export extern (Windows) int foo(int a);
</syntaxhighlight>

== __fastcall ==
Unfortunately, D doesn't support the '''__fastcall''' convention. Therefore, a shim will be needed, either written in C:

<syntaxhighlight lang="C">
int __fastcall foo(int a);

int myfoo(int a)
{
    return foo(int a);
}
</syntaxhighlight>

and compiled with a C compiler that supports '''__fastcall''' and linked in, or compile the above, disassemble it with [http://www.digitalmars.com/ctg/obj2asm.html obj2asm] and insert it in a D '''myfoo''' shim with [http://dlang.org/iasm.html inline assembler].