Programming in D – Tutorial and Reference
Ali Çehreli

Other D Resources

Conditional Compilation

Conditional compilation is for compiling parts of programs in special ways depending on certain compile time conditions. Sometimes, entire sections of a program may need to be taken out and not compiled at all.

Conditional compilation involves condition checks that are evaluable at compile time. Runtime conditional statements like if, for, while are not conditional compilation features.

We have already encountered some features in the previous chapters, which can be seen as conditional compilation:

Unit tests and contracts are about program correctness; whether they are included in the program should not change the behavior of the program.

The following are the features of D that are specifically for conditional compilation:

We will see the is expression in the next chapter.

debug

debug is useful during program development. The expressions and statements that are marked as debug are compiled into the program only when the -debug compiler switch is enabled: 

debug a_conditionally_compiled_expression;

debug {
    // ... conditionally compiled code ...

} else {
    // ... code that is compiled otherwise ...
}

The else clause is optional.

Both the single expression and the code block above are compiled only when the -debug compiler switch is enabled.

We have been adding statements into the programs, which printed messages like "adding", "subtracting", etc. to the output. Such messages (aka logs and log messages) are helpful in finding errors by visualizing the steps that are taken by the program.

Remember the binarySearch() function from the Templates chapter. The following version of the function is intentionally incorrect: 

import std.stdio;

// WARNING! This algorithm is wrong
size_t binarySearch(const int[] values, int value) {
    if (values.length == 0) {
        return size_t.max;
    }

    immutable midPoint = values.length / 2;

    if (value == values[midPoint]) {
        return midPoint;

    } else if (value < values[midPoint]) {
        return binarySearch(values[0 .. midPoint], value);

    } else {
        return binarySearch(values[midPoint + 1 .. $], value);
    }
}

void main() {
    auto numbers = [ -100, 0, 1, 2, 7, 10, 42, 365, 1000 ];

    auto index = binarySearch(numbers, 42);
    writeln("Index: ", index);
}

Although the index of 42 is 6, the program incorrectly reports 1: 

Index: 1

One way of locating the bug in the program is to insert lines that would print messages to the output: 

size_t binarySearch(const int[] values, int value) {
    writefln("searching %s among %s", value, values);

    if (values.length == 0) {
        writefln("%s not found", value);
        return size_t.max;
    }

    immutable midPoint = values.length / 2;

    writefln("considering index %s", midPoint);

    if (value == values[midPoint]) {
        writefln("found %s at index %s", value, midPoint);
        return midPoint;

    } else if (value < values[midPoint]) {
        writefln("must be in the first half");
        return binarySearch(values[0 .. midPoint], value);

    } else {
        writefln("must be in the second half");
        return binarySearch(values[midPoint + 1 .. $], value);
    }
}

The output of the program now includes steps that the program takes: 

searching 42 among [-100, 0, 1, 2, 7, 10, 42, 365, 1000]
considering index 4
must be in the second half
searching 42 among [10, 42, 365, 1000]
considering index 2
must be in the first half
searching 42 among [10, 42]
considering index 1
found 42 at index 1
Index: 1

Let's assume that the previous output does indeed help the programmer locate the bug. It is obvious that the writefln() expressions are not needed anymore once the bug has been located and fixed. However, removing those lines can also be seen as wasteful, because they might be useful again in the future.

Instead of being removed altogether, the lines can be marked as debug instead: 

        debug writefln("%s not found", value);

Such lines are included in the program only when the -debug compiler switch is enabled: 

$ dmd deneme.d -ofdeneme -w -debug
debug(tag)

If there are many debug keywords in the program, possibly in unrelated parts, the output may become too crowded. To avoid that, the debug statements can be given names (tags) to be included in the program selectively: 

        debug(binarySearch) writefln("%s not found", value);

The tagged debug statements are enabled by the -debug=tag compiler switch: 

$ dmd deneme.d -ofdeneme -w -debug=binarySearch

