Update documentation.

From-SVN: r237979

gcc/ada/ChangeLog

 2016-07-04  Arnaud Charlet  <charlet@adacore.com>
 
+	* gnat_rm.texi, gnat_ugn.texi,
+	doc/gnat_ugn/gnat_project_manager.rst,
+	doc/gnat_ugn/building_executable_programs_with_gnat.rst,
+	doc/gnat_ugn/elaboration_order_handling_in_gnat.rst,
+	doc/gnat_ugn/about_this_guide.rst,
+	doc/gnat_ugn/platform_specific_information.rst,
+	doc/gnat_ugn/tools_supporting_project_files.rst,
+	doc/gnat_ugn/gnat_and_program_execution.rst,
+	doc/gnat_ugn/gnat_utility_programs.rst,
+	doc/gnat_ugn/the_gnat_compilation_model.rst,
+	doc/gnat_rm/implementation_defined_attributes.rst,
+	doc/gnat_rm/implementation_defined_pragmas.rst,
+	doc/gnat_rm/representation_clauses_and_pragmas.rst,
+	doc/gnat_rm/standard_and_implementation_defined_restrictions.rst,
+	doc/gnat_ugn.rst: Update documentation.
+
+2016-07-04  Arnaud Charlet  <charlet@adacore.com>
+
 	* gcc-interface/Makefile.in: Cleanups.
 
 2016-07-04  Ed Schonberg  <schonberg@adacore.com>

gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst

@@ -966,9 +966,6 @@ types. This may be overridden for the derived type by giving an explicit scalar
 storage order for the derived type. For a record extension, the derived type
 must have the same scalar storage order as the parent type.
 
-If a component of `T` is of a record or array type, then that type must
-also have a `Scalar_Storage_Order` attribute definition clause.
-
 A component of a record or array type that is a bit-packed array, or that
 does not start on a byte boundary, must have the same scalar storage order
 as the enclosing record or array type.
@@ -1005,6 +1002,11 @@ inheritance in the case of a derived type), then the default is normally
 the native ordering of the target, but this default can be overridden using
 pragma `Default_Scalar_Storage_Order`.
 
+Note that if a component of `T` is itself of a record or array type,
+the specfied `Scalar_Storage_Order` does *not* apply to that nested type:
+an explicit attribute definition clause must be provided for the component
+type as well if desired.
+
 Note that the scalar storage order only affects the in-memory data
 representation. It has no effect on the representation used by stream
 attributes.

gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst

@@ -196,7 +196,7 @@ Ada 83, Ada 95, or Ada 2005 programs.
 The one argument form, which is not a configuration pragma,
 is used for managing the transition from Ada
 2005 to Ada 2012 in the run-time library. If an entity is marked
-as Ada_201 only, then referencing the entity in any pre-Ada_2012
+as Ada_2012 only, then referencing the entity in any pre-Ada_2012
 mode will generate a warning. In addition, in any pre-Ada_2012
 mode, a preference rule is established which does not choose
 such an entity unless it is unambiguously specified. This avoids
@@ -6821,6 +6821,40 @@ the handling of existing code which depends on the interpretation of Size
 as implemented in the VADS compiler.  See description of the VADS_Size
 attribute for further details.
 
+.. _Pragma-Unused:
+
+Pragma Unused
+=============
+.. index:: Warnings, unused
+
+Syntax:
+
+
+::
+
+  pragma Unused (LOCAL_NAME {, LOCAL_NAME});
+
+
+This pragma signals that the assignable entities (variables,
+`out` parameters, and `in out` parameters) whose names are listed
+deliberately do not get assigned or referenced in the current source unit
+after the occurrence of the pragma in the current source unit. This
+suppresses warnings about the entities that are unreferenced and/or not
+assigned, and, in addition, a warning will be generated if one of these
+entities gets assigned or subsequently referenced in the same unit as the
+pragma (in the corresponding body or one of its subunits).
+
+This is particularly useful for clearly signaling that a particular
+parameter is not modified or referenced, even though the spec suggests
+that it might be.
+
+For the variable case, warnings are never given for unreferenced
+variables whose name contains one of the substrings
+`DISCARD, DUMMY, IGNORE, JUNK, UNUSED` in any casing. Such names
+are typically to be used in cases where such warnings are expected.
+Thus it is never necessary to use `pragma Unmodified` for such
+variables, though it is harmless to do so. 
+
 Pragma Validity_Checks
 ======================
 

gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst

@@ -53,9 +53,9 @@ values are as follows:
   For arrays, the alignment is equal to the alignment of the component type
   for the normal case where no packing or component size is given.  If the
   array is packed, and the packing is effective (see separate section on
-  packed arrays), then the alignment will be either 4, 2 or 1 for long packed
+  packed arrays), then the alignment will be either 4, 2, or 1 for long packed
   arrays or arrays whose length is not known at compile time, depending on
-  whether the component size is divisible by 4, 2 or is odd.  For short packed
+  whether the component size is divisible by 4, 2, or is odd.  For short packed
   arrays, which are handled internally as modular types, the alignment
   will be as described for elementary types, e.g. a packed array of length
   31 bits will have an object size of four bytes, and an alignment of 4.
@@ -490,7 +490,7 @@ discrete types are as follows:
   The `Object_Size` for base subtypes reflect the natural hardware
   size in bits (run the compiler with *-gnatS* to find those values
   for numeric types). Enumeration types and fixed-point base subtypes have
-  8, 16, 32 or 64 bits for this size, depending on the range of values
+  8, 16, 32, or 64 bits for this size, depending on the range of values
   to be stored.
 
 *
@@ -1187,7 +1187,7 @@ taken by components.  We distinguish between *packable* components and
 Components of the following types are considered packable:
 
 * Components of an elementary type are packable unless they are aliased,
-  independent or of an atomic type.
+  independent, or of an atomic type.
 
 * Small packed arrays, where the size is statically known, are represented
   internally as modular integers, and so they are also packable.

gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst

@@ -445,20 +445,6 @@ No_Implicit_Heap_Allocations
 
 [RM D.7] No constructs are allowed to cause implicit heap allocation.
 
-No_Implicit_Loops
------------------
-.. index:: No_Implicit_Loops
-
-[GNAT] This restriction ensures that the generated code does not contain any
-implicit `for` loops, either by modifying
-the generated code where possible,
-or by rejecting any construct that would otherwise generate an implicit
-`for` loop. If this restriction is active, it is possible to build
-large array aggregates with all static components without generating an
-intermediate temporary, and without generating a loop to initialize individual
-components. Otherwise, a loop is created for arrays larger than about 5000
-scalar components.
-
 No_Implicit_Protected_Object_Allocations
 ----------------------------------------
 .. index:: No_Implicit_Protected_Object_Allocations
@@ -969,6 +955,20 @@ Unrestricted_Access is forbidden is that it would require the prefix
 to be aliased, and in such cases, it can always be replaced by
 the standard attribute Unchecked_Access which is preferable.
 
+No_Implicit_Loops
+-----------------
+.. index:: No_Implicit_Loops
+
+[GNAT] This restriction ensures that the generated code of the unit marked
+with this restriction does not contain any implicit `for` loops, either by
+modifying the generated code where possible, or by rejecting any construct
+that would otherwise generate an implicit `for` loop. If this restriction is
+active, it is possible to build large array aggregates with all static
+components without generating an intermediate temporary, and without generating
+a loop to initialize individual components. Otherwise, a loop is created for
+arrays larger than about 5000 scalar components. Note that if this restriction
+is set in the spec of a package, it will not apply to its body.
+
 No_Obsolescent_Features
 -----------------------
 .. index:: No_Obsolescent_Features

gcc/ada/doc/gnat_ugn.rst

@@ -42,8 +42,6 @@ included in the section entitled :ref:`gnu_fdl`.
    gnat_ugn/getting_started_with_gnat
    gnat_ugn/the_gnat_compilation_model
    gnat_ugn/building_executable_programs_with_gnat
-   gnat_ugn/gnat_project_manager
-   gnat_ugn/tools_supporting_project_files
    gnat_ugn/gnat_utility_programs
    gnat_ugn/gnat_and_program_execution
 

gcc/ada/doc/gnat_ugn/about_this_guide.rst

@@ -37,12 +37,6 @@ This guide contains the following chapters:
   main GNAT tools to build executable programs, and it also gives examples of
   using the GNU make utility with GNAT.
 
-* :ref:`GNAT_Project_Manager` describes how to use project files
-  to organize large projects.
-  
-* :ref:`Tools_Supporting_Project_Files` described how to use the project
-  facility in conjunction with various GNAT tools.
-
 * :ref:`GNAT_Utility_Programs` explains the various utility programs that
   are included in the GNAT environment
 

gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst

@@ -27,6 +27,15 @@ Finally, this chapter provides examples of
 how to make use of the general GNU make mechanism
 in a GNAT context (see :ref:`Using_the_GNU_make_Utility`).
 
+.. only:: PRO or GPL
+  
+   For building large systems with components possibly written
+   in different languages (such as Ada, C, C++ and Fortran)
+   and organized into subsystems and libraries, the GPRbuild
+   tool can be used. This tool, and the Project Manager
+   facility that it is based upon, is described in
+   *GPRbuild and GPR Companion Tools User's Guide*.
+	  
 
 .. _The_GNAT_Make_Program_gnatmake:
 
