View source for Win32 DLLs in D

DLLs (Dynamic Link Libraries) are one of the foundations of system programming for Windows. The D programming language enables the creation of several different types of DLLs.

For background information on what DLLs are and how they work Chapter 11 of Jeffrey Richter's book [http://www.amazon.com/exec/obidos/ASIN/1572315482/classicempire Advanced Windows] is indispensible. 

This guide will show how to create DLLs of various types with D.

== Compiling a DLL ==
Use the [https://dlang.org/dmd-windows.html#switch-shared -shared] switch to tell the compiler that the generated code is to be put into a DLL. Code compiled for an EXE file will use the optimization assumption that '''_tls_index==0'''. Such code in a DLL will crash.

== DLLs with a C Interface ==

A DLL presenting a C interface can connect to any other code in a language that supports calling C functions in a DLL.

DLLs can be created in D in roughly the same way as in C. A DllMain() is required, but you can use the mixin template SimpleDllMain to insert it:

<syntaxhighlight lang="D">
import core.sys.windows.windows;
import core.sys.windows.dll;

mixin SimpleDllMain;

</syntaxhighlight>

Notes:

* Under the hood, this DllMain simply forwards to the appropriate helper functions found in core.sys.windows.dll. These setup the runtime, create thread objects for interaction with the garbage collector and initialize thread local storage data.
* The DLL does not share its runtime or memory with other DLLs.
* The presence of '''DllMain()''' is recognized by the compiler causing it to emit a reference to [http://www.digitalmars.com/ctg/acrtused.html __acrtused_dll] and the '''phobos.lib''' runtime library.

You must export any functions you want the user to access. Do this by using the '''export''' keyword in your code.

Alternatively, you can link with a .def ([http://www.digitalmars.com/ctg/ctgDefFiles.html Module Definition File]) along the lines of:

<pre>
LIBRARY         MYDLL
DESCRIPTION     'My DLL written in D'

EXETYPE		NT
CODE            PRELOAD DISCARDABLE
DATA            WRITE

EXPORTS
		DllGetClassObject       @2
		DllCanUnloadNow         @3
		DllRegisterServer       @4
		DllUnregisterServer     @5
</pre>

The functions in the EXPORTS list are for illustration. Replace them with the actual exported functions from MYDLL. Alternatively, use [http://www.digitalmars.com/ctg/implib.html implib]. Here's an example of a simple DLL with a function print() which prints a string:

=== mydll.d: ===
<syntaxhighlight lang="D">
module mydll;
import core.stdc.stdio;
export void dllprint() { printf("hello dll world\n"); }
</syntaxhighlight>

Note: We use '''printf'''s in these examples instead of '''writefln''' to make the examples as simple as possible.

=== mydll.def: ===

<pre>
LIBRARY "mydll.dll"
EXETYPE NT
SUBSYSTEM WINDOWS
CODE SHARED EXECUTE
DATA WRITE
</pre>

Put the code above that contains '''DllMain()''' into a file '''dll.d'''. Compile and link the dll with the following command:

<pre>
C:>dmd -ofmydll.dll -L/IMPLIB mydll.d dll.d mydll.def
C:>
</pre>

which will create mydll.dll and mydll.lib. Now for a program, test.d, which will use the dll:

=== test.d: ===
<syntaxhighlight lang="D">
import mydll;

int main()
{
   mydll.dllprint();
   return 0;
}
</syntaxhighlight>

Create an interface file mydll.di that doesn't have the function bodies.

=== mydll.di: ===
<syntaxhighlight lang="D">
export void dllprint();
</syntaxhighlight>

Compile and link with the command:

<pre>
C:>dmd test.d mydll.lib
C:>
</pre>

and run:

<pre>
C:>test
hello dll world
C:>
</pre>

=== Memory Allocation ===
D DLLs use garbage collected memory management. The question is what happens when pointers to allocated data cross DLL boundaries? If the DLL presents a C interface, one would assume the reason for that is to connect with code written in other languages. Those other languages will not know anything about D's memory management. Thus, the C interface will have to shield the DLL's callers from needing to know anything about it.

There are many approaches to solving this problem:

* Do not return pointers to D gc allocated memory to the caller of the DLL. Instead, have the caller allocate a buffer, and have the DLL fill in that buffer.
* Retain a pointer to the data within the D DLL so the GC will not free it. Establish a protocol where the caller informs the D DLL when it is safe to free the data.
* Notify the GC about external references to a memory block by calling GC.addRange.
* Use operating system primitives like VirtualAlloc() to allocate memory to be transferred between DLLs.
* Use core.stdcc.stdlib.malloc() (or another non-gc allocator) when allocating data to be returned to the caller. Export a function that will be used by the caller to free the data.

== COM Programming ==

COM interfaces are all derived from '''core.sys.windows.com.IUnknown'''.

See [[COM Programming]] for more details.

== D code calling D code in DLLs ==
Having DLLs in D be able to talk to each other as if they were statically linked together is, of course, very desirable as code between applications can be shared, and different DLLs can be independently developed.

The underlying difficulty is what to do about garbage collection (gc). Each EXE and DLL will have their own gc instance. When dynamically loading, it is important to load the dll with '''Runtime.loadLibrary''' instead of the system `LoadLibrary` call to ensure the druntime functions are called and the dll must use the druntime dll helper functions (e.g. mixin SimpleDllMain), the same as the C interface example.

=== Shared D Runtime(LDC) ===
When using the LDC compiler, the D Runtime can share the GC by compiling both the executable and the DLL with the flag '''-link-defaultlib-shared'''. Sharing the runtime is very important for being able to handle '''Error/Exception'''. If they are not shared, throwing from the DLL will simply crash the program instead of giving a useful message, this is also true for '''assert''' and other errors the runtime checks for you, for example, range errors. If this flag is not passed at compilation, the GC allocated memory sent from the executable to the DLL and vice versa will need to have its lifetime tracked manually. 

==== Warning for Dub users ====
If you're using the '''dependencies''' section in Dub, passing this flag will get you a linking error, because this is a global flag, all the dependencies must know about it. The safest way to make that is setting the environment variable '''DFLAGS=-link-defaultlib-shared''' before calling '''dub'''. This is a very important step for dub users that must be took with care.

== Using a D class from a DLL ==
Even classes can be loaded using `'''Runtime.loadLibrary'''`. Though those classes must be instantiated via a `factory` function. That means, a function which will return a new instance.
For loading D classes, one must '''import a D interface file(*.di)''' an mark the class as `extern`:

=== class_from_dll.d ===
<syntaxhighlight lang="D">
module class_from_dll;
//This code is not needed for ldc2
version(Windows)
{
    import core.sys.windows.dll;
    mixin SimpleDllMain;
}

export class ClassFromDll
{
    void print()
    {
        import std.stdio;
        writeln("Hello from exported Class!");
    }
}

export ClassFromDll factory(){return new ClassFromDll;}
</syntaxhighlight>

=== class_from_dll.di ===
<syntaxhighlight lang="D">
module class_from_dll;
extern class ClassFromDll
{
    void print();
}
extern ClassFromDll factory();
</syntaxhighlight>

=== app.d ===
<syntaxhighlight lang="D">
module app;

import core.runtime;
import core.sys.windows.winbase:GetProcAddress;
void main()
{
    void* lib = Runtime.loadLibrary("./class_from_dll.dll");
    import class_from_dll;
    auto factoryFunction = cast(typeof(&factory))GetProcAddress(lib, factory.mangleof);
    ClassFromDll cls = factoryFunction();
    cls.print();
}

</syntaxhighlight>

<syntaxhighlight lang="text">
dmd -shared class_from_dll.d
dmd app.d class_from_dll.di
</syntaxhighlight>

----

[[Category::Windows]]
[[Category::DLL]]
[[Category::know-how]]
[[Category::Development]]
[[Category:HowTo]]