debug blocks can have tags as well: 

    debug(binarySearch) {
        // ...
    }

It is possible to enable more than one debug tag at a time: 

$ dmd deneme.d -w -debug=binarySearch -debug=stackContainer

In that case both the binarySearch and the stackContainer debug statements and blocks would be included.

debug(level)

Sometimes it is more useful to associate debug statements by numerical levels. Increasing levels can provide more detailed information: 

debug import std.stdio;

void myFunction(string fileName, int[] values) {
    debug(1) writeln("entered myFunction");

    debug(2) {
        writeln("the arguments:");
        writeln("  file name: ", fileName);

        foreach (i, value; values) {
            writefln("  %4s: %s", i, value);
        }
    }

    // ... the implementation of the function ...
}

void main() {
    myFunction("deneme.txt", [ 10, 4, 100 ]);
}

The debug expressions and blocks that are lower than or equal to the specified level would be compiled: 

$ dmd deneme.d -w -debug=1
$ ./deneme 
entered myFunction

The following compilation would provide more information: 

$ dmd deneme.d -w -debug=2
$ ./deneme 
entered myFunction
the arguments:
  file name: deneme.txt
     0: 10
     1: 4
     2: 100
version(tag) and version(level)

version is similar to debug and is used in the same way: 

    version(testRelease) /* ... an expression ... */;

    version(schoolRelease) {
        /* ... expressions that are related to the version of
         *     this program that is presumably shipped to schools ... */

    } else {
        // ... code compiled otherwise ...
    }

    version(1) aVariable = 5;

    version(2) {
        // ... a feature of version 2 ...
    }

The else clause is optional.

Although version works essentially the same as debug, having separate keywords helps distinguish their unrelated uses.

As with debug, more than one version can be enabled: 

$ dmd deneme.d -w -version=record -version=precise_calculation

There are many predefined version tags, the complete list of which is available at the Conditional Compilation specification. The following short list is just a sampling:

Predefined version tags
The compiler DigitalMars GNU LDC SDC
The operating system Windows Win32 Win64 linux OSX Posix FreeBSD OpenBSD NetBSD DragonFlyBSD BSD Solaris AIX Haiku SkyOS SysV3 SysV4 Hurd
CPU endiannessLittleEndian BigEndian
Enabled compiler switches D_Coverage D_Ddoc D_InlineAsm_X86 D_InlineAsm_X86_64 D_LP64 D_PIC D_X32 D_HardFloat D_SoftFloat D_SIMD D_Version2 D_NoBoundsChecks unittest assert
CPU architecture X86 X86_64
Platform Android Cygwin MinGW ARM ARM_Thumb ARM_Soft ARM_SoftFP ARM_HardFP ARM64 PPC PPC_SoftFP PPC_HardFP PPC64 IA64 MIPS MIPS32 MIPS64 MIPS_O32 MIPS_N32 MIPS_O64 MIPS_N64 MIPS_EABI MIPS_NoFloat MIPS_SoftFloat MIPS_HardFloat SPARC SPARC_V8Plus SPARC_SoftFP SPARC_HardFP SPARC64 S390 S390X HPPA HPPA64 SH SH64 Alpha Alpha_SoftFP Alpha_HardFP
... ...

In addition, there are the following two special version tags:

As an example of how predefined version tags are used, the following is an excerpt (formatted differently here) from the std.ascii module, which is for determining the newline character sequence for the system (static assert will be explained later below): 

version(Windows) {
    immutable newline = "\r\n";

} else version(Posix) {
    immutable newline = "\n";

} else {
    static assert(0, "Unsupported OS");
}
Assigning identifiers to debug and version

Similar to variables, debug and version can be assigned identifiers. Unlike variables, this assignment does not change any value, it activates the specified identifier as well. 

import std.stdio;

debug(everything) {
    debug = binarySearch;
    debug = stackContainer;
    version = testRelease;
    version = schoolRelease;
}

