Conditional Compilation
Conditional compilation is the process of selecting which code to compile and which code to not compile. (In C and C++, conditional compilation is done with the preprocessor directives #if / #else / #endif.)
ConditionalDeclaration: Condition DeclarationBlock Condition DeclarationBlock else DeclarationBlock Condition : DeclDefsopt Condition DeclarationBlock else : DeclDefsopt ConditionalStatement: Condition NoScopeNonEmptyStatement Condition NoScopeNonEmptyStatement else NoScopeNonEmptyStatement
If the Condition is satisfied, then the following DeclarationBlock or Statement is compiled in. If it is not satisfied, the DeclarationBlock or Statement after the optional else is compiled in.
Any DeclarationBlock or Statement that is not compiled in still must be syntactically correct.
No new scope is introduced, even if the DeclarationBlock or Statement is enclosed by { }.
ConditionalDeclarations and ConditionalStatements can be nested.
The StaticAssert can be used to issue errors at compilation time for branches of the conditional compilation that are errors.
Condition comes in the following forms:
Condition: VersionCondition DebugCondition StaticIfCondition
Version Condition
VersionCondition: version ( IntegerLiteral ) version ( Identifier ) version ( unittest ) version ( assert )
Versions enable multiple versions of a module to be implemented with a single source file.
The VersionCondition is satisfied if the IntegerLiteral is greater than or equal to the current version level, or if Identifier matches a version identifier.
The version level and version identifier can be set on the command line by the -version switch or in the module itself with a VersionSpecification, or they can be predefined by the compiler.
Version identifiers are in their own unique name space, they do not conflict with debug identifiers or other symbols in the module. Version identifiers defined in one module have no influence over other imported modules.
int k; version (Demo) // compile in this code block for the demo version { int i; int k; // error, k already defined i = 3; } x = i; // uses the i declared above
version (X86) { ... // implement custom inline assembler version } else { ... // use default, but slow, version }
The version(unittest) is satisfied if and only if the code is compiled with unit tests enabled (the -unittest option on dmd).
Version Specification
VersionSpecification: version = Identifier ; version = IntegerLiteral ;
The version specification makes it straightforward to group a set of features under one major version, for example:
version (ProfessionalEdition) { version = FeatureA; version = FeatureB; version = FeatureC; } version (HomeEdition) { version = FeatureA; } ... version (FeatureB) { ... implement Feature B ... }
Version identifiers or levels may not be forward referenced:
version (Foo) { int x; } version = Foo; // error, Foo already used
VersionSpecifications may only appear at module scope.
While the debug and version conditions superficially behave the same, they are intended for very different purposes. Debug statements are for adding debug code that is removed for the release version. Version statements are to aid in portability and multiple release versions.
Here's an example of a full version as opposed to a demo version:
class Foo { int a, b; version(full) { int extrafunctionality() { ... return 1; // extra functionality is supported } } else // demo { int extrafunctionality() { return 0; // extra functionality is not supported } } }Various different version builds can be built with a parameter to version:
version(n) // add in version code if version level is >= n { ... version code ... } version(identifier) // add in version code if version // keyword is identifier { ... version code ... }
These are presumably set by the command line as -version=n and -version=identifier.
Predefined Versions
Several environmental version identifiers and identifier name spaces are predefined for consistent usage. Version identifiers do not conflict with other identifiers in the code, they are in a separate name space. Predefined version identifiers are global, i.e. they apply to all modules being compiled and imported.
| Version Identifier | Description |
|---|---|
| DigitalMars | DMD (Digital Mars D) is the compiler |
| GNU | GDC (GNU D Compiler) is the compiler |
| LDC | LDC (LLVM D Compiler) is the compiler |
| SDC | SDC (Stupid D Compiler) is the compiler |
| Windows | Microsoft Windows systems |
| Win32 | Microsoft 32-bit Windows systems |
| Win64 | Microsoft 64-bit Windows systems |
| linux | All Linux systems |
| OSX | Mac OS X |
| FreeBSD | FreeBSD |
| OpenBSD | OpenBSD |
| NetBSD | NetBSD |
| DragonFlyBSD | DragonFlyBSD |
| BSD | All other BSDs |
| Solaris | Solaris |
| Posix | All POSIX systems (includes Linux, FreeBSD, OS X, Solaris, etc.) |
| AIX | IBM Advanced Interactive eXecutive OS |
| Haiku | The Haiku operating system |
| SkyOS | The SkyOS operating system |
| SysV3 | System V Release 3 |
| SysV4 | System V Release 4 |
| Hurd | GNU Hurd |
| Android | The Android platform |
| PlayStation | The PlayStation platform |
| PlayStation4 | The PlayStation 4 platform |
| Cygwin | The Cygwin environment |
| MinGW | The MinGW environment |
| FreeStanding | An environment without an operating system (such as Bare-metal targets) |
| CRuntime_Bionic | Bionic C runtime |
| CRuntime_DigitalMars | DigitalMars C runtime |
| CRuntime_Glibc | Glibc C runtime |
| CRuntime_Microsoft | Microsoft C runtime |
| X86 | Intel and AMD 32-bit processors |
| X86_64 | Intel and AMD 64-bit processors |
| ARM | The ARM architecture (32-bit) (AArch32 et al) |
| ARM_Thumb | ARM in any Thumb mode |
| ARM_SoftFloat | The ARM soft floating point ABI |
| ARM_SoftFP | The ARM softfp floating point ABI |
| ARM_HardFloat | The ARM hardfp floating point ABI |
| AArch64 | The Advanced RISC Machine architecture (64-bit) |
| Epiphany | The Epiphany architecture |
| PPC | The PowerPC architecture, 32-bit |
| PPC_SoftFloat | The PowerPC soft float ABI |
| PPC_HardFloat | The PowerPC hard float ABI |
| PPC64 | The PowerPC architecture, 64-bit |
| IA64 | The Itanium architecture (64-bit) |
| MIPS32 | The MIPS architecture, 32-bit |
| MIPS64 | The MIPS architecture, 64-bit |
| MIPS_O32 | The MIPS O32 ABI |
| MIPS_N32 | The MIPS N32 ABI |
| MIPS_O64 | The MIPS O64 ABI |
| MIPS_N64 | The MIPS N64 ABI |
| MIPS_EABI | The MIPS EABI |
| MIPS_SoftFloat | The MIPS soft-float ABI |
| MIPS_HardFloat | The MIPS hard-float ABI |
| NVPTX | The Nvidia Parallel Thread Execution (PTX) architecture, 32-bit |
| NVPTX64 | The Nvidia Parallel Thread Execution (PTX) architecture, 64-bit |
| SPARC | The SPARC architecture, 32-bit |
| SPARC_V8Plus | The SPARC v8+ ABI |
| SPARC_SoftFloat | The SPARC soft float ABI |
| SPARC_HardFloat | The SPARC hard float ABI |
| SPARC64 | The SPARC architecture, 64-bit |
| S390 | The System/390 architecture, 32-bit |
| SystemZ | The System Z architecture, 64-bit |
| HPPA | The HP PA-RISC architecture, 32-bit |
| HPPA64 | The HP PA-RISC architecture, 64-bit |
| SH | The SuperH architecture, 32-bit |
| SH64 | The SuperH architecture, 64-bit |
| Alpha | The Alpha architecture |
| Alpha_SoftFloat | The Alpha soft float ABI |
| Alpha_HardFloat | The Alpha hard float ABI |
| LittleEndian | Byte order, least significant first |
| BigEndian | Byte order, most significant first |
| ELFv1 | The Executable and Linkable Format v1 |
| ELFv2 | The Executable and Linkable Format v2 |
| D_Coverage | Code coverage analysis instrumentation (command line switch -cov) is being generated |
| D_Ddoc | Ddoc documentation (command line switch -D) is being generated |
| D_InlineAsm_X86 | Inline assembler for X86 is implemented |
| D_InlineAsm_X86_64 | Inline assembler for X86-64 is implemented |
| D_LP64 | Pointers are 64 bits (command line switch -m64). (Do not confuse this with C's LP64 model) |
| D_X32 | Pointers are 32 bits, but words are still 64 bits (x32 ABI) (This can be defined in parallel to X86_64) |
| D_HardFloat | The target hardware has a floating point unit |
| D_SoftFloat | The target hardware does not have a floating point unit |
| D_PIC | Position Independent Code (command line switch -fPIC) is being generated |
| D_SIMD | Vector extensions (via __simd) are supported |
| D_Version2 | This is a D version 2 compiler |
| D_NoBoundsChecks | Array bounds checks are disabled (command line switch -boundscheck=off) |
| D_ObjectiveC | The target supports interfacing with Objective-C |
| unittest | Unit tests are enabled (command line switch -unittest) |
| assert | Checks are being emitted for AssertExpressions |
| none | Never defined; used to just disable a section of code |
| all | Always defined; used as the opposite of none |
The following identifiers are defined, but are deprecated:
| Version Identifier | Description | |
|---|---|---|
| darwin | The Darwin operating system; use OSX instead | |
| Thumb | ARM in Thumb mode; use ARM_Thumb instead | |
| S390X | The System/390X architecture | 64-bit; use SystemZ instead |
Others will be added as they make sense and new implementations appear.
It is inevitable that the D language will evolve over time. Therefore, the version identifier namespace beginning with "D_" is reserved for identifiers indicating D language specification or new feature conformance. Further, all identifiers derived from the ones listed above by appending any character(s) are reserved. This means that e.g. ARM_foo and Windows_bar are reserved while foo_ARM and bar_Windows are not.
Furthermore, predefined version identifiers from this list cannot be set from the command line or from version statements. (This prevents things like both Windows and linux being simultaneously set.)
Compiler vendor specific versions can be predefined if the trademarked vendor identifier prefixes it, as in:
version(DigitalMars_funky_extension)
{
...
}
It is important to use the right version identifier for the right purpose. For example, use the vendor identifier when using a vendor specific feature. Use the operating system identifier when using an operating system specific feature, etc.
Debug Condition
DebugCondition: debug debug ( IntegerLiteral ) debug ( Identifier )
Two versions of programs are commonly built, a release build and a debug build. The debug build includes extra error checking code, test harnesses, pretty-printing code, etc. The debug statement conditionally compiles in its statement body. It is D's way of what in C is done with #ifdef DEBUG / #endif pairs.
The debug condition is satisfied when the -debug switch is passed to the compiler or when the debug level is >= 1.
The debug ( IntegerLiteral ) condition is satisfied when the debug level is >= IntegerLiteral.
The debug ( Identifier ) condition is satisfied when the debug identifier matches Identifier.
class Foo { int a, b; debug: int flag; }
Debug Specification
DebugSpecification: debug = Identifier ; debug = IntegerLiteral ;
Debug identifiers and levels are set either by the command line switch -debug or by a DebugSpecification.
Debug specifications only affect the module they appear in, they do not affect any imported modules. Debug identifiers are in their own namespace, independent from version identifiers and other symbols.
It is illegal to forward reference a debug specification:
debug(foo) writeln("Foo"); debug = foo; // error, foo used before set
DebugSpecifications may only appear at module scope.
Various different debug builds can be built with a parameter to debug:
debug(IntegerLiteral) { } // add in debug code if debug level is >= IntegerLiteral debug(identifier) { } // add in debug code if debug keyword is identifier
These are presumably set by the command line as -debug=n and -debug=identifier.
Static If Condition
StaticIfCondition: static if ( AssignExpression )
AssignExpression is implicitly converted to a boolean type, and is evaluated at compile time. The condition is satisfied if it evaluates to true. It is not satisfied if it evaluates to false.
It is an error if AssignExpression cannot be implicitly converted to a boolean type or if it cannot be evaluated at compile time.
StaticIfConditions can appear in module, class, template, struct, union, or function scope. In function scope, the symbols referred to in the AssignExpression can be any that can normally be referenced by an expression at that point.
const int i = 3; int j = 4; static if (i == 3) // ok, at module scope int x; class C { const int k = 5; static if (i == 3) // ok int x; else long x; static if (j == 3) // error, j is not a constant int y; static if (k == 5) // ok, k is in current scope int z; } template INT(int i) { static if (i == 32) alias INT = int; else static if (i == 16) alias INT = short; else static assert(0); // not supported } INT!(32) a; // a is an int INT!(16) b; // b is a short INT!(17) c; // error, static assert trips
A StaticIfConditional condition differs from an IfStatement in the following ways:
- It can be used to conditionally compile declarations, not just statements.
- It does not introduce a new scope even if { } are used for conditionally compiled statements.
- For unsatisfied conditions, the conditionally compiled code need only be syntactically correct. It does not have to be semantically correct.
- It must be evaluatable at compile time.
Static Assert
StaticAssert: static assert ( AssignExpression ,opt ); static assert ( AssignExpression , AssignExpression ,opt );
AssignExpression is evaluated at compile time, and converted to a boolean value. If the value is true, the static assert is ignored. If the value is false, an error diagnostic is issued and the compile fails.
Unlike AssertExpressions, StaticAsserts are always checked and evaluted by the compiler unless they appear in an unsatisfied conditional.
void foo() { if (0) { assert(0); // never trips static assert(0); // always trips } version (BAR) { } else { static assert(0); // trips when version BAR is not defined } }
StaticAssert is useful tool for drawing attention to conditional configurations not supported in the code.
The optional second AssignExpression can be used to supply additional information, such as a text string, that will be printed out along with the error diagnostic.