2.8 Pragmas
1
{Pragma}
[Glossary Entry]
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.
Syntax
2
pragma ::=
pragma identifier [(
pragma_argument_association {,
pragma_argument_association})];
3
pragma_argument_association ::=
[
pragma_argument_identifier =>]
name
| [
pragma_argument_identifier =>]
expression
4
In a pragma, any
pragma_argument_associations without a pragma_argument_identifier
shall precede any associations with a pragma_argument_identifier.
5
Pragmas
are only allowed at the following places in a program:
6
- After a semicolon delimiter,
but not within a formal_part or discriminant_part.
7
- At any place where the
syntax rules allow a construct defined by a syntactic category whose
name ends with "declaration", "statement",
"clause", or "alternative",
or one of the syntactic categories variant
or exception_handler; but not in place of
such a construct. Also at any place where a compilation_unit
would be 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
{name (of a pragma)}
{pragma name}
The
name of a
pragma
is the identifier following the reserved word
pragma.
{pragma
argument} {argument
of a 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
{identifier specific
to a pragma} {pragma,
identifier specific to} An
identifier
specific to a pragma is an identifier 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.
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
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
B.1, “
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
{execution (pragma)
[partial]} {elaboration
(pragma) [partial]} 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
Normally, implementation-defined pragmas should have
no semantic effect for error-free programs; that is, if the implementation-defined
pragmas are removed from a working program, 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
- A pragma
used to complete a declaration, such as a pragma
Import;
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
{
incompatibilities with Ada 83}
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
{
extensions to Ada 83}
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.
Syntax
20
The forms of
List, Page, and Optimize pragmas are as follows:
21
22
23
pragma Optimize(
identifier);
24
[Other pragmas are defined throughout this
International Standard, 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/2
{
AI-00433-01}
pragma List(Off); --
turn off listing generation
pragma Optimize(Off); --
turn off optional optimizations
pragma Inline(Set_Mask); --
generate code for Set_Mask inline
pragma Import(C, Put_Char, External_Name => "putchar"); -- import C putchar function pragma Suppress(Range_Check, On => Index); -- turn off range checking on IndexExtensions to Ada 83
29.a
{
extensions to Ada 83}
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
{
AI-00433-01}
Updated the example of named pragma parameters,
because the second parameter of pragma Suppress
is obsolescent.
Sponsored by Ada-Europe