2.54 Pragma Eliminate

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.

• * If E is overloaded within U then, in the absence of a Source_Location argument, all overloadings are eliminated.
• * If 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.
• * If 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.
• * If 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).
• * If 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]");