From: charlet <charlet@138bc75d-0d04-0410-961f-82ee72b054a4>
Date: Fri, 24 Apr 2009 13:49:15 +0000 (+0000)
Subject: (pragma Source_File_Name): add missing documentation for the Index
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=892bc8308b7306f9c16e7ed32f9058efc06032d5;p=thirdparty%2Fgcc.git

(pragma Source_File_Name): add missing documentation for the Index
 argument.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@146723 138bc75d-0d04-0410-961f-82ee72b054a4
---

diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
index f3059ae6f4f9..81b6a1140bc4 100644
--- a/gcc/ada/gnat_rm.texi
+++ b/gcc/ada/gnat_rm.texi
@@ -4238,11 +4238,13 @@ Syntax:
 @smallexample @c ada
 pragma Source_File_Name (
   [Unit_Name   =>] unit_NAME,
-  Spec_File_Name =>  STRING_LITERAL);
+  Spec_File_Name =>  STRING_LITERAL,
+  [Index => INTEGER_LITERAL]);
 
 pragma Source_File_Name (
   [Unit_Name   =>] unit_NAME,
-  Body_File_Name =>  STRING_LITERAL);
+  Body_File_Name =>  STRING_LITERAL,
+  [Index => INTEGER_LITERAL]);
 @end smallexample
 
 @noindent
@@ -4254,6 +4256,36 @@ compilation, or to a single unit, depending on how it is used.
 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 @code{gnatchop} to separate then
+into multiple files (which is the recommended procedure to limit the
+number of recompilation that are needed when some sources change).
+For instance, if the source file @file{source.ada} contains
+
+@smallexample @c ada
+package B is
+...
+end B;
+
+with B;
+procedure A is
+begin
+   ..
+end A;
+@end smallexample
+
+you could use the following configuration pragmas:
+
+@smallexample @c ada
+pragma Source_File_Name
+  (B, Spec_File_Name => "source.ada", Index => 1);
+pragma Source_File_Name
+  (A, Body_File_Name => "source.ada", Index => 2);
+@end smallexample
+
+Note that the @code{gnatname} utility can also be used to generate those
+configuration pragmas.
+
 Another form of the @code{Source_File_Name} pragma allows
 the specification of patterns defining alternative file naming schemes
 to apply to all files.