Annotated Ada Reference Manual (Ada 202y Draft 1)Legal Information
Contents   Index   References   Search   Previous   Next 

2.8 Pragmas

1
A pragma is a compiler directive. There are language-defined pragmas that give instructions for optimization, listing control, etc. An implementation may support additional (implementation-defined) pragmas. 
1.a/5
Term entry: pragma — compiler directive to provide control over and above that provided by the other syntactic constructs of the language
Note: There are language-defined pragmas that give instructions for optimization, listing control, etc. An implementation can support additional (implementation-defined) pragmas.

Language Design Principles

1.b/3
{AI05-0100-1} {AI05-0163-1} In general, if all pragmas are treated as unrecognized pragmas, the program should remain both syntactically and semantically legal. There are a few exceptions to this general principle (for example, pragma Import can eliminate the need for a completion), but the principle remains, and is strictly true at the syntactic level. Certainly any implementation-defined pragmas should obey this principle both syntactically and semantically, so that if the pragmas are not recognized by some other implementation, the program will remain legal. 

Syntax

2
pragma ::= 
   pragma identifier [(pragma_argument_association {, pragma_argument_association})];
3/3
{AI05-0290-1} pragma_argument_association ::= 
     [pragma_argument_identifier =>] name
   | [pragma_argument_identifier =>] expression
   | pragma_argument_aspect_mark =>  name
   | pragma_argument_aspect_mark =>  expression
4/3
{AI05-0290-1} In a pragma, any pragma_argument_associations without a pragma_argument_identifier or pragma_argument_aspect_mark shall precede any associations with a pragma_argument_identifier or pragma_argument_aspect_mark.
5
Pragmas are only allowed at the following places in a program: 
6/5
{AI12-0236-1} After a semicolon delimiter, but not within a formal_part, discriminant_part, or declare_expression.
7/3
{AI05-0100-1} {AI05-0163-1} At any place where the syntax rules allow a construct defined by a syntactic category whose name ends with “declaration”, “item”, “statement”, “clause”, or “alternative”, or one of the syntactic categories variant or exception_handler; but not in place of such a construct if the construct is required, or is part of a list that is required to have at least one such construct.
7.1/3
{AI05-0163-1} In place of a statement in a sequence_of_statements.
7.2/3
{AI05-0100-1} At any place where a compilation_unit is allowed. 
8
Additional syntax rules and placement restrictions exist for specific pragmas. 
8.a
Discussion: The above rule is written in text, rather than in BNF; the syntactic category pragma is not used in any BNF syntax rule. 
8.b
Ramification: A pragma is allowed where a generic_formal_parameter_declaration is allowed. 
9
The name of a pragma is the identifier following the reserved word pragma. The name or expression of a pragma_argument_association is a pragma argument.
9.a/2
To be honest: {AI95-00284-02} For compatibility with Ada 83, the name of a pragma may also be “interface”, which is not an identifier (because it is a reserved word). See J.12.
10/3
{AI05-0272-1} An identifier specific to a pragma is an identifier or reserved word that is used in a pragma argument with special meaning for that pragma. 
10.a
To be honest: Whenever the syntax rules for a given pragma allow "identifier" as an argument of the pragma, that identifier is an identifier specific to that pragma.
10.b/3
{AI05-0272-1} In a few cases, a reserved word is allowed as "an identifier specific to a pragma". Even in these cases, the syntax still is written as identifier (the reserved word(s) are not shown). For example, the restriction No_Use_Of_Attribute (see 13.12.1) allows the reserved words which can be attribute designators, but the syntax for a restriction does not include these reserved words. 

Static Semantics

11
If an implementation does not recognize the name of a pragma, then it has no effect on the semantics of the program. Inside such a pragma, the only rules that apply are the Syntax Rules. 
11.a
To be honest: This rule takes precedence over any other rules that imply otherwise. 
11.b
Ramification: Note well: this rule applies only to pragmas whose name is not recognized. If anything else is wrong with a pragma (at compile time), the pragma is illegal. This is true whether the pragma is language defined or implementation defined.
11.c
For example, an expression in an unrecognized pragma does not cause freezing, even though the rules in 13.14, “Freezing Rules” say it does; the above rule overrules those other rules. On the other hand, an expression in a recognized pragma causes freezing, even if this makes something illegal.
11.d
For another example, an expression that would be ambiguous is not illegal if it is inside an unrecognized pragma.
11.e
Note, however, that implementations have to recognize pragma Inline(Foo) and freeze things accordingly, even if they choose to never do inlining.
11.f
Obviously, the contradiction needs to be resolved one way or the other. The reasons for resolving it this way are: The implementation is simple — the compiler can just ignore the pragma altogether. The interpretation of constructs appearing inside implementation-defined pragmas is implementation defined. For example: “pragma Mumble(X);”. If the current implementation has never heard of Mumble, then it doesn't know whether X is a name, an expression, or an identifier specific to the pragma Mumble. 
11.g
To be honest: The syntax of individual pragmas overrides the general syntax for pragma.
11.h
Ramification: Thus, an identifier specific to a pragma is not a name, syntactically; if it were, the visibility rules would be invoked, which is not what we want.
11.i/3
{AI05-0229-1} This also implies that named associations do not allow one to give the arguments in an arbitrary order — the order given in the syntax rule for each individual pragma must be obeyed. However, it is generally possible to leave out earlier arguments when later ones are given; for example, this is allowed by the syntax rule for pragma Import (see J.15.5, “Interfacing Pragmas”). As for subprogram calls, positional notation precedes named notation.
11.j
Note that Ada 83 had no pragmas for which the order of named associations mattered, since there was never more than one argument that allowed named associations. 
11.k
To be honest: The interpretation of the arguments of implementation-defined pragmas is implementation defined. However, the syntax rules have to be obeyed. 