void main() {
    debug(binarySearch) writeln("binarySearch is active");
    debug(stackContainer) writeln("stackContainer is active");

    version(testRelease) writeln("testRelease is active");
    version(schoolRelease) writeln("schoolRelease is active");
}

The assignments inside the debug(everything) block above activates all of the specified identifiers: 

$ dmd deneme.d -w -debug=everything
$ ./deneme 
binarySearch is active
stackContainer is active
testRelease is active
schoolRelease is active
static if

static if is the compile time equivalent of the if statement.

Just like the if statement, static if takes a logical expression and evaluates it. Unlike the if statement, static if is not about execution flow; rather, it determines whether a piece of code should be included in the program or not.

The logical expression must be evaluable at compile time. If the logical expression evaluates to true, the code inside the static if gets compiled. If the condition is false, the code is not included in the program as if it has never been written. The logical expressions commonly take advantage of the is expression and __traits.

static if can appear at module scope or inside definitions of struct, class, template, etc. Optionally, there may be else clauses as well.

Let's use static if with a simple template, making use of the is expression. We will see other examples of static if in the next chapter: 

import std.stdio;

struct MyType(T) {
    static if (is (T == float)) {
        alias ResultType = double;

    } else static if (is (T == double)) {
        alias ResultType = real;

    } else {
        static assert(false, T.stringof ~ " is not supported");
    }

    ResultType doWork() {
        writefln("The return type for %s is %s.",
                 T.stringof, ResultType.stringof);
        ResultType result;
        // ...
        return result;
    }
}

void main() {
    auto f = MyType!float();
    f.doWork();

    auto d = MyType!double();
    d.doWork();
}

According to the code, MyType can be used only with two types: float or double. The return type of doWork() is chosen depending on whether the template is instantiated for float or double: 

The return type for float is double.
The return type for double is real.

Note that one must write else static if when chaining static if clauses. Otherwise, writing else if would result in inserting that if conditional into the code, which would naturally be executed at run time.

static assert

Although it is not a conditional compilation feature, I have decided to introduce static assert here.

static assert is the compile time equivalent of assert. If the conditional expression is false, the compilation gets aborted due to that assertion failure.

Similar to static if, static assert can appear in any scope in the program.

We have seen an example of static assert in the program above: There, compilation gets aborted if T is any type other than float or double: 

    auto i = MyType!int();

The compilation is aborted with the message that was given to static assert: 

Error: static assert  "int is not supported"

As another example, let's assume that a specific algorithm can work only with types that are a multiple of a certain size. Such a condition can be ensured at compile time by a static assert: 

T myAlgorithm(T)(T value) {
    /* This algorithm requires that the size of type T is a
     * multiple of 4. */
    static assert((T.sizeof % 4) == 0);

    // ...
}

If the function was called with a char, the compilation would be aborted with the following error message: 

Error: static assert  (1LU == 0LU) is false

Such a test prevents the function from working with an incompatible type, potentially producing incorrect results.

static assert can be used with any logical expression that is evaluable at compile time.

Type traits

The __traits keyword and the std.traits module provide information about types and expressions at compile time.

Some information that is collected by the compiler is made available to the program by __traits. Its syntax includes a traits keyword and parameters that are relevant to that keyword: 

    __traits(keyword, parameters)

keyword specifies the information that is being queried. The parameters are either types or expressions, meanings of which are determined by each particular keyword.

The information that can be gathered by __traits is especially useful in templates. For example, the isArithmetic keyword can determine whether a particular template parameter T is an arithmetic type: 

    static if (__traits(isArithmetic, T)) {
        // ... an arithmetic type ...

    } else {
        // ... not an arithmetic type ...
    }

Similarly, the std.traits module provides information at compile time through its templates. For example, std.traits.isSomeChar returns true if its template parameter is a character type: 

import std.traits;

// ...

    static if (isSomeChar!T) {
        // ... char, wchar, or dchar ...

    } else {
        // ... not a character type ...
    }

Please refer to the __traits documentation and the std.traits documentation for more information.

Summary