The primary focus of this chapter is how to create a binding between D and C. A binding is a bit of code that allows one language to communicate with another. There are two other terms that sometimes get mixed up in the same context: wrapper and port. If you ever create a binding to a C library and intend to make it publicly available for others, you want to make sure you're using the correct terminology.

Different languages have different approaches to creating language bindings. Java programmers bind to foreign-language libraries through the Java Native Interface (JNI). An intermediate layer, which sits between the Java code and the library, is created as a C or C++ library. The JNI is used to translate Java types and function calls to something understood by the foreign library. In this scenario, the Java code does not bind to the foreign library itself, but rather to the intermediate layer. This means there need not be a one-to-one correspondence between the types and function signatures in the library and those on the Java side. In fact, the intermediate layer can hide the library interface completely and expose an entirely new interface to the Java code, one that wraps the library. In that situation, the result can be called a wrapper.

C++ has the advantage that C++ compilers can understand C header files. No bindings need to be created to use a C library in C++. However, some C++ programmers prefer to create an object-oriented interface over a C library, using C++ features that aren't present in C. Again, this can be called a wrapper. When going the other way, from C++ to C, the terminology isn't so obvious. Much of the C++ API is hidden behind C functions. The interface has to be different simply because C does not support many C++ features. Is this a binding or a wrapper? Both terms are sometimes used in this case.

Like C++, D can communicate directly with C without the need for a JNI-like layer in the middle. However, D compilers do not know how to parse C header files. That means the function prototypes and type declarations in a C header need to be translated to D. The result is a module full of aliases, type declarations, and function prototypes that can be called a binding. The new D module can be imported in any D project and, once compiled and linked with the C library, will allow D code to call into the C API directly.

Several great examples of this can be found in the DRuntime source that ships with DMD. The core.stdc package is a collection of modules that, together, form a binding to the C library. In it you'll find function prototypes such as this one from core.stdc.stdlib:

extern(C) void exit(int status);

That comes with a companion set of manifest constants, which are the result of translating the C definitions for the possible values of status:

enum EXIT_SUCCESS = 0;
enum EXIT_FAILURE = 1;
enum MB_CUR_MAX   = 1;

When you compile any D program, the standard C library is automatically linked, so you can call exit and any other standard C functions any time you like. All you need is to import the correct module.

In D, there is a clear distinction between bindings and wrappers. Bindings provide no implementation of the functions in an API, only the signatures; they link directly with the equivalent symbols in a C library. A wrapper can be implemented on top of a binding to give it a more D-like interface, but the functions in a wrapper must have an implementation. As an example, you can find a binding to the 2D graphics library, SDL, at https://github.com/DerelictOrg/DerelictSDL2. Then at https://github.com/d-gamedev-team/gfm/tree/master/sdl2/gfm/sdl2 is an API that uses the binding internally, but wraps the SDL interface in something more D-friendly.

That brings us to the word port. Typically, this term is used to indicate that a program has been translated from one language, platform, or CPU architecture to another. Looking at core.stdc again, some might say that the headers of the C standard library have been ported to D, but that's misleading; we cannot say that the entire library has been ported. Translating the headers is what is necessary to create a binding; translating the source is creating a port. As an example, the colorize package that we used in the previous chapter is a port of a Ruby library to D. Bindings have a number of constraints which ports don't have, perhaps the biggest being a dependency on the original C library.

From personal experience in maintaining the Derelict bindings over several years, more confusion arises from the terms dynamic binding and static binding than from any other related terms. There are four other terms that include dynamic or static and which are often used in any discussion about compiling, linking, and using bindings: dynamic linking, static linking, dynamic libraries, and static libraries. Even if you are familiar with these terms and what they describe, you are encouraged to read through this subsection to fully understand the difference between static and dynamic bindings.

extern(C) void exit(int status);

extern(C) alias pexit = void function(int);
pexit exit;

With a language that supports function overloading, a linker needs to be able to distinguish between different overloads of a function. It also needs to be able to distinguish between any symbols of the same name in different namespaces. This is where name mangling comes into play. The compiler takes symbols declared in source code and mangles, or decorates, them with a set of characters that have predefined meanings. We can see this in D by calling the mangleof property on any symbol. Save the following as $LEARNINGD/Chapter09/mangle.d:

module mangle;
import std.stdio;
int x;
void printInt(int i) { writeln(i); }
void main() {
  writeln(x.mangleof);
  writeln(printInt.mangleof);
}

Running this results in the following output:

_D6mangle1xi
_D6mangle8printIntFiZv

A linker need not know or care what the mangled names indicate, but a tool that understands D mangling can make use of it. In both lines, _D indicates that this is the D name-mangling format. The 6 immediately after it says that the symbol following the number, mangle, has six characters. Being that mangle is the first symbol in the name, we know it's the name of the module. It acts as a namespace. In the first line, mangle is followed by 1xi. The 1 indicates a one-character symbol name, x is the name, and the i tells us it's an int.

Similarly, the second line tells us that the symbol name has 8 characters and the name is printInt. F lets us know that it's a function, i that it takes an int parameter, and Z, in this case, indicates that the next character represents the return type of the function. Since that happens to be v, we know the return type is void. You can read more about D's name mangling at http://dlang.org/abi.html.