@@ -67,8 +76,9 @@ changes to the source program cause corresponding changes in
 dependencies, they will always be tracked exactly correctly by
 *gnatmake*.
 
-Note that for advanced description of project structure, we recommend creating
-a project file as explained in :ref:`GNAT_Project_Manager` and use the
+Note that for advanced forms of project structure, we recommend creating
+a project file as explained in the *GNAT_Project_Manager* chapter in the
+*GPRbuild User's Guide*, and using the
 *gprbuild* tool which supports building with project files and works similarly
 to *gnatmake*.
 
@@ -516,6 +526,8 @@ You may specify any of the following switches to *gnatmake*:
 
 :samp:`-P{project}`
   Use project file `project`. Only one such switch can be used.
+
+.. -- Comment:  
   :ref:`gnatmake_and_Project_Files`.
 
 
@@ -545,8 +557,10 @@ You may specify any of the following switches to *gnatmake*:
 :samp:`-u`
   Unique. Recompile at most the main files. It implies -c. Combined with
   -f, it is equivalent to calling the compiler directly. Note that using
-  -u with a project file and no main has a special meaning
-  (:ref:`Project_Files_and_Main_Subprograms`).
+  -u with a project file and no main has a special meaning.
+
+.. --Comment:
+  (See :ref:`Project_Files_and_Main_Subprograms`.)
 
 
 .. index:: -U  (gnatmake)

gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst

@@ -75,7 +75,7 @@ of that unit before elaborating the unit doing the |withing|:
 
      with Unit_1;
      package Unit_2 is ...
-  
+
 would require that both the body and spec of `Unit_1` be elaborated
 before the spec of `Unit_2`. However, a rule like that would be far too
 restrictive. In particular, it would make it impossible to have routines
@@ -94,7 +94,7 @@ of the body of `Unit_1`:
 .. code-block:: ada
 
      Sqrt_1 : Float := Sqrt (0.1);
-  
+
 The elaboration code of the body of `Unit_1` also contains:
 
 .. code-block:: ada
@@ -111,7 +111,7 @@ the body `Unit_2`:
 .. code-block:: ada
 
       Sqrt_2 : Float := Sqrt (0.1);
-  
+
 The elaboration code of the body of `Unit_2` also contains:
 
 .. code-block:: ada
@@ -119,7 +119,7 @@ The elaboration code of the body of `Unit_2` also contains:
      if expression_2 = 2 then
         Q := Unit_1.Func_1;
      end if;
-  
+
 Now the question is, which of the following orders of elaboration is
 acceptable:
 
@@ -129,7 +129,7 @@ acceptable:
      Spec of Unit_2
      Body of Unit_1
      Body of Unit_2
-  
+
 or
 
 ::
@@ -138,7 +138,7 @@ or
      Spec of Unit_1
      Body of Unit_2
      Body of Unit_1
-  
+
 If you carefully analyze the flow here, you will see that you cannot tell
 at compile time the answer to this question.
 If `expression_1` is not equal to 1,
@@ -378,7 +378,7 @@ order of elaboration of the servers on which they depend:
 
         Unit A |withs| unit B and calls B.Func in elab code
         Unit B |withs| unit C, and B.Func calls C.Func
-    
+
 
   Now if we put a pragma `Elaborate (B)`
   in unit `A`, this ensures that the
@@ -481,14 +481,14 @@ example writing:
 .. code-block:: ada
 
      function One return Float;
- 
+
      Q : Float := One;
-  
+
      function One return Float is
      begin
           return 1.0;
      end One;
-  
+
 will obviously raise `Program_Error` at run time, because function
 One will be called before its body is elaborated. In this case GNAT will
 generate a warning that the call will raise `Program_Error`::
@@ -510,7 +510,7 @@ generate a warning that the call will raise `Program_Error`::
     11. begin
     12.    null;
     13. end;
-  
+
 
 Note that in this particular case, it is likely that the call is safe, because
 the function `One` does not access any global variables.
@@ -527,7 +527,7 @@ would prevent this reordering, and if we write:
 .. code-block:: ada
 
      function One return Float;
- 
+
      function One return Float is
      begin
           return 1.0;
@@ -586,7 +586,7 @@ raised at the point of the call. Let's look at the warning::
     13. begin
     14.    null;
     15. end;
-  
+
 
 Note that the message here says 'may raise', instead of the direct case,
 where the message says 'will be raised'. That's because whether
@@ -677,7 +677,7 @@ Consider the following:
       begin
          ...
       end Main;
-  
+
 where `Main` is the main program. When this program is executed, the
 elaboration code must first be executed, and one of the jobs of the
 binder is to determine the order in which the units of a program are
@@ -813,7 +813,7 @@ switch, then the compiler outputs an information message::
                           |
         >>> info: call to "r" may raise Program_Error
         >>> info: missing pragma Elaborate_All for "k"
-   
+
      4. end;
 
 and these messages can be used as a guide for supplying manually
