Pragmas

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

Pragmas are a way to pass special information to the compiler and to add vendor specific extensions to D. Pragmas can be used by themselves terminated with a ‘;’, they can influence a statement, a block of statements, a declaration, or a block of declarations.

Pragmas can appear as either declarations, Pragma DeclarationBlock, or as statements, 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. ExpressionList is a comma-separated list of AssignExpressions. The AssignExpressions must be parsable as expressions, but what they mean semantically is up to the individual pragma semantics.

Predefined Pragmas

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

• pragma inline
• pragma lib
• pragma mangle
• pragma msg
• pragma startaddress

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. If there are multiple pragma inlines in a function, the lexically last one takes effect.

It takes three forms:

1. pragma(inline)
   

   Sets the behavior to match the default behavior set by the compiler switch -inline.

2. pragma(inline, false)
   

   Functions are never inlined.

3. pragma(inline, true)
   

   If a function cannot be inlined with the -inline switch, an error message is issued. This is expected to be improved in the future to causing functions to always be inlined regardless of compiler switch settings. Whether a compiler can inline a particular function or not is implementation defined.

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

lib

Inserts a directive in the object file to link in the library specified by the AssignExpression. The AssignExpressions must be a string literal:

pragma(lib, "foo.lib");

mangle

Overrides the default mangling for a symbol. It's only effective when the symbol is a function declaration or a variable declaration. For example this allows linking to a symbol which is a D keyword, which would normally be disallowed as a symbol name:

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

msg

Constructs a message from the arguments and prints to the standard error stream while compiling:

pragma(msg, "compiling...", 1, 1.0);

startaddress

Puts a directive into the object file saying that the function specified in the first argument will be the start address for the program:

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

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.

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_funky_extension) { ... }

Compilers must diagnose an error for unrecognized Pragmas, even if they are vendor specific ones. This implies that vendor specific pragmas should be wrapped in version statements:

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