Pragmas

Contents

Predefined Pragmas
Vendor Specific Pragmas

PragmaDeclaration:
    Pragma;
    Pragma DeclarationBlock

PragmaStatement:
    Pragma;
    Pragma NoScopeStatement

Pragma:
    pragma ( Identifier )
    pragma ( Identifier , ArgumentList )

Pragmas pass special information to the implementation and can add vendor specific extensions. Pragmas can be used by themselves terminated with a ;, and can apply to a statement, a block of statements, a declaration, or a block of declarations.

Pragmas can be either a PragmaDeclaration or a PragmaStatement.

pragma(ident);        // just by itself

pragma(ident) declaration; // influence one declaration

pragma(ident): // influence subsequent declarations
    declaration;
    declaration;

pragma(ident)   // influence block of declarations
{
    declaration;
    declaration;
}

pragma(ident) statement; // influence one statement

pragma(ident)   // influence block of statements
{
    statement;
    statement;
}

The kind of pragma it is determined by the Identifier. ArgumentList is a comma-separated list of AssignExpressions. The AssignExpressions must be parsable as expressions, but their meaning is up to the individual pragma semantics.

Predefined Pragmas

All implementations must support these, even if by just ignoring them:

pragma crt_constructor
pragma crt_destructor
pragma inline
pragma lib
pragma linkerDirective
pragma mangle
pragma msg
pragma printf
pragma scanf
pragma startaddress

Implementation Defined: An implementation may ignore these pragmas.

`pragma crt_constructor`

Annotates a function so it is run after the C runtime library is initialized and before the D runtime library is initialized.

The function must:

be extern (C)
not have any parameters
not be a non-static member function
be a function definition, not a declaration (i.e. it must have a function body)
not return a type that has a destructor
not be a nested function

__gshared int initCount;

pragma(crt_constructor)
extern(C) void initializer() { initCount += 1; }

No arguments to the pragma are allowed.

A function may be annotated with both pragma(crt_constructor) and pragma(crt_destructor).

Annotating declarations other than function definitions has no effect.

Annotating a struct or class definition does not affect the members of the aggregate.

Best Practices: Use for system programming and interfacing with C/C++, for example to allow for initialization of the runtime when loading a DSO, or as a simple replacement for shared static this in betterC mode. Implementation Defined: The order in which functions annotated with pragma(crt_constructor) are run is implementation defined. Best Practices: to control the order in which the functions are called within one module, write a single function that calls them in the desired order, and only annotate that function. Implementation Defined: This uses the mechanism C compilers use to run code before main() is called. C++ compilers use it to run static constructors and destructors. For example, GCC's __attribute__((constructor)) is equivalent. Digital Mars C uses _STI and _STD identifier prefixes to mark crt_constructor and crt_destructor functions. Implementation Defined: A reference to the annotated function will be inserted in the .init_array section for Elf systems, the XI section for Win32 OMF systems, the .CRT$XCU section for Windows MSCOFF systems, and the __mod_init_func section for OSX systems. Note: crt_constructor and crt_destructor were implemented in v2.078.0 (2018-01-01). Some compilers exposed non-standard, compiler-specific mechanism before.

`pragma crt_destructor`

pragma(crt_destructor) works the same as pragma(crt_destructor) except:

Annotates a function so it is run after the D runtime library is terminated and before the C runtime library is terminated. Calling C's exit() function also causes the annotated functions to run.

The order in which the annotated functions are run is the reverse of those functions annotated with pragma(crt_constructor).

Implementation Defined: This uses the mechanism C compilers use to run code after main() returns or exit() is called. C++ compilers use it to run static destructors. For example, GCC's __attribute__((destructor)) is equivalent. Digital Mars C uses _STI and _STD identifier prefixes to mark crt_constructor and crt_destructor functions. Implementation Defined: A reference to the annotated function will be inserted in the .fini_array section for Elf systems, the XC section for Win32 OMF systems, the .CRT$XPU section for Windows MSCOFF systems, and the __mod_term_func section for OSX systems.

__gshared int initCount;

pragma(crt_constructor)
extern(C) void initialize() { initCount += 1; }

pragma(crt_destructor)
extern(C) void deinitialize() { initCount -= 1; }

pragma(crt_constructor)
pragma(crt_destructor)
extern(C) void innuendo() { printf("Inside a constructor... Or destructor?\n"); }

`pragma inline`

Affects whether functions are inlined or not. If at the declaration level, it affects the functions declared in the block it controls. If inside a function, it affects the function it is enclosed by.

It takes two forms:

```
pragma(inline)
```
Sets the behavior to match the implementation's default behavior.
```
pragma(inline, AssignExpression)
```
The AssignExpression is evaluated and must have a type that can be converted to a boolean. If the result is false the functions are never inlined, otherwise they are always inlined.

More than one AssignExpression is not allowed.

If there are multiple pragma inlines in a function, the lexically last one takes effect.

pragma(inline):
int foo(int x) // foo() is never inlined
{
    pragma(inline, true);
    ++x;
    pragma(inline, false); // supercedes the others
    return x + 3;
}

Implementation Defined:

The default inline behavior is typically selectable with a compiler switch such as -inline.
Whether a particular function can be inlined or not is implementation defined.
What happens for pragma(inline, true) if the function cannot be inlined. An error message is typical.