Dynamic Semantics

12
Any pragma that appears at the place of an executable construct is executed. Unless otherwise specified for a particular pragma, this execution consists of the evaluation of each evaluable pragma argument in an arbitrary order.
12.a
Ramification: For a pragma that appears at the place of an elaborable construct, execution is elaboration.
12.b
An identifier specific to a pragma is neither a name nor an expression — such identifiers are not evaluated (unless an implementation defines them to be evaluated in the case of an implementation-defined pragma).
12.c
The “unless otherwise specified” part allows us (and implementations) to make exceptions, so a pragma can contain an expression that is not evaluated. Note that pragmas in type_definitions may contain expressions that depend on discriminants.
12.d
When we wish to define a pragma with some run-time effect, we usually make sure that it appears in an executable context; otherwise, special rules are needed to define the run-time effect and when it happens. 

Implementation Requirements

13
The implementation shall give a warning message for an unrecognized pragma name. 
13.a
Ramification: An implementation is also allowed to have modes in which a warning message is suppressed, or in which the presence of an unrecognized pragma is a compile-time error. 

Implementation Permissions

14
An implementation may provide implementation-defined pragmas; the name of an implementation-defined pragma shall differ from those of the language-defined pragmas. 
14.a
Implementation defined: Implementation-defined pragmas.
14.b
Ramification: The semantics of implementation-defined pragmas, and any associated rules (such as restrictions on their placement or arguments), are, of course, implementation defined. Implementation-defined pragmas may have run-time effects. 
15
An implementation may ignore an unrecognized pragma even if it violates some of the Syntax Rules, if detecting the syntax error is too complex. 
15.a
Reason: Many compilers use extra post-parsing checks to enforce the syntax rules, since the Ada syntax rules are not LR(k) (for any k). (The grammar is ambiguous, in fact.) This paragraph allows them to ignore an unrecognized pragma, without having to perform such post-parsing checks. 

Implementation Advice

16/3
{AI05-0163-1} Normally, implementation-defined pragmas should have no semantic effect for error-free programs; that is, if the implementation-defined pragmas in a working program are replaced with unrecognized pragmas, the program should still be legal, and should still have the same semantics. 
16.a.1/2
Implementation Advice: Implementation-defined pragmas should have no semantic effect for error-free programs.
16.a
Ramification: Note that “semantics” is not the same as “effect;” as explained in 1.1.3, the semantics defines a set of possible effects.
16.b
Note that adding a pragma to a program might cause an error (either at compile time or at run time). On the other hand, if the language-specified semantics for a feature are in part implementation defined, it makes sense to support pragmas that control the feature, and that have real semantics; thus, this paragraph is merely a recommendation. 
17
Normally, an implementation should not define pragmas that can make an illegal program legal, except as follows: 
18/3
{AI05-0229-1} A pragma used to complete a declaration;
18.a/3
Discussion: {AI05-0229-1} There are no language-defined pragmas which can be completions; pragma Import was defined this way in Ada 95 and Ada 2005, but in Ada 2012 pragma Import just sets aspect Import which disallows having any completion.
19
A pragma used to configure the environment by adding, removing, or replacing library_items.
19.a.1/2
Implementation Advice: Implementation-defined pragmas should not make an illegal program legal, unless they complete a declaration or configure the library_items in an environment.
19.a
Ramification: For example, it is OK to support Interface, System_Name, Storage_Unit, and Memory_Size pragmas for upward compatibility reasons, even though all of these pragmas can make an illegal program legal. (The latter three can affect legality in a rather subtle way: They affect the value of named numbers in System, and can therefore affect the legality in cases where static expressions are required.)
19.b
On the other hand, adding implementation-defined pragmas to a legal program can make it illegal. For example, a common kind of implementation-defined pragma is one that promises some property that allows more efficient code to be generated. If the promise is a lie, it is best if the user gets an error message. 