@@ -840,7 +840,7 @@ the *-gnatE* switch on the compiler (*gcc* or
 .. code-block:: ada
 
       pragma Elaboration_Checks (DYNAMIC);
-  
+
 Either approach will cause the unit affected to be compiled using the
 standard dynamic run-time elaboration checks described in the Ada
 Reference Manual. The static model is generally preferable, since it
@@ -976,7 +976,7 @@ the following example
       begin
          Decls.Lib_Task.Start;
       end;
-  
+
 If the above example is compiled in the default static elaboration
 mode, then a circularity occurs. The circularity comes from the call
 `Utils.Put_Val` in the task body of `Decls.Lib_Task`. Since
@@ -1112,7 +1112,7 @@ We have four possible answers to this question:
       begin
          Decls1.Lib_Task.Start;
       end;
-    
+
 
   All we have done is to split `Decls` into two packages, one
   containing the library task, and one containing everything else. Now
@@ -1179,7 +1179,7 @@ We have four possible answers to this question:
       begin
          Declst.Lib_Task.Start;
       end;
-    
+
 
   What we have done here is to replace the `task` declaration in
   package `Decls` with a `task type` declaration. Then we
@@ -1227,7 +1227,7 @@ We have four possible answers to this question:
   .. code-block:: ada
 
       pragma Restrictions (No_Entry_Calls_In_Elaboration_Code);
-    
+
   This pragma can be placed in the :file:`gnat.adc` file in the usual
   manner. If we take our original unmodified program and compile it
   in the presence of a :file:`gnat.adc` containing the above pragma,
@@ -1288,7 +1288,7 @@ similar to that in the following example::
 
      warning: "x.ads" has dynamic elaboration checks and with's
      warning:   "y.ads" which has static elaboration checks
- 
+
 These warnings indicate that the rule has been violated, and that as a result
 elaboration checks may be missed in the resulting executable file.
 This warning may be suppressed using the *-ws* binder switch
@@ -1456,7 +1456,7 @@ Faced with a circularity of this kind, you have three different options.
         begin
           Ada.Text_IO.Put_Line(Pack1.X1'Img); -- 101
         end Proc3;
-    
+
   In the absence of any pragmas, an attempt to bind this program produces
   the following diagnostics::
 
@@ -1473,7 +1473,7 @@ Faced with a circularity of this kind, you have three different options.
        info:          "pack2 (spec)"
        info:             which is withed by:
        info:          "pack1 (body)"
-    
+
   The sources of the circularity are the two calls to `Pack2.Pure` and
   `Pack2.F2` in the body of `Pack1`. We can see that the call to
   F2 is safe, even though F2 calls F1, because the call appears after the
@@ -1541,19 +1541,24 @@ fall back to run-time checks; premature calls to any primitive
 operation of a tagged type before the body of the operation has been
 elaborated will raise `Program_Error`.
 
-Access-to-subprogram types, however, are handled conservatively, and
-do not require run-time checks. This was not true in earlier versions
-of the compiler; you can use the *-gnatd.U* debug switch to
-revert to the old behavior if the new conservative behavior causes
-elaboration cycles. Here, 'conservative' means that if you do
-`P'Access` during elaboration, the compiler will assume that you
-might call `P` indirectly during elaboration, so it adds an
-implicit `pragma Elaborate_All` on the library unit containing
-`P`. The *-gnatd.U* switch is safe if you know there are
-no such calls. If the program worked before, it will continue to work
-with *-gnatd.U*. But beware that code modifications such as
-adding an indirect call can cause erroneous behavior in the presence
-of *-gnatd.U*.
+Access-to-subprogram types, however, are handled conservatively in many
+cases. This was not true in earlier versions of the compiler; you can use
+the *-gnatd.U* debug switch to revert to the old behavior if the new
+conservative behavior causes elaboration cycles. Here, 'conservative' means
+that if you do `P'Access` during elaboration, the compiler will normally
+assume that you might call `P` indirectly during elaboration, so it adds an
+implicit `pragma Elaborate_All` on the library unit containing `P`. The
+*-gnatd.U* switch is safe if you know there are no such calls. If the
+program worked before, it will continue to work with *-gnatd.U*. But beware
+that code modifications such as adding an indirect call can cause erroneous
+behavior in the presence of *-gnatd.U*.
+
+These implicit Elaborate_All pragmas are not added in all cases, because
+they cause elaboration cycles in certain common code patterns. If you want
+even more conservative handling of P'Access, you can use the *-gnatd.o*
+switch.
+
+See `debug.adb` for documentation on the *-gnatd...* debug switches.
 
 
 .. _Summary_of_Procedures_for_Elaboration_Control:
@@ -1564,7 +1569,7 @@ Summary of Procedures for Elaboration Control
 .. index:: Elaboration control
 
 First, compile your program with the default options, using none of
-the special elaboration control switches. If the binder successfully
+the special elaboration-control switches. If the binder successfully
 binds your program, then you can be confident that, apart from issues
 raised by the use of access-to-subprogram types and dynamic dispatching,
 the program is free of elaboration errors. If it is important that the
@@ -1621,7 +1626,7 @@ requirements. Consider this example:
      package Init_Constants is
         procedure P; --* require a body*
      end Init_Constants;
- 
+
      with Constants;
      package body Init_Constants is
         procedure P is begin null; end;
@@ -1641,7 +1646,7 @@ requirements. Consider this example:
      begin
         Put_Line (Calc.Z'Img);
      end Main;
-  
+
 In this example, there is more than one valid order of elaboration. For
 example both the following are correct orders::
 
@@ -1654,13 +1659,13 @@ example both the following are correct orders::
 and
 
 ::
-  
+
     Init_Constants spec
     Init_Constants body
     Constants spec
     Calc spec
     Main body
-  
+
 There is no language rule to prefer one or the other, both are correct
 from an order of elaboration point of view. But the programmatic effects
 of the two orders are very different. In the first, the elaboration routine
@@ -1684,7 +1689,7 @@ case, that could have been achieved by adding to the spec of Calc:
 .. code-block:: ada
 
      pragma Elaborate_All (Constants);
-  
+
 which requires that the body (if any) and spec of `Constants`,
 as well as the body and spec of any unit |withed| by
 `Constants` be elaborated before `Calc` is elaborated.
@@ -1719,7 +1724,7 @@ following output:
      $ gnatmake -f -q main -bargs -p
      $ main
       0
-  
+
 It is of course quite unlikely that both these results are correct, so
 it is up to you in a case like this to investigate the source of the
 difference, by looking at the two elaboration orders that are chosen,
@@ -1768,7 +1773,7 @@ the last part of the file:`b~xxx.adb` binder output file. Here is an example::
      Ada.Text_Io'Elab_Spec;
      Ada.Text_Io'Elab_Body;
      E07 := True;
-  
+
 Here Elab_Spec elaborates the spec
 and Elab_Body elaborates the body. The assignments to the :samp:`E{xx}` flags
 flag that the corresponding body is now elaborated.

gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst

@@ -2605,6 +2605,14 @@ appropriate options.
   subprograms and helps the compiler to create a smaller executable for your
   program.
 
+  *gnatelim* is a project-aware tool.
+  (See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
+  the project-related switches but note that *gnatelim* does not support
+  the :samp:`-U`, :samp:`-U {main_unit}`, :samp:`--subdirs={dir}`, or
+  :samp:`--no_objects_dir` switches.)
+  The project file package that can specify
+  *gnatelim* switches is named ``Eliminate``.
+
   .. _About_gnatelim:
 
   About `gnatelim`

gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst

@@ -19,6 +19,9 @@ This chapter describes a number of utility programs:
   * :ref:`The_Body_Stub_Generator_gnatstub`
   * :ref:`The_Unit_Test_Generator_gnattest`
 
+  It also describes how several of these tools can be used in conjunction
+  with project files: :ref:`Using_Project_Files_with_GNAT_Tools`
+
 .. only:: FSF
 
   * :ref:`The_File_Cleanup_Utility_gnatclean`
@@ -629,7 +632,8 @@ The following switches are available for *gnatxref*:
 .. index:: -pFILE (gnatxref)
 
 :samp:`p{FILE}`
-  Specify a project file to use :ref:`GNAT_Project_Manager`.
+  Specify a project file to use (see the *GNAT_Project_Manager*
+  chapter in the *GPRbuild User's Guide*).
   If you need to use the :file:`.gpr`
   project files, you should use gnatxref through the GNAT driver
   (*gnat xref -Pproject*).
@@ -832,7 +836,8 @@ The following switches are available:
 .. index:: -pFILE (gnatfind)
 
 :samp:`p{FILE}`
-  Specify a project file (:ref:`GNAT_Project_Manager`) to use.
+  Specify a project file (see the *GNAT_Project_Manager* chapter in the
+  *GPRbuild User's Guide*).
   By default, `gnatxref` and `gnatfind` will try to locate a
   project file in the current directory.
 
@@ -1379,6 +1384,11 @@ Alternatively, you may run the script using the following command line:
   The *gnat2xml* tool is an ASIS-based utility that converts
   Ada source code into XML.
 
+  *gnat2xml* is a project-aware tool
+  (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
+  the project-related switches).  The project file package that can specify
+  *gnat2xml* switches is named ``gnat2xml``.
+
   .. _Switches_for_*gnat2xml*:
 
   Switches for *gnat2xml*
@@ -1823,15 +1833,12 @@ Alternatively, you may run the script using the following command line:
   The *gnatcheck* tool is an ASIS-based utility that checks properties
   of Ada source files according to a given set of semantic rules.
 
-  In order to check compliance with a given rule, *gnatcheck* has to
-  semantically analyze the Ada sources.
-  Therefore, checks can only be performed on
-  legal Ada units. Moreover, when a unit depends semantically upon units located
-  outside the current directory, the source search path has to be provided when
-  calling *gnatcheck*, either through a specified project file or
-  through *gnatcheck* switches.
+  *gnatcheck* is a project-aware tool
+  (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
+  the project-related switches).  The project file package that can specify
+  *gnatcheck* switches is named ``Check``.
 
-  For full details, refer to :title:`GNATcheck Reference Manual`.
+  For full details, plese refer to :title:`GNATcheck Reference Manual`.
 
 
 
@@ -1851,6 +1858,11 @@ Alternatively, you may run the script using the following command line:
   metrics data as output. Various switches control which
   metrics are computed and output.
 
+  *gnatmetric* is a project-aware tool
+  (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
+  the project-related switches).  The project file package that can specify
+  *gnatmetric* switches is named ``Metrics``.
+
   To compute program metrics, *gnatmetric* invokes the Ada
   compiler and generates and uses the ASIS tree for the input source;
   thus the input must be legal Ada code, and the tool should have all the
@@ -2095,71 +2107,71 @@ Alternatively, you may run the script using the following command line:
   .. index:: --no-lines (gnatmetric)
 
 
-  :samp:`-lines-all`
+  :samp:`--lines-all`
     Report all the line metrics
 
 
-  :samp:`-no-lines-all`
+  :samp:`--no-lines-all`
     Do not report any of line metrics
 
 
-  :samp:`-lines`
+  :samp:`--lines`
     Report the number of all lines
 
 
-  :samp:`-no-lines`
+  :samp:`--no-lines`
     Do not report the number of all lines
 
 
-  :samp:`-lines-code`
+  :samp:`--lines-code`
     Report the number of code lines
 
 
-  :samp:`-no-lines-code`
+  :samp:`--no-lines-code`
     Do not report the number of code lines
 
 
-  :samp:`-lines-comment`
+  :samp:`--lines-comment`
     Report the number of comment lines
 
 
-  :samp:`-no-lines-comment`
+  :samp:`--no-lines-comment`
     Do not report the number of comment lines
 
 
-  :samp:`-lines-eol-comment`
+  :samp:`--lines-eol-comment`
     Report the number of code lines containing
     end-of-line comments
 
 
-  :samp:`-no-lines-eol-comment`
+  :samp:`--no-lines-eol-comment`
     Do not report the number of code lines containing
     end-of-line comments
 
 
-  :samp:`-lines-ratio`
+  :samp:`--lines-ratio`
     Report the comment percentage in the program text
 
 
-  :samp:`-no-lines-ratio`
+  :samp:`--no-lines-ratio`
     Do not report the comment percentage in the program text
 
 
-  :samp:`-lines-blank`
+  :samp:`--lines-blank`
     Report the number of blank lines
 
 
-  :samp:`-no-lines-blank`
+  :samp:`--no-lines-blank`
     Do not report the number of blank lines
 
 
-  :samp:`-lines-average`
+  :samp:`--lines-average`
     Report the average number of code lines in subprogram bodies, task bodies,
     entry bodies and statement sequences in package bodies. The metric is computed
     and reported for the whole set of processed Ada sources only.
 
 
-  :samp:`-no-lines-average`
+  :samp:`--no-lines-average`
     Do not report the average number of code lines in subprogram bodies,
     task bodies, entry bodies and statement sequences in package bodies.
 
@@ -2204,6 +2216,15 @@ Alternatively, you may run the script using the following command line:
       maximum nesting level in the GNAT built-in style checks
       (see :ref:`Style_Checking`)
 
+  * *Number of formal parameters*
+      Number of formal parameters of a subprogram; if a subprogram does have
+      parameters, then numbers of "in", "out" and "in out" parameters are also
+      reported. This metric is reported for subprogram specifications and for
+      subprogram instantiations. For subprogram bodies, expression functions
+      and null procedures this metric is reported if the construct acts as a
+      subprogram declaration but is not a completion of previous declaration.
+      This metric is not reported for generic and formal subprograms.
+
   For the outermost unit in the file, *gnatmetric* additionally computes
   the following metrics:
 
@@ -2263,77 +2284,84 @@ Alternatively, you may run the script using the following command line:
   .. index:: --no-syntax (gnatmetric)
 
 
-  :samp:`-syntax-all`
+  :samp:`--syntax-all`
     Report all the syntax metrics
 
 
-  :samp:`-no-syntax-all`
+  :samp:`--no-syntax-all`
     Do not report any of syntax metrics
 
 
-  :samp:`-declarations`
+  :samp:`--declarations`
     Report the total number of declarations
 
 
-  :samp:`-no-declarations`
+  :samp:`--no-declarations`
     Do not report the total number of declarations
 
 
-  :samp:`-statements`
+  :samp:`--statements`
     Report the total number of statements
 
 
-  :samp:`-no-statements`
+  :samp:`--no-statements`
     Do not report the total number of statements
 
 
-  :samp:`-public-subprograms`
+  :samp:`--public-subprograms`
     Report the number of public subprograms in a compilation unit
 
 
-  :samp:`-no-public-subprograms`
+  :samp:`--no-public-subprograms`
     Do not report the number of public subprograms in a compilation unit
 
 
-  :samp:`-all-subprograms`
+  :samp:`--all-subprograms`
     Report the number of all the subprograms in a compilation unit
 
 
-  :samp:`-no-all-subprograms`
+  :samp:`--no-all-subprograms`
     Do not report the number of all the subprograms in a compilation unit
 
 
-  :samp:`-public-types`
+  :samp:`--public-types`
     Report the number of public types in a compilation unit
 
 
-  :samp:`-no-public-types`
+  :samp:`--no-public-types`
     Do not report the number of public types in a compilation unit
 
 
-  :samp:`-all-types`
+  :samp:`--all-types`
     Report the number of all the types in a compilation unit
 
 
-  :samp:`-no-all-types`
+  :samp:`--no-all-types`
     Do not report the number of all the types in a compilation unit
 
 
-  :samp:`-unit-nesting`
+  :samp:`--unit-nesting`
     Report the maximal program unit nesting level
 
 
-  :samp:`-no-unit-nesting`
+  :samp:`--no-unit-nesting`
     Do not report the maximal program unit nesting level
 
 
-  :samp:`-construct-nesting`
+  :samp:`--construct-nesting`
     Report the maximal construct nesting level
 
 
-  :samp:`-no-construct-nesting`
+  :samp:`--no-construct-nesting`
     Do not report the maximal construct nesting level
 
+  :samp:`--param-number`
+    Report the number of subprogram parameters
+
+
+  :samp:`--no-param-number`
+    Do not report the number of subprogram parameters
+
 
   .. _Complexity_Metrics_Control:
 
@@ -2420,31 +2448,31 @@ Alternatively, you may run the script using the following command line:
   .. index:: --no-complexity (gnatmetric)
 
 
-  :samp:`-complexity-all`
+  :samp:`--complexity-all`
     Report all the complexity metrics
 
 
-  :samp:`-no-complexity-all`
+  :samp:`--no-complexity-all`
     Do not report any of complexity metrics
 
 
-  :samp:`-complexity-cyclomatic`
+  :samp:`--complexity-cyclomatic`
     Report the McCabe Cyclomatic Complexity
 
 
-  :samp:`-no-complexity-cyclomatic`
+  :samp:`--no-complexity-cyclomatic`
     Do not report the McCabe Cyclomatic Complexity
 
 
-  :samp:`-complexity-essential`
+  :samp:`--complexity-essential`
     Report the Essential Complexity
 
 
-  :samp:`-no-complexity-essential`
+  :samp:`--no-complexity-essential`
     Do not report the Essential Complexity
 
 
-  :samp:`-loop-nesting`
+  :samp:`--loop-nesting`
     Report maximal loop nesting level
 
 
@@ -2452,14 +2480,14 @@ Alternatively, you may run the script using the following command line:
     Do not report maximal loop nesting level
 
 
-  :samp:`-complexity-average`
+  :samp:`--complexity-average`
     Report the average McCabe Cyclomatic Complexity for all the subprogram bodies,
     task bodies, entry bodies and statement sequences in package bodies.
     The metric is computed and reported for whole set of processed Ada sources
     only.
 
 
-  :samp:`-no-complexity-average`
+  :samp:`--no-complexity-average`
     Do not report the average McCabe Cyclomatic Complexity for all the subprogram
     bodies, task bodies, entry bodies and statement sequences in package bodies
 
@@ -2473,11 +2501,11 @@ Alternatively, you may run the script using the following command line:
   .. index:: --no-static-loop (gnatmetric)
 
 
-  :samp:`-no-static-loop`
+  :samp:`--no-static-loop`
     Do not consider static loops when computing cyclomatic complexity
 
 
-  :samp:`-extra-exit-points`
+  :samp:`--extra-exit-points`
     Report the extra exit points for subprogram bodies. As an exit point, this
     metric counts `return` statements and raise statements in case when the
     raised exception is not handled in the same body. In case of a function this
@@ -2485,7 +2513,7 @@ Alternatively, you may run the script using the following command line:
     must contain at least one `return` statement.
 
 
-  :samp:`-no-extra-exit-points`
+  :samp:`--no-extra-exit-points`
     Do not report the extra exit points for subprogram bodies
 
 
@@ -2678,39 +2706,39 @@ Alternatively, you may run the script using the following command line:
   .. index:: --unit-coupling (gnatmetric)
   .. index:: --control-coupling (gnatmetric)
 
-  :samp:`-coupling-all`
+  :samp:`--coupling-all`
     Report all the coupling metrics
 
 
-  :samp:`-tagged-coupling-out`
+  :samp:`--tagged-coupling-out`
     Report tagged (class) fan-out coupling
 
 
-  :samp:`-tagged-coupling-in`
+  :samp:`--tagged-coupling-in`
     Report tagged (class) fan-in coupling
 
 
-  :samp:`-hierarchy-coupling-out`
+  :samp:`--hierarchy-coupling-out`
     Report hierarchy (category) fan-out coupling
 
 
-  :samp:`-hierarchy-coupling-in`
+  :samp:`--hierarchy-coupling-in`
     Report hierarchy (category) fan-in coupling
 
 
-  :samp:`-unit-coupling-out`
+  :samp:`--unit-coupling-out`
     Report unit fan-out coupling
 
 
-  :samp:`-unit-coupling-in`
+  :samp:`--unit-coupling-in`
     Report unit fan-in coupling
 
 
-  :samp:`-control-coupling-out`
+  :samp:`--control-coupling-out`
     Report control fan-out coupling
 
 
-  :samp:`-control-coupling-in`
+  :samp:`--control-coupling-in`
     Report control fan-in coupling
 
 
@@ -2724,13 +2752,13 @@ Alternatively, you may run the script using the following command line:
 
   .. index:: --version (gnatmetric)
 
-  :samp:`-version`
+  :samp:`--version`
     Display Copyright and version, then exit disregarding all other options.
 
 
   .. index:: --help (gnatmetric)
 
-  :samp:`-help`
+  :samp:`--help`
     Display usage, then exit disregarding all other options.
 
 
@@ -2768,14 +2796,14 @@ Alternatively, you may run the script using the following command line:
 
   .. index:: --RTS (gnatmetric)
 
-  :samp:`-RTS={rts-path}`
+  :samp:`--RTS={rts-path}`
     Specifies the default location of the runtime library. Same meaning as the
     equivalent *gnatmake* flag (see :ref:`Switches_for_gnatmake`).
 
 
   .. index:: --subdirs=dir (gnatmetric)
 
-  :samp:`-subdirs={dir}`
+  :samp:`--subdirs={dir}`
     Use the specified subdirectory of the project objects file (or of the
     project file directory if the project does not specify an object directory)
     for tool output files. Has no effect if no project is specified as
@@ -2784,7 +2812,7 @@ Alternatively, you may run the script using the following command line:
 
   .. index:: --no_objects_dir (gnatmetric)
 
-  :samp:`-no_objects_dir`
+  :samp:`--no_objects_dir`
     Place all the result files into the current directory instead of
     project objects directory. This corresponds to the *gnatcheck*
     behavior when it is called with the project file from the
@@ -2852,6 +2880,11 @@ Alternatively, you may run the script using the following command line:
    You can specify various style directives via switches; e.g.,
    identifier case conventions, rules of indentation, and comment layout.
 
+   *gnatpp* is a project-aware tool
+   (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
+   the project-related switches).  The project file package that can specify
+   *gnatpp* switches is named ``Pretty_Printer``.
+
    To produce a reformatted file, *gnatpp* invokes the Ada
    compiler and generates and uses the ASIS tree for the input source;
    thus the input must be legal Ada code, and the tool should have all the
@@ -3143,6 +3176,13 @@ Alternatively, you may run the script using the following command line:
    :samp:`--comments-only`
      Format just the comments.
 
+   .. index:: --no-end-id (gnatpp)
+
+
+   :samp:`--no-end-id`
+     Do not insert the name of a unit after `end`; leave whatever comes
+     after `end`, if anything, alone.
+
    .. index:: --no-separate-is (gnatpp)
 
 
@@ -3849,6 +3889,15 @@ Alternatively, you may run the script using the following command line:
   for library unit declarations, and empty but compilable
   subunit for body stubs.
 
+  *gnatstub* is a project-aware tool.
+  (See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
+  the project-related switches but note that *gnatstub* does not support
+  the :samp:`-U`, :samp:`-U {main_unit}`, :samp:`--subdirs={dir}`, or
+  :samp:`--no_objects_dir` switches.)
+  The project file package that can specify
+  *gnatstub* switches is named ``gnatstub``.
+
+
   To create a body or a subunit, *gnatstub* invokes the Ada
   compiler and generates and uses the ASIS tree for the input source;
   thus the input must be legal Ada code, and the tool should have all the
@@ -4336,9 +4385,10 @@ Alternatively, you may run the script using the following command line:
 
     .. index:: --separate-drivers (gnattest)
 
-  :samp:`--separate-drivers`
-    Generates a separate test driver for each test, rather than a single
-    executable incorporating all tests.
+  :samp:`--separate-drivers[={val}]`
+    Generates a separate test driver for each test or unit under test, rather
+    than a single executable incorporating all tests. `val` can be "unit" or
+    "test", or may be omitted, which defaults to "unit".
 
 
     .. index:: --stub (gnattest)
@@ -4401,6 +4451,16 @@ Alternatively, you may run the script using the following command line:
     placed accordingly.
 
 
+    .. index:: --exclude-from-stubbing (gnattest)
+
+  :samp:`--exclude-from-stubbing={filename}`
+    Disables stubbing of units listed in `filename`. The file should contain
+    corresponding spec files, one per line.
+
+  :samp:`--exclude-from-stubbing:{unit}={filename}`
+    Same as above, but corresponding units will not be stubbed only when testing
+    specified `unit`.
+
     .. index:: --validate-type-extensions (gnattest)
 
   :samp:`--validate-type-extensions`
@@ -4531,6 +4591,15 @@ Alternatively, you may run the script using the following command line:
        specified by ``--skeleton-default`` option. The value of this attribute
        should be either ``pass`` or ``fail``.
 
+  * ``Default_Stub_Exclusion_List``
+       is used to specify the file with list of units whose bodies should not
+       be stubbed, otherwise specified by ``--exclude-from-stubbing=filename``.
+
+  * ``Stub_Exclusion_List ("unit")``
+       is used to specify the file with list of units whose bodies should not
+       be stubbed when testing "unit", otherwise specified by
+       ``--exclude-from-stubbing:unit=filename``.
+
   Each of those attributes can be overridden from the command line if needed.
   Other *gnattest* switches can also be passed via the project
   file as an attribute list called *Gnattest_Switches*.
@@ -4877,12 +4946,12 @@ Alternatively, you may run the script using the following command line:
 
   By default, *gnattest* generates a monolithic test driver that
   aggregates the individual tests into a single executable. It is also possible
-  to generate separate executables for each test, by passing the switch
-  ``--separate-drivers``. This approach scales better for large testing
-  campaigns, especially involving target architectures with limited resources
-  typical for embedded development. It can also provide a major performance
-  benefit on multi-core systems by allowing simultaneous execution of multiple
-  tests.
+  to generate separate executables for each test or each unit under test, by
+  passing the switch ``--separate-drivers`` with corresponding parameter. This
+  approach scales better for large testing campaigns, especially involving target
+  architectures with limited resources typical for embedded development. It can
+  also provide a major performance benefit on multi-core systems by allowing
+  simultaneous execution of multiple tests.
 
   *gnattest* can take charge of executing the individual tests; for this,
   instead of passing a project file, a text file containing the list of
@@ -4923,7 +4992,8 @@ Alternatively, you may run the script using the following command line:
 
   Due to the nature of stubbing process, this mode implies the switch
   ``--separate-drivers``, i.e. an individual test driver (with the
-  corresponding hierarchy of extending projects) is generated for each test.
+  corresponding hierarchy of extending projects) is generated for each unit under
+  test.
 
   .. note::
 
@@ -4965,5 +5035,90 @@ Alternatively, you may run the script using the following command line:
   * pragma *No_Secondary_Stack* is not supported;
   * if pragmas for interfacing with foreign languages are used, manual
     adjustments might be necessary to make the test harness compilable;
-  * use of elaboration control pragmas may result in elaboration circularities
-    in the generated harness.
+  * use of some constructs, such as elaboration-control pragmas, Type_Invariant
+    aspects, and complex variable initializations that use Subprogram'Access,
+    may result in elaboration circularities in the generated harness.
+
+.. only:: PRO or GPL
+
+   .. _Using_Project_Files_with_GNAT_Tools:
+
+   Using Project Files with GNAT Tools
+   ===================================
+
+   This section describes how project files can be used in conjunction
+   with a number of GNAT tools.
+   For a comprehensive description of project files and the overall
+   GNAT Project Manager facility, please refer to the
+   *GNAT Project Manager* chapter in the 
+   *GPRbuild and GPR Companion Tools User's Guide*.
+
+   .. index:: Project-aware tool
+
+   If a tool can take a project file as an option and extract the needed
+   information, such a tool is called a *project-aware* tool.
+
+   .. _Switches_Related_to_Project_Files:
+
+   Switches Related to Project Files
+   ---------------------------------
+
+   The following switches are used by the project-aware GNAT tools:
+
+   :samp:`-P{project_file}`
+      Indicates the name of the project file whose source files are to
+      be processed. The exact set of sources depends on other options
+      specified, see below.
+
+   :samp:`-U`
+      If a project file is supplied, say for project ``proj``,
+      but no sources are specified for ``proj`` (either by a 
+      project attribute or through a tool option that provides a list
+      of the files to be used), process all the source files
+      from projects imported either directly or indirectly by ``proj``.
+      Otherwise this option has no effect.
+
+   :samp:`-U {main_unit}`
+      Similar to :samp:`-U`, but if no sources are specified then
+      process only those source files for units in the closure of
+      `main_unit`.
+
+   :samp:`-X{name}={val}`
+      Indicates that the external variable ``name`` in the project has the
+      value ``val``. Has no effect if no project has been specified.
+
+   :samp:`--subdirs={dir}`
+      Use the `dir` subdirectory of the project's object directory (or the `dir`
+      subdirectory of the project file directory if the project does not specify
+      an object directory) for tool output files. Has no effect if no project
+      has been specified or if :samp:`--no_objects_dir` is specified.
+
+   :samp:`--no_objects_dir`
+      Place all the result files into the current directory (i.e., the directory
+      from which the tool invocation command is issued) instead of the project's
+      object directory. Has no effect if no project has been specified.
+
+   :samp:`-eL`
+      Follow all symbolic links when processing project files.
+
+   If a project file is specified and there is neither a :samp:`-U` option,
+   nor a :samp:`-U {main_unit}` option, nor some other explicit option to
+   specify the source files, then the sources to be processed are the
+   immediate sources of the specified project (i.e., the source files directly
+   defined by that project, either implicitly by residing in the project
+   source directories, or explicitly through any of the source-related
+   attributes).
+  
+   .. _Tool-specific_packages_in_project files:
+
+   Tool-specific packages in project files
+   ---------------------------------------
+
+   Each project-aware tool may have a corresponding package in a project file;
+   the package names are given elsewhere in this manual, in the sections that describe
+   the respective tools.
+
+   A tool-specific package in a project file may define the ``Default_Switches``
+   attribute indexed by "ada" (as language name). The value of this attribute
+   is a list of switches that will be supplied at tool invocation.
+   Project-specific switches cannot be specified through this attribute. 

gcc/ada/doc/gnat_ugn/platform_specific_information.rst

@@ -156,6 +156,31 @@ For example on x86-linux::
    --           |
    --           +--- adalib
 
+.. only:: html or latex
+
+  .. image:: rtlibrary-structure.png
+
+.. only:: not (html or latex) 
+
+   ::
+
+                      $(target-dir)
+                     __/ /      \ \___
+             _______/   /        \    \_________________
+            /          /          \                     \
+           /          /            \                     \
+       ADAINCLUDE  ADALIB      rts-native             rts-sjlj
+          :          :            /    \                 /   \
+          :          :           /      \               /     \
+          :          :          /        \             /       \
+          :          :         /          \           /         \
+          +-------------> adainclude     adalib   adainclude   adalib
+                     :                     ^
+                     :                     :
+                     +---------------------+
+
+                     Run-Time Library Directory Structure
+          (Upper-case names and dotted/dashed arrows represent soft links)
 
 If the *rts-sjlj* library is to be selected on a permanent basis,
 these soft links can be modified with the following commands:
@@ -486,7 +511,58 @@ file will be created. This is particularly useful in networked
 environments where you may not have write access to some
 directories.
 
+Disabling Command Line Argument Expansion
+-----------------------------------------
+
+.. index:: Command Line Argument Expansion
+
+By default, an executable compiled for the **Windows** platform will do
+the following postprocessing on the arguments passed on the command
+line:
+
+* If the argument contains the characters ``*`` and/or ``?``, then
+  file expansion will be attempted. For example, if the current directory
+  contains :file:`a.txt` and :file:`b.txt`, then when calling::
+
+      $ my_ada_program *.txt
+
+  The following arguments will effectively be passed to the main program
+  (for example when using ``Ada.Command_Line.Argument``)::
+
+      Ada.Command_Line.Argument (1) -> "a.txt"
+      Ada.Command_Line.Argument (2) -> "b.txt"
+
+* Filename expansion can be disabled for a given argument by using single
+  quotes. Thus, calling::
 
+      $ my_ada_program '*.txt'
+
+  will result in::
+
+      Ada.Command_Line.Argument (1) -> "*.txt"
+
+Note that if the program is launched from a shell such as **Cygwin** **Bash**
+then quote removal might be performed by the shell.
+
+In some contexts it might be useful to disable this feature (for example if
+the program performs its own argument expansion). In order to do this, a C
+symbol needs to be defined and set to ``0``. You can do this by
+adding the following code fragment in one of your **Ada** units:
+
+.. code-block:: ada
+
+   Do_Argv_Expansion : Integer := 0;
+   pragma Export (C, Do_Argv_Expansion, "__gnat_do_argv_expansion");
+
+The results of previous examples will be respectively::
+
+   Ada.Command_Line.Argument (1) -> "*.txt"
+
+and::
+
+   Ada.Command_Line.Argument (1) -> "'*.txt'"
+
+   
 .. _Mixed-Language_Programming_on_Windows:
 
 Mixed-Language Programming on Windows
@@ -1033,7 +1109,8 @@ Building DLLs with GNAT Project files
 .. index:: DLLs, building
 
 There is nothing specific to Windows in the build process.
-:ref:`Library_Projects`.
+See the *Library Projects* section in the *GNAT Project Manager*
+chapter of the *GPRbuild User's Guide*.
 
 Due to a system limitation, it is not possible under Windows to create threads
 when inside the `DllMain` routine which is used for auto-initialization
@@ -1149,7 +1226,9 @@ Note that a relocatable DLL stripped using the `strip`
 binutils tool will not be relocatable anymore. To build a DLL without
 debug information pass `-largs -s` to `gnatdll`. This
 restriction does not apply to a DLL built using a Library Project.
-See :ref:`Library_Projects`.
+See the *Library Projects* section in the *GNAT Project Manager*
+chapter of the *GPRbuild User's Guide*.
+
 
 .. Limitations_When_Using_Ada_DLLs_from Ada:
 

gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst

@@ -872,7 +872,7 @@ File Name Krunching with `gnatkr`
 
 .. index:: ! gnatkr
 
-This chapter discusses the method used by the compiler to shorten
+This section discusses the method used by the compiler to shorten
 the default file names chosen for Ada units so that they do not
 exceed the maximum length permitted. It also describes the
 `gnatkr` utility that can be used to determine the result of
@@ -1052,7 +1052,7 @@ Renaming Files with `gnatchop`
 
 .. index:: ! gnatchop
 
-This chapter discusses how to handle files with multiple units by using
+This section discusses how to handle files with multiple units by using
 the `gnatchop` utility. This utility is also useful in renaming
 files to meet the standard GNAT default file naming conventions.
 
@@ -1550,8 +1550,10 @@ depend on a file that no longer exists. Such tools include
 *gprbuild*, *gnatmake*, and *gnatcheck*.
 
 If you are using project file, a separate mechanism is provided using
-project attributes, see :ref:`Specifying_Configuration_Pragmas` for more
-details.
+project attributes.
+
+.. --Comment:
+   See :ref:`Specifying_Configuration_Pragmas` for more details.
 
 
 .. _Generating_Object_Files:
@@ -1788,10 +1790,10 @@ GNAT and Libraries
 
 .. index:: Library building and using
 
-This chapter describes how to build and use libraries with GNAT, and also shows
+This section describes how to build and use libraries with GNAT, and also shows
 how to recompile the GNAT run-time library. You should be familiar with the
-Project Manager facility (:ref:`GNAT_Project_Manager`) before reading this
-chapter.
+Project Manager facility (see the *GNAT_Project_Manager* chapter of the
+*GPRbuild User's Guide*) before reading this chapter.
 
 .. _Introduction_to_Libraries_in_GNAT:
 
@@ -1849,7 +1851,8 @@ Building a library
 
 The easiest way to build a library is to use the Project Manager,
 which supports a special type of project called a *Library Project*
-(see :ref:`Library_Projects`).
+(see the *Library Projects* section in the *GNAT Project Manager*
+chapter of the *GPRbuild User's Guide*).
 
 A project is considered a library project, when two project-level attributes
 are defined in it: `Library_Name` and `Library_Dir`. In order to
@@ -1961,7 +1964,8 @@ Installing a library
 .. index:: GPR_PROJECT_PATH
 
 If you use project files, library installation is part of the library build
-process (:ref:`Installing_a_library_with_project_files`).
+process (see the *Installing a Library with Project Files* section of the
+*GNAT Project Manager* chapter of the *GPRbuild User's Guide*).
 
 When project files are not an option, it is also possible, but not recommended,
 to install the library so that the sources needed to use the library are on the
@@ -2137,11 +2141,13 @@ Building a Stand-alone Library
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 GNAT's Project facility provides a simple way of building and installing
-stand-alone libraries; see :ref:`Stand-alone_Library_Projects`.
+stand-alone libraries; see the *Stand-alone Library Projects* section
+in the *GNAT Project Manager* chapter of the *GPRbuild User's Guide*.
 To be a Stand-alone Library Project, in addition to the two attributes
 that make a project a Library Project (`Library_Name` and
-`Library_Dir`; see :ref:`Library_Projects`), the attribute
-`Library_Interface` must be defined.  For example:
+`Library_Dir`; see the *Library Projects* section in the
+*GNAT Project Manager* chapter of the *GPRbuild User's Guide*),
+the attribute `Library_Interface` must be defined.  For example:
 
 .. code-block:: gpr
  

gcc/ada/doc/gnat_ugn/tools_supporting_project_files.rst

-.. _Tools_Supporting_Project_Files:
-
-Tools Supporting Project Files
-==============================
-
-This section describes how project files can be used in conjunction with a number of
-GNAT tools.
-
-.. _gnatmake_and_Project_Files:
-
-gnatmake and Project Files
---------------------------
-
-This section covers several topics related to *gnatmake* and
-project files: defining switches for *gnatmake*
-and for the tools that it invokes; specifying configuration pragmas;
-the use of the `Main` attribute; building and rebuilding library project
-files.
-
-.. _Switches_Related_to_Project_Files:
-
-Switches Related to Project Files
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following switches are used by GNAT tools that support project files:
-
-
-  .. index:: -P (any project-aware tool)
-
-:samp:`-P{project}`
-  Indicates the name of a project file. This project file will be parsed with
-  the verbosity indicated by *-vP*x**,
-  if any, and using the external references indicated
-  by *-X* switches, if any.
-  There may zero, one or more spaces between *-P* and `project`.
-
-  There must be only one *-P* switch on the command line.
-
-  Since the Project Manager parses the project file only after all the switches
-  on the command line are checked, the order of the switches
-  *-P*,
-  *-vP*x**
-  or *-X* is not significant.
-
-
-  .. index:: -X (any project-aware tool)
-
-:samp:`-X{name}={value}`
-  Indicates that external variable `name` has the value `value`.
-  The Project Manager will use this value for occurrences of
-  `external(name)` when parsing the project file.
-
-  If `name` or `value` includes a space, then `name=value` should be
-  put between quotes.
-
-  ::
-
-      -XOS=NT
-      -X"user=John Doe"
-    
-  Several *-X* switches can be used simultaneously.
-  If several *-X* switches specify the same
-  `name`, only the last one is used.
-
-  An external variable specified with a *-X* switch
-  takes precedence over the value of the same name in the environment.
-
-
-  .. index:: -vP (any project-aware tool)
-
-:samp:`-vP{x}`
-  Indicates the verbosity of the parsing of GNAT project files.
-
-  *-vP0* means Default;
-  *-vP1* means Medium;
-  *-vP2* means High.
-
-  The default is Default: no output for syntactically correct
-  project files.
-  If several *-vP*x** switches are present,
-  only the last one is used.
-
-
-  .. index:: -aP (any project-aware tool)
-
-:samp:`-aP{dir}`
-  Add directory `dir` at the beginning of the project search path, in order,
-  after the current working directory.
-
-
-  .. index:: -eL (any project-aware tool)
-
-:samp:`-eL`
-  Follow all symbolic links when processing project files.
-
-
-  .. index:: --subdirs= (gnatmake and gnatclean)
-
-:samp:`--subdirs={subdir}`
-  This switch is recognized by *gnatmake* and *gnatclean*. It
-  indicate that the real directories (except the source directories) are the
-  subdirectories `subdir` of the directories specified in the project files.
-  This applies in particular to object directories, library directories and
-  exec directories. If the subdirectories do not exist, they are created
-  automatically.
-
-
-.. _Switches_and_Project_Files:
-
-Switches and Project Files
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-For each of the packages `Builder`, `Compiler`, `Binder`, and
-`Linker`, you can specify a `Default_Switches`
-attribute, a `Switches` attribute, or both;
-as their names imply, these switch-related
-attributes affect the switches that are used for each of these GNAT
-components when
-*gnatmake* is invoked.  As will be explained below, these
-component-specific switches precede
-the switches provided on the *gnatmake* command line.
-
-The `Default_Switches` attribute is an attribute
-indexed by language name (case insensitive) whose value is a string list.
-For example:
-
-  .. code-block:: gpr
-
-     package Compiler is
-       for Default_Switches ("Ada")
-           use ("-gnaty",
-                "-v");
-     end Compiler;
-
-The `Switches` attribute is indexed on a file name (which may or may
-not be case sensitive, depending
-on the operating system) whose value is a string list.  For example:
-
-  .. code-block:: gpr
-
-     package Builder is
-        for Switches ("main1.adb")
-            use ("-O2");
-        for Switches ("main2.adb")
-            use ("-g");
-     end Builder;
-
-For the `Builder` package, the file names must designate source files
-for main subprograms.  For the `Binder` and `Linker` packages, the
-file names must designate :file:`ALI` or source files for main subprograms.
-In each case just the file name without an explicit extension is acceptable.
-
-For each tool used in a program build (*gnatmake*, the compiler, the
-binder, and the linker), the corresponding package @dfn{contributes} a set of
-switches for each file on which the tool is invoked, based on the
-switch-related attributes defined in the package.
-In particular, the switches
-that each of these packages contributes for a given file `f` comprise:
-
-* the value of attribute `Switches (`f`)`,
-  if it is specified in the package for the given file,
-* otherwise, the value of `Default_Switches ("Ada")`,
-  if it is specified in the package.
-
-If neither of these attributes is defined in the package, then the package does
-not contribute any switches for the given file.
-
-When *gnatmake* is invoked on a file, the switches comprise
-two sets, in the following order: those contributed for the file
-by the `Builder` package;
-and the switches passed on the command line.
-
-When *gnatmake* invokes a tool (compiler, binder, linker) on a file,
-the switches passed to the tool comprise three sets,
-in the following order:
-
-* the applicable switches contributed for the file
-  by the `Builder` package in the project file supplied on the command line;
-
-* those contributed for the file by the package (in the relevant project file --
-  see below) corresponding to the tool; and
-
-* the applicable switches passed on the command line.
-
-The term *applicable switches* reflects the fact that
-*gnatmake* switches may or may not be passed to individual
-tools, depending on the individual switch.
-
-*gnatmake* may invoke the compiler on source files from different
-projects. The Project Manager will use the appropriate project file to
-determine the `Compiler` package for each source file being compiled.
-Likewise for the `Binder` and `Linker` packages.
-
-As an example, consider the following package in a project file:
-
-
-  .. code-block:: gpr
-
-     project Proj1 is
-        package Compiler is
-           for Default_Switches ("Ada")
-               use ("-g");
-           for Switches ("a.adb")
-               use ("-O1");
-           for Switches ("b.adb")
-               use ("-O2",
-                    "-gnaty");
-        end Compiler;
-     end Proj1;
-  
-If *gnatmake* is invoked with this project file, and it needs to
-compile, say, the files :file:`a.adb`, :file:`b.adb`, and :file:`c.adb`, then
-:file:`a.adb` will be compiled with the switch *-O1*,
-:file:`b.adb` with switches *-O2* and *-gnaty*,
-and :file:`c.adb` with *-g*.
-
-The following example illustrates the ordering of the switches
-contributed by different packages:
-
-  .. code-block:: gpr
-
-     project Proj2 is
-        package Builder is
-           for Switches ("main.adb")
-               use ("-g",
-                    "-O1",
-                    "-f");
-        end Builder;
-
-        package Compiler is
-           for Switches ("main.adb")
-               use ("-O2");
-        end Compiler;
-     end Proj2;
-
-If you issue the command:
-
-  ::
-
-      $ gnatmake -Pproj2 -O0 main
-  
-then the compiler will be invoked on :file:`main.adb` with the following
-sequence of switches
-
-  ::
-
-      -g -O1 -O2 -O0
-  
-with the last *-O*
-switch having precedence over the earlier ones;
-several other switches
-(such as *-c*) are added implicitly.
-
-The switches *-g*
-and *-O1* are contributed by package
-`Builder`,  *-O2* is contributed
-by the package `Compiler`
-and *-O0* comes from the command line.
-
-The *-g* switch will also be passed in the invocation of
-*Gnatlink.*
-
-A final example illustrates switch contributions from packages in different
-project files:
-
-  .. code-block:: gpr
-  
-     project Proj3 is
-        for Source_Files use ("pack.ads", "pack.adb");
-        package Compiler is
-           for Default_Switches ("Ada")
-               use ("-gnata");
-        end Compiler;
-     end Proj3;
-
-     with "Proj3";
-     project Proj4 is
-        for Source_Files use ("foo_main.adb", "bar_main.adb");
-        package Builder is
-           for Switches ("foo_main.adb")
-               use ("-s",
-                    "-g");
-        end Builder;
-     end Proj4;
-
-  .. code-block:: ada
-
-     -- Ada source file:
-     with Pack;
-     procedure Foo_Main is
-        ...
-     end Foo_Main;
-  
-If the command is
-
-  ::
-
-     $ gnatmake -PProj4 foo_main.adb -cargs -gnato
-  
-then the switches passed to the compiler for :file:`foo_main.adb` are
-*-g* (contributed by the package `Proj4.Builder`) and
-*-gnato* (passed on the command line).
-When the imported package `Pack` is compiled, the switches used
-are *-g* from `Proj4.Builder`,
-*-gnata* (contributed from package `Proj3.Compiler`,
-and *-gnato* from the command line.
-
-When using *gnatmake* with project files, some switches or
-arguments may be expressed as relative paths. As the working directory where
-compilation occurs may change, these relative paths are converted to absolute
-paths. For the switches found in a project file, the relative paths
-are relative to the project file directory, for the switches on the command
-line, they are relative to the directory where *gnatmake* is invoked.
-The switches for which this occurs are:
--I,
--A,
--L,
--aO,
--aL,
--aI, as well as all arguments that are not switches (arguments to
-switch
--o, object files specified in package `Linker` or after
--largs on the command line). The exception to this rule is the switch
---RTS= for which a relative path argument is never converted.
-
-.. _Specifying_Configuration_Pragmas:
-
-Specifying Configuration Pragmas
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When using *gnatmake* with project files, if there exists a file
-:file:`gnat.adc` that contains configuration pragmas, this file will be
-ignored.
-
-Configuration pragmas can be defined by means of the following attributes in
-project files: `Global_Configuration_Pragmas` in package `Builder`
-and `Local_Configuration_Pragmas` in package `Compiler`.
-
-Both these attributes are single string attributes. Their values is the path
-name of a file containing configuration pragmas. If a path name is relative,
-then it is relative to the project directory of the project file where the
-attribute is defined.
-
-When compiling a source, the configuration pragmas used are, in order,
-those listed in the file designated by attribute
-`Global_Configuration_Pragmas` in package `Builder` of the main
-project file, if it is specified, and those listed in the file designated by
-attribute `Local_Configuration_Pragmas` in package `Compiler` of
-the project file of the source, if it exists.
-
-.. _Project_Files_and_Main_Subprograms:
-
-Project Files and Main Subprograms
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When using a project file, you can invoke *gnatmake*
-with one or several main subprograms, by specifying their source files on the
-command line.
-
-  ::
-
-      $ gnatmake -Pprj main1.adb main2.adb main3.adb
-
-Each of these needs to be a source file of the same project, except
-when the switch `-u` is used.
-
-When `-u` is not used, all the mains need to be sources of the
-same project, one of the project in the tree rooted at the project specified
-on the command line. The package `Builder` of this common project, the
-"main project" is the one that is considered by *gnatmake*.
-
-When `-u` is used, the specified source files may be in projects
-imported directly or indirectly by the project specified on the command line.
-Note that if such a source file is not part of the project specified on the
-command line, the switches found in package `Builder` of the
-project specified on the command line, if any, that are transmitted
-to the compiler will still be used, not those found in the project file of
-the source file.
-
-When using a project file, you can also invoke *gnatmake* without
-explicitly specifying any main, and the effect depends on whether you have
-defined the `Main` attribute.  This attribute has a string list value,
-where each element in the list is the name of a source file (the file
-extension is optional) that contains a unit that can be a main subprogram.
-
-If the `Main` attribute is defined in a project file as a non-empty
-string list and the switch *-u* is not used on the command
-line, then invoking *gnatmake* with this project file but without any
-main on the command line is equivalent to invoking *gnatmake* with all
-the file names in the `Main` attribute on the command line.
-
-Example:
-
-  .. code-block:: gpr
-
-     project Prj is
-        for Main use ("main1.adb", "main2.adb", "main3.adb");
-     end Prj;
-
-With this project file, `"gnatmake -Pprj"`
-is equivalent to
-`"gnatmake -Pprj main1.adb main2.adb main3.adb"`.
-
-When the project attribute `Main` is not specified, or is specified
-as an empty string list, or when the switch *-u* is used on the command
-line, then invoking *gnatmake* with no main on the command line will
-result in all immediate sources of the project file being checked, and
-potentially recompiled. Depending on the presence of the switch *-u*,
-sources from other project files on which the immediate sources of the main
-project file depend are also checked and potentially recompiled. In other
-words, the *-u* switch is applied to all of the immediate sources of the
-main project file.
-
-When no main is specified on the command line and attribute `Main` exists
-and includes several mains, or when several mains are specified on the
-command line, the default switches in package `Builder` will
-be used for all mains, even if there are specific switches
-specified for one or several mains.
-
-But the switches from package `Binder` or `Linker` will be
-the specific switches for each main, if they are specified.
-
-.. _Library_Project_Files:
-
-Library Project Files
-^^^^^^^^^^^^^^^^^^^^^
-
-When *gnatmake* is invoked with a main project file that is a library
-project file, it is not allowed to specify one or more mains on the command
-line.
-
-When a library project file is specified, switches `-b` and
-`-l` have special meanings.
-
-* `-b` is only allowed for stand-alone libraries. It indicates
-  to *gnatmake* that *gnatbind* should be invoked for the
-  library.
-
-* `-l` may be used for all library projects. It indicates
-  to *gnatmake* that the binder generated file should be compiled
-  (in the case of a stand-alone library) and that the library should be built.
-
-
-.. _The_GNAT_Driver_and_Project_Files:
-
-The GNAT Driver and Project Files
----------------------------------
-
-A number of GNAT tools beyond *gnatmake*
-can benefit from project files:
-
-.. only:: PRO or GPL
-
-  * *gnatbind*
-  * *gnatcheck*
-  * *gnatclean*
-  * *gnatelim*
-  * *gnatfind*
-  * *gnatlink*
-  * *gnatls*
-  * *gnatmetric*
-  * *gnatpp*
-  * *gnatstub*
-  * *gnatxref*
-
-.. only:: FSF
-
-  * *gnatbind*
-  * *gnatclean*
-  * *gnatfind*
-  * *gnatlink*
-  * *gnatls*
-  * *gnatxref*
-
-However, none of these tools can be invoked
-directly with a project file switch (*-P*).
-They must be invoked through the *gnat* driver.
-
-The *gnat* driver is a wrapper that accepts a number of commands and
-calls the corresponding tool. It was designed initially for VMS platforms (to
-convert VMS qualifiers to Unix-style switches), but it is now available on all
-GNAT platforms.
-
-On non-VMS platforms, the *gnat* driver accepts the following commands
-(case insensitive):
-
-.. only:: PRO or GPL
-
-  * BIND to invoke *gnatbind*
-  * CHOP to invoke *gnatchop*
-  * CLEAN to invoke *gnatclean*
-  * COMP or COMPILE to invoke the compiler
-  * ELIM to invoke *gnatelim*
-  * FIND to invoke *gnatfind*
-  * KR or KRUNCH to invoke *gnatkr*
-  * LINK to invoke *gnatlink*
-  * LS or LIST to invoke *gnatls*
-  * MAKE to invoke *gnatmake*
-  * METRIC to invoke *gnatmetric*
-  * NAME to invoke *gnatname*
-  * PP or PRETTY to invoke *gnatpp*
-  * PREP or PREPROCESS to invoke *gnatprep*
-  * STUB to invoke *gnatstub*
-  * XREF to invoke *gnatxref*
-
-.. only:: FSF
-
-  * BIND to invoke *gnatbind*
-  * CHOP to invoke *gnatchop*
-  * CLEAN to invoke *gnatclean*
-  * COMP or COMPILE to invoke the compiler
-  * FIND to invoke *gnatfind*
-  * KR or KRUNCH to invoke *gnatkr*
-  * LINK to invoke *gnatlink*
-  * LS or LIST to invoke *gnatls*
-  * MAKE to invoke *gnatmake*
-  * NAME to invoke *gnatname*
-  * PREP or PREPROCESS to invoke *gnatprep*
-  * XREF to invoke *gnatxref*
-
-Note that the command
-*gnatmake -c -f -u* is used to invoke the compiler.
-
-On non-VMS platforms, between *gnat* and the command, two
-special switches may be used:
-
-* *-v* to display the invocation of the tool.
-* *-dn* to prevent the *gnat* driver from removing
-  the temporary files it has created. These temporary files are
-  configuration files and temporary file list files.
-
-The command may be followed by switches and arguments for the invoked
-tool.
-
-  ::
-
-     $ gnat bind -C main.ali
-     $ gnat ls -a main
-     $ gnat chop foo.txt
-  
-Switches may also be put in text files, one switch per line, and the text
-files may be specified with their path name preceded by '@'.
-
-  ::
-
-     $ gnat bind @args.txt main.ali
-  
-In addition, for the following commands the project file related switches
-(*-P*, *-X* and *-vPx*) may be used in addition to
-the switches of the invoking tool:
-
-.. only:: PRO or GPL
-
-   * BIND
-   * COMP or COMPILE 
-   * FIND
-   * ELIM
-   * LS or LIST
-   * LINK
-   * METRIC
-   * PP or PRETTY
-   * STUB
-   * XREF
-
-.. only:: FSF
-
-   * BIND
-   * COMP or COMPILE 
-   * FIND
-   * LS or LIST
-   * LINK
-   * XREF
-
-.. only:: PRO or GPL
-
-   When GNAT PP or GNAT PRETTY is used with a project file, but with no source
-   specified on the command line, it invokes *gnatpp* with all
-   the immediate sources of the specified project file.
-
-   When GNAT METRIC is used with a project file, but with no source
-   specified on the command line, it invokes *gnatmetric*
-   with all the immediate sources of the specified project file and with
-   *-d* with the parameter pointing to the object directory
-   of the project.
-
-   In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
-   a project file, no source is specified on the command line and
-   switch -U is specified on the command line, then
-   the underlying tool (gnatpp or
-   gnatmetric) is invoked for all sources of all projects,
-   not only for the immediate sources of the main project.
-   (-U stands for Universal or Union of the project files of the project tree)
-
-For each of the following commands, there is optionally a corresponding
-package in the main project.
-
-.. only:: PRO or GPL
-
-   * package `Binder` for command BIND (invoking `gnatbind`)
-   * package `Check` for command CHECK (invoking `gnatcheck`)
-   * package `Compiler` for command COMP or COMPILE (invoking the compiler)
-   * package `Cross_Reference` for command XREF (invoking `gnatxref`)
-   * package `Eliminate` for command ELIM (invoking `gnatelim`)
-   * package `Finder` for command FIND (invoking `gnatfind`)
-   * package `Gnatls` for command LS or LIST (invoking `gnatls`)
-   * package `Gnatstub` for command STUB (invoking `gnatstub`)
-   * package `Linker` for command LINK (invoking `gnatlink`)
-   * package `Metrics` for command METRIC (invoking `gnatmetric`)
-   * package `Pretty_Printer` for command PP or PRETTY (invoking `gnatpp`)
-
-.. only:: FSF
-
-   * package `Binder` for command BIND (invoking `gnatbind`)
-   * package `Compiler` for command COMP or COMPILE (invoking the compiler)
-   * package `Cross_Reference` for command XREF (invoking `gnatxref`)
-   * package `Finder` for command FIND (invoking `gnatfind`)
-   * package `Gnatls` for command LS or LIST (invoking `gnatls`)
-   * package `Linker` for command LINK (invoking `gnatlink`)
-
-Package `Gnatls` has a unique attribute `Switches`,
-a simple variable with a string list value. It contains switches
-for the invocation of `gnatls`.
-
-  .. code-block:: gpr
-
-     project Proj1 is
-        package gnatls is
-           for Switches
-               use ("-a",
-                    "-v");
-        end gnatls;
-     end Proj1;
-
-All other packages have two attribute `Switches` and
-`Default_Switches`.
-
-`Switches` is an indexed attribute, indexed by the
-source file name, that has a string list value: the switches to be
-used when the tool corresponding to the package is invoked for the specific
-source file.
-
-`Default_Switches` is an attribute,
-indexed by  the programming language that has a string list value.
-`Default_Switches ("Ada")` contains the
-switches for the invocation of the tool corresponding
-to the package, except if a specific `Switches` attribute
-is specified for the source file.
-
-  .. code-block:: gpr
-
-     project Proj is
-
-        for Source_Dirs use ("");
-
-        package gnatls is
-           for Switches use
-               ("-a",
-                "-v");
-        end gnatls;
-
-        package Compiler is
-           for Default_Switches ("Ada")
-               use ("-gnatv",
-                    "-gnatwa");
-        end Binder;
-
-        package Binder is
-           for Default_Switches ("Ada")
-               use ("-C",
-                    "-e");
-        end Binder;
-
-        package Linker is
-           for Default_Switches ("Ada")
-               use ("-C");
-           for Switches ("main.adb")
-               use ("-C",
-                    "-v",
-                    "-v");
-        end Linker;
-
-        package Finder is
-           for Default_Switches ("Ada")
-                use ("-a",
-                     "-f");
-        end Finder;
-
-        package Cross_Reference is
-           for Default_Switches ("Ada")
-               use ("-a",
-                    "-f",
-                    "-d",
-                    "-u");
-        end Cross_Reference;
-     end Proj;
-  
-With the above project file, commands such as
-
-  ::
-
-     $ gnat comp -Pproj main
-     $ gnat ls -Pproj main
-     $ gnat xref -Pproj main
-     $ gnat bind -Pproj main.ali
-     $ gnat link -Pproj main.ali
-
-will set up the environment properly and invoke the tool with the switches
-found in the package corresponding to the tool:
-`Default_Switches ("Ada")` for all tools,
-except `Switches ("main.adb")`
-for `gnatlink`.
-
-.. only:: PRO or GPL
-
-   It is also possible to invoke some of the tools,
-   (`gnatcheck`,
-   `gnatmetric`,
-   and `gnatpp`)
-   on a set of project units thanks to the combination of the switches
-   *-P*, *-U* and possibly the main unit when one is interested
-   in its closure. For instance,
-
-     ::
-
-        $ gnat metric -Pproj
- 
-   will compute the metrics for all the immediate units of project `proj`.
-
-     ::
-
-        $ gnat metric -Pproj -U
-  
-   will compute the metrics for all the units of the closure of projects
-   rooted at `proj`.
-
-     ::
-
-        $ gnat metric -Pproj -U main_unit
-
-   will compute the metrics for the closure of units rooted at
-   `main_unit`. This last possibility relies implicitly
-   on *gnatbind*'s option *-R*. But if the argument files for the
-   tool invoked by the *gnat* driver are explicitly  specified
-   either directly or through the tool *-files* option, then the tool
-   is called only for these explicitly specified files.