Pragma Eliminate

Syntax:

     pragma Eliminate (
         [Unit_Name =>] IDENTIFIER |
                        SELECTED_COMPONENT);
     
     pragma Eliminate (
         [Unit_Name       =>]  IDENTIFIER |
                               SELECTED_COMPONENT,
         [Entity          =>]  IDENTIFIER |
                               SELECTED_COMPONENT |
                               STRING_LITERAL
       [,[Parameter_Types =>]  PARAMETER_TYPES]
       [,[Result_Type     =>]  result_SUBTYPE_NAME]
       [,[Homonym_Number  =>]  INTEGER_LITERAL]);
     
     PARAMETER_TYPES ::= (SUBTYPE_NAME {, SUBTYPE_NAME})
     SUBTYPE_NAME    ::= STRING_LITERAL

This pragma indicates that the given entity is not used outside the compilation unit it is defined in. The entity may be either a subprogram or a variable.

If the entity to be eliminated is a library level subprogram, then the first form of pragma Eliminate is used with only a single argument. In this form, the Unit_Name argument specifies the name of the library level unit to be eliminated.

In all other cases, both Unit_Name and Entity arguments are required. If item is an entity of a library package, then the first argument specifies the unit name, and the second argument specifies the particular entity. If the second argument is in string form, it must correspond to the internal manner in which GNAT stores entity names (see compilation unit Namet in the compiler sources for details).

The remaining parameters are optionally used to distinguish between overloaded subprograms. There are two ways of doing this.

Use Parameter_Types and Result_Type to specify the profile of the subprogram to be eliminated in a manner similar to that used for the extended Import and Export pragmas, except that the subtype names are always given as string literals, again corresponding to the internal manner in which GNAT stores entity names.

Alternatively, the Homonym_Number parameter is used to specify which overloaded alternative is to be eliminated. A value of 1 indicates the first subprogram (in lexical order), 2 indicates the second etc.

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 it is defined in, causes a compile time or link time error.

The parameters of this pragma may be given in any order, as long as the usual rules for use of named parameters and position parameters are used.

The intention of pragma Eliminate is to allow a program to be compiled in a system independent manner, with unused entities eliminated, without the requirement of modifying 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.

Note that the reason this pragma takes string literals where names might be expected is that a pragma Eliminate can appear in a context where the relevant names are not visible.