Syntax:
pragma Eliminate (
[ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT ,
[ Entity => ] IDENTIFIER |
SELECTED_COMPONENT |
STRING_LITERAL
[, Source_Location => SOURCE_TRACE ] );
SOURCE_TRACE ::= STRING_LITERAL
This pragma indicates that the given entity is not used in the program to be compiled and built, thus allowing the compiler to eliminate the code or data associated with the named entity. Any reference to an eliminated entity causes a compile-time or link-time error.
The pragma has the following semantics, where U is the unit specified by
the Unit_Name argument and E is the entity specified by the Entity
argument:
E must be a subprogram that is explicitly declared either:
o Within U, or
o Within a generic package that is instantiated in U, or
o As an instance of generic subprogram instantiated in U.
Otherwise the pragma is ignored.
E is overloaded within U then, in the absence of a
Source_Location argument, all overloadings are eliminated.
E is overloaded within U and only some overloadings
are to be eliminated, then each overloading to be eliminated
must be specified in a corresponding pragma Eliminate
with a Source_Location argument identifying the line where the
declaration appears, as described below.
E is declared as the result of a generic instantiation, then
a Source_Location argument is needed, as described below
Pragma Eliminate allows a program to be compiled in a system-independent
manner, so that unused entities are eliminated but without
needing to modify the source text. Normally the required set of
Eliminate pragmas is constructed automatically using the gnatelim tool.
Any source file change that removes, splits, or
adds lines may make the set of Eliminate pragmas invalid because their
Source_Location argument values may get out of date.
Pragma Eliminate may be used where the referenced entity is a dispatching
operation. In this case all the subprograms to which the given operation can
dispatch are considered to be unused (are never called as a result of a direct
or a dispatching call).
The string literal given for the source location specifies the line number
of the declaration of the entity, using the following syntax for SOURCE_TRACE:
SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ]
LBRACKET ::= '['
RBRACKET ::= ']'
SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER
LINE_NUMBER ::= DIGIT {DIGIT}
Spaces around the colon in a SOURCE_REFERENCE are optional.
The source trace that is given as the Source_Location must obey the
following rules (or else the pragma is ignored), where U is
the unit U specified by the Unit_Name argument and E is the
subprogram specified by the Entity argument:
FILE_NAME is the short name (with no directory
information) of the Ada source file for U, using the required syntax
for the underlying file system (e.g. case is significant if the underlying
operating system is case sensitive).
If U is a package and E is a subprogram declared in the package
specification and its full declaration appears in the package body,
then the relevant source file is the one for the package specification;
analogously if U is a generic package.
E is not declared in a generic instantiation (this includes
generic subprogram instances), the source trace includes only one source
line reference. LINE_NUMBER gives the line number of the occurrence
of the declaration of E within the source file (as a decimal literal
without an exponent or point).
E is declared by a generic instantiation, its source trace
(from left to right) starts with the source location of the
declaration of E in the generic unit and ends with the source
location of the instantiation, given in square brackets. This approach is
applied recursively with nested instantiations: the rightmost (nested
most deeply in square brackets) element of the source trace is the location
of the outermost instantiation, and the leftmost element (that is, outside
of any square brackets) is the location of the declaration of E in
the generic unit.
Examples:
pragma Eliminate (Pkg0, Proc); -- Eliminate (all overloadings of) Proc in Pkg0 pragma Eliminate (Pkg1, Proc, Source_Location => "pkg1.ads:8"); -- Eliminate overloading of Proc at line 8 in pkg1.ads -- Assume the following file contents: -- gen_pkg.ads -- 1: generic -- 2: type T is private; -- 3: package Gen_Pkg is -- 4: procedure Proc(N : T); -- ... ... -- ... end Gen_Pkg; -- -- q.adb -- 1: with Gen_Pkg; -- 2: procedure Q is -- 3: package Inst_Pkg is new Gen_Pkg(Integer); -- ... -- No calls on Inst_Pkg.Proc -- ... end Q; -- The following pragma eliminates Inst_Pkg.Proc from Q pragma Eliminate (Q, Proc, Source_Location => "gen_pkg.ads:4[q.adb:3]");