Not all languages define a name-mangling format as D does. C++, for example, does not; each compiler has its own approach to name mangling, which is one of several aspects of the C++ ABI that makes it extremely difficult to bind to C++ libraries (though, as we'll see in Chapter 11, Taking D to the Next Level, there is ongoing work to make it possible in D). C, on the other hand, is the lingua franca of programming languages for a reason: it has a well-defined ABI that does not include function overloading or namespaces.

That's not to say that C compilers don't use any sort of decorations. It's still necessary to distinguish between variables that are declared locally to a compilation unit rather than globally, but this has no impact on bindings. Some compilers may decorate a C symbol in a static library with an underscore, but this is usually not an issue in practice. The short of it is that when a C header is translated into D, any symbols that need to link up on both sides cannot be declared with the default D name mangling. The C side knows nothing about D's name-mangling scheme, so nothing would ever match up unless it's disabled. We'll see how to do this soon, but first we need to talk about calling conventions.

When a function is called, there are a number of steps that must be taken, both at the beginning of the call and at the end. During compilation, the compiler generates the appropriate instructions to carry out those steps. This includes instructions to preserve the contents of the CPU registers if needed, pushing function parameters on the stack or copying them into registers before the call, looking in the correct location for a return value once a function call has ended, and other low-level details that we programmers never have to manage ourselves unless we are programming in assembly. In order for the correct instructions to be generated, the requirements must be detailed somewhere of how to carry out any given function call, including whether it expects any parameters in registers, in what order stack parameters should be pushed, and so on. That's the role played by a calling convention.

A calling convention defines how every aspect of a function call should be handled. When a function is compiled, the compiler determines which calling convention is associated with the function and generates the appropriate instructions to fetch parameters and return a value. When any code calling that function is compiled, the compiler must be made aware of the calling convention originally used to compile the function so that it can generate the appropriate instructions for the call.

By default, all functions in D are assumed to have the D calling convention. As I write, the D calling convention on non-Windows systems is documented to be the same as the C calling convention supported by the system C compiler. In practice, there are undocumented discrepancies, but this isn't an issue for general use. The convention for Windows is described at http://dlang.org/abi.html.

When binding to any C library from D, it's important to know exactly which calling convention the library uses. On non-Windows systems, this is almost always the C calling convention. On Windows, it is usually either the C calling convention or the system calling convention, stdcall (standard call). Often, the calling convention used is not described anywhere in a library's documentation and it's necessary to look at the headers. If you find __stdcall defined in any of the headers, such as something like this:

#define DLL_CALLCONV __stdcall

Then you know any functions annotated with DLL_CALLCONV have the standard call calling convention. The C calling convention might also be defined explicitly with a __cdecl. If no convention is declared, you can assume the C calling convention, which is the default for all C compilers.

D allows you to specify both the name-mangling scheme of any symbol and the calling convention of any function by using a linkage attribute. Here's an example:

module linkage;
extern(C) int cint;
extern(D) int dint;
extern(C) int aFuncWithCLinkage() { return 1; }
extern(D) int aFuncWithDLinkage() { return 2; }
void main() {
  import std.stdio;
  writeln(cint.mangleof);
  writeln(dint.mangleof);
  writeln(aFuncWithCLinkage.mangleof);
  writeln(aFuncWithDLinkage.mangleof);
}

extern(C) is a linkage attribute that turns off name mangling (to match C) and specifies that a function has the C calling convention. extern(D) specifies the D name mangling and calling convention. The output looks like this:

cint
_D7linkage4dinti
aFuncWithCLinkage
_D7linkage17aFuncWithDLinkageFZi

That's a big difference. It's easy to forget that linkage attributes affect more than calling conventions. Of course, since D is the default name-mangling scheme and calling convention, the need to specify it in code is rare (in the previous example, main has D linkage). However, linkage attributes can be declared with a colon (:) and with braces ({}), so it may sometimes be needed. For example:

extern(C):
  // A bunch of stuff with C linkage
extern(D):
  // Enable D linkage again

In addition to C and D, there are also the Windows, System, and Pascal linkage attributes. extern(Windows) is used for functions that have the standard call calling convention. extern(System) defaults to extern(Windows) on Windows and extern(C) elsewhere. There are some cross-platform libraries out there that use the default C calling convention on most platforms, but use standard call on Windows. extern(System) eliminates the need to declare two sets of function declarations to match the different calling conventions. The need for extern(Pascal) is extremely rare, if not nonexistent. It was the system calling convention for Windows back in the 16-bit days.

Linkage attributes have no effect on type declarations. We can see that in this example:

module types;
extern(C) struct CStruct {
  int x, y;
}
struct DStruct {
  int x, y;
}
void main() {
  import std.stdio;
  writeln(CStruct.mangleof);
  writeln(DStruct.mangleof);
}

The output:

S5types7CStruct
S5types7DStruct

Some new D programmers think that types must always be declared as extern(C) when binding to C, but that's not the case. The types in D don't even need to have the same name as the C types, as the type names will never be emitted to the binary. All that matters is that the D types are binary compatible with the C types. More on this in the next section.

Another point of confusion comes from function implementations with C linkage. Functions in a C library binding have no implementation, only declarations. However, when using a binding, it is sometimes necessary to implement an extern(C) function to use as a callback. Sometimes, new D users have the impression that D features cannot be used in such a function. This is not the case. Remember, the linkage attribute only affects the mangling of the function's name and its calling convention. There are no restrictions on the features that can be used in the function body. On the other hand, there can be negative consequences when it comes to throwing exceptions and allocating GC memory, but that has nothing to do with the linkage attribute. We'll cover those issues later in the chapter when we talk about calling C from D.