Pragma Eliminate

Syntax:

     pragma Eliminate (UNIT_NAME, ENTITY, Source_Location => SOURCE_TRACE)
     
     UNIT_NAME        ::= IDENTIFIER |
                          SELECTED_COMPONENT,
     
     ENTITY           ::= IDENTIFIER |
                          SELECTED_COMPONENT,
     
     SOURCE_TRACE     ::= SOURCE_REFERENCE |
                          SOURCE_REFERENCE LBRACKET SOURCE_TRACE RBRACKET
     
     LBRACKET         ::= [
     RBRACKET         ::= ]
     
     SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER
     
     FILE_NAME        ::= STRING_LITERAL
     LINE_NUMBER      ::= INTEGER_LITERAL

This pragma indicates that the given entity is not used in the program to be compiled and built. The entity must be an explicitly declared subprogram; this includes generic subprogram instances and subprograms declared in generic package instances. Unit_Name must be the name of the compilation unit in which the entity is declared.

The Source_Location argument is used to resolve overloading in case more then one callable entity with the same name is declared in the given compilation unit. Each file name must be the short name of the source file (with no directory information). 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 starts from the source location in the instantiation and ends with the source location of the declaration of the corresponding entity in the generic unit. This approach is recursively used in case of nested instantiations: the leftmost element of the source trace is the location of the outermost instantiation, the next element is the location of the next (first nested) instantiation in the code of the corresponding generic unit, and so on.

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 outside the compilation unit where it is defined 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. Elimination of unused entities local to a compilation unit is automatic, without requiring the use of pragma Eliminate.

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).