`pragma lib`

There must be one AssignExpression and it must evaluate at compile time to a string literal.

pragma(lib, "foo.lib");

Implementation Defined: The string literal specifies the file name of a library file. This name is inserted into the generated object file, or otherwise passed to the linker, so the linker automatically links in that library.

`pragma linkerDirective`

There must be one AssignExpression and it must evaluate at compile time to a string literal.

pragma(linkerDirective, "/FAILIFMISMATCH:_ITERATOR_DEBUG_LEVEL=2");

Implementation Defined: The string literal specifies a linker directive to be embedded in the generated object file. Linker directives are only supported for MS-COFF output.

`pragma mangle`

Overrides the default mangling for a symbol.

There must be one AssignExpression and it must evaluate at compile time to a string literal.

It only applies to function and variable symbols. Other symbols are ignored.

Implementation Defined: On macOS and Win32, an extra underscore (_) is prepended to the string since 2.079, as is done by the C/C++ toolchain. This allows using the same pragma(mangle) for all compatible (POSIX in one case, win64 in another) platforms instead of having to special-case. Rationale:

Enables linking to symbol names that D cannot represent.
Enables linking to a symbol which is a D keyword, since an Identifier cannot be a keyword.

pragma(mangle, "body")
extern(C) void body_func();

`pragma msg`

Each AssignExpression is evaluated at compile time and then all are combined into a message.

pragma(msg, "compiling...", 6, 1.0); // prints "compiling...61.0" at compile time

Implementation Defined: The form the message takes and how it is presented to the user. One way is by printing them to the standard error stream. Rationale: Analogously to how writeln() performs a role of writing informational messages during runtime, pragma(msg) performs the equivalent role at compile time. For example,

static if (kilroy)
    pragma(msg, "Kilroy was here");
else
    pragma(msg, "Kilroy got lost");

`pragma printf`

pragma(printf) specifies that a function declaration is a printf-like function, meaning it is an extern (C) or extern (C++) function with a format parameter accepting a pointer to a 0-terminated char string conforming to the C99 Standard 7.19.6.1, immediately followed by either a ... variadic argument list or a parameter of type va_list as the last parameter.

If the format argument is a string literal, it is verified to be a valid format string per the C99 Standard. If the format parameter is followed by ..., the number and types of the variadic arguments are checked against the format string.

Diagnosed incompatibilities are:

incompatible sizes which may cause argument misalignment
deferencing arguments that are not pointers
insufficient number of arguments
struct arguments
array and slice arguments
non-pointer arguments to s specifier
non-standard formats
undefined behavior per C99

Per the C99 Standard, extra arguments are ignored.

Ignored mismatches are:

sign mismatches, such as printing an int with a %u format
integral promotion mismatches, where the format specifies a smaller integral type than int or uint, such as printing a short with the %d format rather than %hd

printf("%k\n", value); // error: non-Standard format k
printf("%d\n");        // error: not enough arguments
printf("%d\n", 1, 2);  // ok, extra arguments ignored

Best Practices: In order to use non-Standard printf/scanf formats, an easy workaround is:

const format = "%k\n";
printf(format.ptr, value);  // no error

Best Practices: Most of the errors detected are portability issues. For instance,

string s;
printf("%.*s\n", s.length, s.ptr);
printf("%d\n", s.sizeof);
ulong u;
scanf("%lld%*c\n", &u);

should be replaced with:

string s;
printf("%.*s\n", cast(int) s.length, s.ptr);
printf("%zd\n", s.sizeof);
ulong u;
scanf("%llu%*c\n", &u);

pragma(printf) applied to declarations that are not functions are ignored. In particular, it has no effect on the declaration of a pointer to function type.

`pragma scanf`

pragma(scanf) specifies that a function declaration is a scanf-like function, meaning it is an extern (C) or extern (C++) function with a format parameter accepting a pointer to a 0-terminated char string conforming to the C99 Standard 7.19.6.2, immediately followed by either a ... variadic argument list or a parameter of type va_list as the last parameter.

Diagnosed incompatibilities are:

argument is not a pointer to the format specified type
insufficient number of arguments
non-standard formats
undefined behavior per C99

Per the C99 Standard, extra arguments are ignored.

pragma(scanf) applied to declarations that are not functions are ignored. In particular, it has no effect on the declaration of a pointer to function type.

`pragma startaddress`

There must be one AssignExpression and it must evaluate at compile time to a function symbol.

Implementation Defined: The function symbol specifies the start address for the program. The symbol is inserted into the object file or is otherwise presented to the linker to set the start address. This is not normally used for application level programming, but is for specialized systems work. For applications code, the start address is taken care of by the runtime library.

void foo() { ... }
pragma(startaddress, foo);

Vendor Specific Pragmas

Vendor specific pragma Identifiers can be defined if they are prefixed by the vendor's trademarked name, in a similar manner to version identifiers:

pragma(DigitalMars_extension) { ... }

Implementations must diagnose an error for unrecognized Pragmas, even if they are vendor specific ones.

Implementation Defined: Vendor specific pragmas. Best Practices: vendor specific pragmas should be wrapped in version statements

version (DigitalMars)
{
    pragma(DigitalMars_extension)
    {   ... }
}