Incompatibilities With Ada 83

19.c
In Ada 83, “bad” pragmas are ignored. In Ada 95, they are illegal, except in the case where the name of the pragma itself is not recognized by the implementation. 

Extensions to Ada 83

19.d
Implementation-defined pragmas may affect the legality of a program. 

Wording Changes from Ada 83

19.e
Implementation-defined pragmas may affect the run-time semantics of the program. This was always true in Ada 83 (since it was not explicitly forbidden by RM83), but it was not clear, because there was no definition of “executing” or “elaborating” a pragma.

Extensions to Ada 2005

19.f/3
{AI05-0163-1} Correction: Allow pragmas in place of a statement, even if there are no other statements in a sequence_of_statements.
19.g/3
{AI05-0272-1} Identifiers specific to a pragma can be reserved words.
19.h/3
{AI05-0290-1} Pragma arguments can be identified with aspect_marks; this allows identifier'Class in this context. As usual, this is only allowed if specifically allowed by a particular pragma. 

Wording Changes from Ada 2005

19.i/3
{AI05-0100-1} Correction: Clarified where pragmas are (and are not) allowed. 

Wording Changes from Ada 2012

19.j/5
{AI12-0236-1} Added wording to ensure that pragmas are not allowed in declare_expressions. We don't allow this as the definition of most pragmas assume that they're given between entities. We also don't want to answer questions about conformance of pragmas, especially unrecognized pragmas and pragmas whose state can change between the specification and body. 

Syntax

20
The forms of List, Page, and Optimize pragmas are as follows:
21
  pragma List(identifier);
22
  pragma Page;
23
  pragma Optimize(identifier);
24
[Other pragmas are defined throughout this Reference Manual, and are summarized in Annex L.] 
24.a
Ramification: The language-defined pragmas are supported by every implementation, although “supporting” some of them (for example, Inline) requires nothing more than checking the arguments, since they act only as advice to the implementation. 

Static Semantics

25
A pragma List takes one of the identifiers On or Off as the single argument. This pragma is allowed anywhere a pragma is allowed. It specifies that listing of the compilation is to be continued or suspended until a List pragma with the opposite argument is given within the same compilation. The pragma itself is always listed if the compiler is producing a listing.
26
A pragma Page is allowed anywhere a pragma is allowed. It specifies that the program text which follows the pragma should start on a new page (if the compiler is currently producing a listing).
27
A pragma Optimize takes one of the identifiers Time, Space, or Off as the single argument. This pragma is allowed anywhere a pragma is allowed, and it applies until the end of the immediately enclosing declarative region, or for a pragma at the place of a compilation_unit, to the end of the compilation. It gives advice to the implementation as to whether time or space is the primary optimization criterion, or that optional optimizations should be turned off. [It is implementation defined how this advice is followed.]
27.a
Implementation defined: Effect of pragma Optimize.
27.b
Discussion: For example, a compiler might use Time vs. Space to control whether generic instantiations are implemented with a macro-expansion model, versus a shared-generic-body model.
27.c
We don't define what constitutes an “optimization” — in fact, it cannot be formally defined in the context of Ada. One compiler might call something an optional optimization, whereas another compiler might consider that same thing to be a normal part of code generation. Thus, the programmer cannot rely on this pragma having any particular portable effect on the generated code. Some compilers might even ignore the pragma altogether. 

Examples

28
Examples of pragmas:
29/5
{AI95-00433-01} {AI05-0229-1} {AI12-0417-1} pragma List(Off); -- turn off listing generation
pragma Optimize(Off); -- turn off optional optimizations
pragma Assertion_Policy(Check); -- check assertions
pragma Assert(Exists(File_Name),
              Message => "Nonexistent file"); -- assert file exists

Extensions to Ada 83

29.a
The Optimize pragma now allows the identifier Off to request that normal optimization be turned off.
29.b
An Optimize pragma may appear anywhere pragmas are allowed. 

Wording Changes from Ada 83

29.c
We now describe the pragmas Page, List, and Optimize here, to act as examples, and to remove the normative material from Annex L, “Language-Defined Pragmas”, so it can be entirely an informative annex. 

Wording Changes from Ada 95

29.d/2
{AI95-00433-01} Updated the example of named pragma parameters, because the second parameter of pragma Suppress is obsolescent. 

Wording Changes from Ada 2005

29.e/3
{AI05-0229-1} Updated the example of pragmas, because both pragmas Inline and Import are obsolescent. 

Contents   Index   References   Search   Previous   Next 
Ada-Europe Ada 2005 and 2012 Editions sponsored in part by Ada-Europe