There are a few DMD options that control optimizations and debugging. The -g switch adds debugging information in a D-specific format. For debuggers that don't support D debug symbols, -gc can be used to make the compiler use C-style debug output. The -O switch turns on optimizations; -inline will activate function inlining; -release will turn off contracts and asserts, cause assertion failures to be classified as undefined behavior, and disable array bounds checking in functions not annotated with @safe (more on that in Chapter 11, Taking D to the Next Level). Additionally, the –boundscheck= switch can be used to have a little more control over array bounds checking. It takes one of three possible arguments: on, safeonly, and off. The first is the default in the absence of –release, the second the default with it.

The default behavior of DMD is to name the binary output the same as the first input source or object file it is given, and to write it in the current working directory, using the appropriate platform-specific file extension. The output directory for object files and library files can be changed with the -od command-line switch. The name of the target library or executable file can be changed with the –of switch. The argument here can be a file name or a path. For example, the following line writes main.obj to the out/obj subdirectory and creates an executable named app (or app.exe on Windows) in a subdirectory named bin. The directories out, out/obj and bin will be created if they do not exist.

dmd –odout/obj –ofbin/app main.d

Creating a library requires compiling several source files into object files, then handing the object files off to a tool that packs them all into the target library. DMD allows you to condense these separate steps into a single command line with the –lib switch. With this option, any source files, object files, or library files fed to the compiler will all be combined into a single library. Let's experiment.

In $LEARNINGD/Chapter08/libs, create two modules, hello.d and goodbye.d. The former should look like this:

module hello;
void sayHello() {
	import std.stdio : writeln;
	writeln("Hello");
}

And the latter should look this:

module goodbye;
void sayGoodbye() {
	import std.stdio : writeln("Goodbye!");
}

First, let's create two separate libraries, named hello and goodbye with the following two command lines:

dmd -lib -odseparate hello.d
dmd -lib -odseparate goodbye.d

This will create two libraries (hello.lib and goodbye.lib on Windows, libhello.a and libgoodbye.a elsewhere) in a subdirectory named separate. Let's say we want to combine them into a single library. There are multiple ways to go about this. If all we have is the source code, we would do this:

dmd -lib -odcombined -ofgreets hello.d goodbye.d

Now we have greets.lib or libgreets.a in the combined subdirectory. What if we have the two libraries and no source?

dmd -lib -odcombined -ofgreets separate/hello.lib separate/goodbye.lib

Same result. You could also pass, for example, hello.d and goodbye.lib, or hello.lib and goodbye.d, or compile the source modules into object files and pass those to the compiler instead. Each case will have the same result.

Using a library with DMD can be as easy as making one, but there are some potential pain points. For the simplest cases, you can pass a library directly on the command line along with one or more source files, object files, or other libraries. As long as a main function exists somewhere in the mix, the compiler will make sure everything is passed to the linker to generate the executable. For example, given a module main.d in $LEARNINGD/Chapter08/libs, which looks like this:

void main() {
	import hello, goodbye;
	sayHello();
	sayGoodbye();
}

As we saw in Chapter 4, Running Code at Compile Time, we can add a lib pragma to the top of main.d and forgo the need to pass the library on the command line at all, but if we do decide to use the command line, there are some differences between Windows and other platforms.

On Windows, we can compile the preceding code and link with combined/greets.lib like so:

dmd main.d combined/greets.lib

This command line hides the linker flags from the user. Whether we're using the Digital Mars linker or the Microsoft linker, the compiler will do what needs to be done to link the binary. DMD allows flags to be passed directly to the linker with the –L switch. On Linux, Mac, and the BSDs, this is used to specify any libraries that should be linked with. On those platforms, the GNU linker expects libraries to be fed to it with the –l (lowercase L) switch. For example, given libgreets.a in the same directory as main.d, we would link with it like so:

dmd –L-lgreets main.d

The –L tells the compiler that what immediately follows is not for the compiler itself, but for the linker. So, now we have two different command lines for linking with libraries, one for Windows and one for other platforms. If we want to pass a common directory in which to find libraries, it gets a bit messier.

Whether we're passing libraries on the command line or using lib pragmas, when we are using multiple libraries from the same path, it can help keep things neat and concise if we tell the linker to look for the libraries in a specific directory. Moreover, due to the nature of the linker on Linux and other platforms, you typically don't want to be passing a full library name (such as libhello.a) to the linker. This is where the pain starts to set in if you are using a make file or custom build script to compile on multiple platforms, or on Windows with multiple compilers or architectures.

