Using external libraries

D can use external libraries written in D, as well as other languages, with direct access to C functions, such as those provided by the operating system or the wealth of code written in C that can perform a variety of tasks. Here, you'll learn how to use an external library in your D program.

How to do it…

Let's use external libraries by executing the following steps:

1. Create or download bindings, a list of function prototypes, and a data structure definition from the library.

2. On 32-bit Windows with dmd only, get or create an import library (.lib file).

3. If you have a .lib file, you can use coffimplib.

4. If you only have a DLL file, you can use implib.

5. Import the binding by using the following statement:

   import package.module.name;

6. Compile with the library. For Linux, pass –L-llibname to dmd. On Windows, pass the .lib file to dmd when compiling your program. This will link the file with the generated executable, producing a working program.

How it works…

D is binary compatible with C, but not source compatible. This means you can link directly to C libraries, including most operating system libraries, without any wrapper or invoker code. You do need, however, to port the header files, the function prototypes, and the variable declarations, to D. This process is called binding.

While you can use a library by only providing the prototypes for the functions you need, being minimally type-safe, the recommended way is to port the C header as closely as possible. This will minimize bugs and maximize the ease of use for programmers who are familiar with the usage and documentation of C.

In your code, using the library is the same as using any other module; you import the module, call the functions, and disambiguate the names by using fully-qualified package and module names.

When compiling, the –L flag to dmd passes the rest of the argument straight to the linker. On 32-bit Windows, using an existing library may be difficult because dmd uses an old library file format called OMF that is incompatible with the newer and more common COFF format. This is where implib and coffimplib come into play—these programs generate the format that the linker, optlink, expects from the more common formats available. The implib command creates a .lib file that you can use with D directly from a .dll file. The implib command's invocation format is as follows:

implib /s myfile.lib myfile.dll

The coffimplib command converts the more common COFF .lib format to the format D requires. The coffimplib command's invocation format is as follows:

coffimplib myfile.lib

These programs can be separately downloaded from Digital Mars, the small company behind the D programming language and DMD compiler. They are not necessary when building 64-bit Windows programs, or programs on any other operating system.

There's more…

The DMD compiler supports pragma(lib, "name");, which will automatically handle the linker flag while building, if you pass the module to dmd's command line. This pragma is not fully supported on GDC, but it doesn't necessarily hurt either. It will issue a warning about an unsupported pragma.

You can also create D interface files for D libraries, the extension .di is used traditionally. The .di files can be automatically generated with the dmd –H option. The D interface files are similar to header files in C or C++; they list the interface definitions, but omit function bodies. The use of D interface files is optional.

See also

• Sometimes, using other libraries isn't as simple as calling their function, or you want to improve upon the API somehow. Chapter 4, Integration, explains how to address these issues.

• Deimos (https://github.com/d-programming-deimos) is the official repository for translated bindings and common C libraries. It makes no attempt to change the API; it is simply a collection of ports of C library headers that can be used in D, saving you the trouble of recreating the prototypes yourself.

• Dub (http://code.dlang.org) is the semi-official D package manager, and code.dlang.org lists community libraries that are available through it. This includes C bindings as well as pure D libraries.

• If you are developing for 32-bit Windows, the Basic Utilities Package from Digital Mars (http://digitalmars.com/download/freecompiler.html) contains the implib tool as well as others to build advanced Windows .exe files.

• The directory dmd2/src/druntime/import in the dmd's ZIP file has various D interface files for the D runtime library and the C standard library.