2.155 Pragma Source_File_Name

Syntax:

    pragma Source_File_Name (
      [Unit_Name   =>] unit_NAME,
      Spec_File_Name =>  STRING_LITERAL,
      [Index => INTEGER_LITERAL]);
    
    pragma Source_File_Name (
      [Unit_Name   =>] unit_NAME,
      Body_File_Name =>  STRING_LITERAL,
      [Index => INTEGER_LITERAL]);

Use this to override the normal naming convention. It is a configuration pragma, and so has the usual applicability of configuration pragmas (i.e., it applies to either an entire partition, or to all units in a compilation, or to a single unit, depending on how it is used. unit_name is mapped to file_name_literal. The identifier for the second argument is required, and indicates whether this is the file name for the spec or for the body.

The optional Index argument should be used when a file contains multiple units, and when you do not want to use gnatchop to separate then into multiple files (which is the recommended procedure to limit the number of recompilations that are needed when some sources change). For instance, if the source file source.ada contains

    package B is
    ...
    end B;
    
    with B;
    procedure A is
    begin
       ..
    end A;

you could use the following configuration pragmas:

    pragma Source_File_Name
      (B, Spec_File_Name => "source.ada", Index => 1);
    pragma Source_File_Name
      (A, Body_File_Name => "source.ada", Index => 2);

Note that the gnatname utility can also be used to generate those configuration pragmas.

Another form of the Source_File_Name pragma allows the specification of patterns defining alternative file naming schemes to apply to all files.

    pragma Source_File_Name
      (  [Spec_File_Name  =>] STRING_LITERAL
       [,[Casing          =>] CASING_SPEC]
       [,[Dot_Replacement =>] STRING_LITERAL]);
    
    pragma Source_File_Name
      (  [Body_File_Name  =>] STRING_LITERAL
       [,[Casing          =>] CASING_SPEC]
       [,[Dot_Replacement =>] STRING_LITERAL]);
    
    pragma Source_File_Name
      (  [Subunit_File_Name =>] STRING_LITERAL
       [,[Casing            =>] CASING_SPEC]
       [,[Dot_Replacement   =>] STRING_LITERAL]);
    
    CASING_SPEC ::= Lowercase | Uppercase | Mixedcase

The first argument is a pattern that contains a single asterisk indicating the point at which the unit name is to be inserted in the pattern string to form the file name. The second argument is optional. If present it specifies the casing of the unit name in the resulting file name string. The default is lower case. Finally the third argument allows for systematic replacement of any dots in the unit name by the specified string literal.

Note that Source_File_Name pragmas should not be used if you are using project files. The reason for this rule is that the project manager is not aware of these pragmas, and so other tools that use the projet file would not be aware of the intended naming conventions. If you are using project files, file naming is controlled by Source_File_Name_Project pragmas, which are usually supplied automatically by the project manager. A pragma Source_File_Name cannot appear after a Pragma Source_File_Name_Project.

For more details on the use of the Source_File_Name pragma, see the sections on Using Other File Names and Alternative File Naming Schemes' in the :title:`GNAT User's Guide.