To specify a common directory, we have to explicitly pass the appropriate flag to the linker via –L, but the DM linker and the MS linker take different options. Not only that, if you throw in other platforms, you've got a third option to deal with. In short, telling the linker to search for libraries in the separate subdirectory and link with both the hello and goodbye libraries looks like the following with the different linkers:

This is where something like DUB really comes in handy. No matter which compiler, which platform, or which linker, it abstracts away all these differences so that you never have to worry about them.

Finally, it's worth noting that DMD looks for the LIB environment variable when it's time to link. If you have any special paths where you like to store libraries, you can add that path to LIB, either on the command line, via a shell script, or in the DMD configuration file.

Warnings in DMD are not enabled by default. There are two ways to turn them on. With the –w switch, warnings will be treated as errors and cause compilation to halt. The –wi switch will allow compilation to continue, printing each warning to stderr as they are encountered. Whichever approach you prefer, it's a good idea to compile your project with these once in a while, if not all the time, to try and squelch any warnings that may arise.

There are a number of profiling tools out there that may be usable with D when working with the GCC or Microsoft toolchains, but DMD ships with an easy-to-use option that allows you to get an idea of where your D program is spending its time. It's a simple command-line switch, -profile, which results in a binary that generates profiling information on execution.

In the $LEARNINGD/Chapter08/profile directory, you'll find a source file, main.d:

uint calc(uint x, uint y) {
    return x + y;
}
uint select() {
    import std.random : uniform;
    return uniform(1u, 1001u);
}
void main() {
    import std.stdio : writeln;

    for(size_t i=0; i<100; ++i) {
        writeln("Starting calculations...");
        uint result;
        for(size_t j=0; j<20; ++j) 
            result += calc(select(), select());
        writeln("The accumulated result: ", result);
    }
}

Compile this file with the following command:

dmd -profile main.d

Executing the resulting binary will produce two new files, trace.def and trace.log. The former is intended to be passed to the linker, telling it the optimal order in which to link the program's functions. The latter has two sections that display information about the program's call tree and the function timings.

The first section appears to be a jumbled mess of mangled function names and numbers, but there is a method to the madness: it's a call tree. Each entry is separated by dashed lines, with the first function called in the program (the main function) listed at the very bottom of the tree. Scroll down until you see the last few sections that look like this:

------------------
	 4000	_Dmain
_D4main6selectFZk	4000	2736	471
	 4000	_D3std6random27__T7uniformVAyaa2_5b29TkTkZ7uniformFNfkkZk
------------------
	    1	main
_Dmain	1	119380	464
	  100	_D3std5stdio16__T7writelnTAyaZ7writelnFNfAyaZv
	 4000	_D4main6selectFZk
	 2000	_D4main4calcFiiZk
	  100	_D3std5stdio18__T7writelnTAyaTkZ7writelnFNfAyakZv
------------------
main	0	0	0
	    1	_Dmain

The entry at the bottom tells us that the main function (which is actually internal to DRuntime) calls _Dmain exactly one time (_Dmain is the name by which DRuntime knows our main function in main.d). Moving up to the next entry, we see 1 main in the first line. This tells us this entry is for a function that's called one time from main. Next we have the name of that function (_Dmain), followed by all of the functions that it calls and how many times it calls each of them. Next to _Dmain we see three numbers, 1, 119380 and 464. The first is the number of times it is called, in this case by main, the next two are timings in ticks , or the number of times the timer has incremented. The first timing is the total number of ticks taken by _Dmain, including the tick count of the functions it calls (call tree time).

The second is the tick count of _Dmain minus that of the functions it calls (function call time). Moving up, we see an entry for one of the functions that _Dmain calls 4000 times, select, along with the functions it calls. Select has tick counts of 2736 and 471. Every function call in the program will have an entry in the same format as those shown here.

The second section, just below the bottom entry in the call tree, starts off like this:

======== Timer Is 3320439 Ticks/Sec, Times are in Microsecs ========

This is arguably the part of the file you'll usually be most interested in. It is a table listing the number of calls and timings for each function. The headers of the table are, as shown:

Num          Tree        Func        Per
Calls        Time        Time        Call

