Conditional Compilation - D Programming Language

Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Calendar
  - Discord (community-run)
  - Forums
  - IRC
  - Wiki
  - Issues
  - Contributing
  - Contributors
  - Foundation
  - Security Team
  - Donate
  - Sponsors
- Resources
  - Tour
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - run.dlang.io
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

# 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:

- `unittest` blocks are compiled and run only if the `-unittest` compiler switch is enabled.
- The contract programming blocks `in`, `out`, and `invariant` are activated only if the `-release` compiler switch is not enabled.

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:

- `debug`
- `version`
- `static if`
- `is` expression
- `__traits`

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 endianness | LittleEndian 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:

- `none`: This tag is never defined; it is useful for disabling code blocks.
- `all`: This tag is always defined; it is useful for enabling code blocks.

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

- Code that is defined as `debug` is included to the program only if the `-debug` compiler switch is used.
- Code that is defined as `version` is included to the program only if a corresponding `-version` compiler switch is used.
- `static if` is similar to an `if` statement that is executed at compile time. It introduces code to the program depending on certain compile-time conditions.
- `static assert` validates assumptions about code at compile time.
- `__traits` and `std.traits` provide information about types at compile time.

Copyright © 1999-2026 by the D Language Foundation | Page generated by Ddoc on Wed Aug 5 15:38:50 2026