Pragma Eliminate

Syntax:

     pragma Eliminate ([Entity          =>] DEFINING_DESIGNATOR,
                       [Source_Location =>] STRING_LITERAL);

The string literal given for the source location is a string which specifies the line number of the occurrence of the entity, using the syntax for SOURCE_TRACE given below:

      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 DEFINING_DESIGNATOR matches the defining designator used in an explicit subprogram declaration, where the entity name in this designator appears on the source line specified by the source location.

The source trace that is given as the Source_Location shall obey the following rules. The FILE_NAME is the short name (with no directory information) of an Ada source file, given using exactly the required syntax for the underlying file system (e.g. case is important if the underlying operating system is case sensitive). LINE_NUMBER gives the line number of the occurrence of the entity as a decimal literal without an exponent or point. If an entity is not declared in a generic instantiation (this includes generic subprogram instances), the source trace includes only one source reference. If an entity is declared inside a generic instantiation, its source trace (when parsing from left to right) starts with the source location of the declaration of the entity in the generic unit and ends with the source location of the instantiation (it is given in square brackets). This approach is recursively used in case of nested instantiations: the rightmost (nested most deeply in square brackets) element of the source trace is the location of the outermost instantiation, the next to left element is the location of the next (first nested) instantiation in the code of the corresponding generic unit, and so on, and the leftmost element (that is out of any square brackets) is the location of the declaration of the entity to eliminate in a generic unit.

Note that the Source_Location argument specifies which of a set of similarly named entities is being eliminated, dealing both with overloading, and also appearance of the same entity name in different scopes.

This pragma indicates that the given entity is not used in the program to be compiled and built. The effect of the pragma is to allow 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 intention of pragma Eliminate is to allow a program to be compiled in a system-independent manner, with unused entities eliminated, 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).