Tree Time is the total amount of time spent inside the function, including any function calls it makes. Func Time is the total amount of time spent in the function minus any function calls it makes. Per Call is Func Time / Num Calls. Following the headers is an entry for every function, most of which are listed in their demangled forms. The entry for the select function looks like this:

4000         823         141           0     uint main.select()

A total of 4000 calls, a total time of 823 microseconds, a total function time of 141 microseconds, and a per call time of 0 (meaning less than one microsecond per call).

Code coverage analysis is useful to find dead code in a program, to make sure that all code paths intended to be taken actually are and, when used in conjunction with unit testing, to ensure all of the code is tested. Essentially, it means analyzing the run time of a program to determine what percentage of the total number of lines of code is actually touched. DMD has built-in support for code coverage analysis via the –cov switch.

Save the following code snippet as $LEARNINGD/Chapter08/cov/main.d:

import std.stdio;
void dontCallMe() {
    writeln("Not covered.");
    writeln("Me neither");
}
void callMe() {
    writeln("Covered.");
}
void main() {
    callMe();
    callMe();
}

Compile it with the following command line:

dmd -cov main.d

Execute the resulting binary and a new file, main.lst, will be created in the same directory. It contains the same source code found in main.d, but annotated with the number of times each line of code is executed. At the end of the file, it lists the total percentage of code coverage. In our case, with five total lines of code two of which are never executed, we have achieved only 60% coverage.

       |import std.stdio;
       |
       |void dontCallMe() {
0000000|    writeln("Not covered.");
0000000|    writeln("Me neither");
       |}
       |
       |void callMe() {
      2|    writeln("Covered.");
       |}
       |
       |void main() {
      1|    callMe();
      1|    callMe();
       |}
main.d is 60% covered

The –cov switch takes an optional argument specifying a target coverage percentage. If the target is not met, an error will be thrown at the end of execution, letting you know before you ever look at the output file if your target is met. For example, execute the following in the same directory:

dmd -cov=100 main.d

This yields a binary, whose output is this:

Covered.
Covered.
Error: main.d is 60% covered, less than required 100%

When compiling an executable with the –run switch, DMD will launch the binary as soon as it has been compiled and linked. Any files generated during the process are temporary and will be cleaned up once execution has completed. The syntax is as follows:

dmd <options> -run <srcfile> <args>

Here, <options> is any number of DMD options, including source files. However, one source file must follow the –run switch in <srcfile>. Any arguments passed in <args> will be treated as command-line arguments for the executed program.

The GNU D Compiler is a community-driven, GPL implementation that integrates the D front end with the GNU Compiler Collection. This integration opens the door to compiling for platforms and targets not officially supported by DMD through the use of the existing GCC toolchain to generate output. It's available through the package managers of several systems, but the latest can always be found at http://gdcproject.org/downloads.

At the time of writing, the Linux versions of GDC are well-tested and suitable for production code. They are often used to produce the final release version of software due to GDC's ability to better optimize than DMD. The Windows versions require installation of the w64-mingw32 compiler, but as I write this, they are considered alpha-quality and not quite ready for production.

Most, if not all, of the supported DMD command-line options have GCC-style equivalents supported by GDC (the common GCC options are also supported). Code generated by GDC can be debugged with GDB. Iain Buclaw, the primary GDC maintainer, is also the official maintainer of D support in GDB. It is expected that GDC will one day become part of the GCC distribution. The source for GDC can be found at https://github.com/D-Programming-GDC/GDC. There is also a GDC-specific forum at http://forum.dlang.org/group/gdc.

LDC is an open-source, community-driven compiler that integrates the D frontend with the LLVM core libraries. It is available for several different platforms supported by LLVM. Where it can't be obtained through a package manager, binaries of the latest version can always be downloaded at https://github.com/ldc-developers/ldc/releases and the source is available at https://github.com/ldc-developers/ldc. At the time of writing, Windows binaries require the Visual Studio runtime, though past releases have also supported w64-mingw32.

In addition to LLVM-related command-line options, LDC has equivalents for many of the options supported by DMD. Output on most platforms can be debugged with GDB and with Visual Studio on Windows. Like GDC, LDC is also better at optimizing D code than DMD, so it's another alternative used for release versions of software. The LDC forum at http://forum.dlang.org/group/ldc is a good source of help.