[Ada] Stabilization of Elaboration order v4.0

This patch introduces several changes to the new elaboration order
mechanism:

   * Instantiations processed in the context of invocation graph
     encoding now yield a relation which is later transformed into an
     invocation edge. This ensures that the unit where the instantiation
     resides properly depends on the unit where the body of the generic
     is.

   * The diagnostics of cycles that involve invocation edges now use a
     set to avoid infinite recursion when visiting paths that represent
     recursive code.

   * Various diagnostics that suggest the use of switches have been
     updated to indicate which tool the switches apply to.

   * Bindo can now output the dependencies of various units that specify
     why a predecessor unit must be elaborated prior to a successor
     unit. This functionality implements binder switch -e (output
     complete list of elaboration order dependencies).

   * The output of the elaboration order is now identical to that
     emitted by Binde.

   * The nature of the invocation graph encoding is now recorded in the
     ALI record rather than the Unit record of a unit. This ensures that
     both the spec and body share the same encoding kind.

   * A section on debugging elaboration order issues is now available in
     Bindo.

2019-07-05  Hristian Kirtchev  <kirtchev@adacore.com>

gcc/ada/

	* ali.adb (For_Each_Invocation_Construct,
	For_Each_Invocation_Relation): New version.
	(Scan_ALI): Initialize field Invocation_Graph_Encoding.
	(Set_Invocation_Graph_Encoding): Update the setting of the
	invocation graph encoding.
	* ali.ads: Move field Invocation_Graph_Encoding from Unit_Record
	to ALI_Record because the encoding applies to the whole ALI,
	rather than one of the units (spec or body) for which the ALI
	file was created.
	(For_Each_Invocation_Construct, For_Each_Invocation_Relation):
	New version.
	* bindo.adb: Update the section on switches.  Complete the
	section of debugging elaboration order issues.
	(Find_Elaboration_Order): Prepare the routine for the switch
	from the old to the new elaboration order mechanism.
	* bindo-diagnostics.adb (Find_And_Output_Invocation_Paths):
	Manage a visited set used by Visit_Vertex.
	(Output_All_Cycles_Suggestions,
	Output_Dynamic_Model_Suggestions): Clarify the nature of the
	suggested switch.
	(Output_Elaborate_Body_Transition): Update the diagnostic to
	emit a better message.
	(Output_Forced_Suggestions, Output_Full_Encoding_Suggestions):
	Clarify the nature of the suggested switch.
	(Visit_Vertex): Update the parameter profile to add a set of
	invokers visited during the transition. This set prevents
	infinite exploration of the graph in case the invocations are
	recursive.
	* bindo-elaborators.adb: Add a use clause for
	Bindo.Writers.Dependency_Writers.
	(Elaborate_Units_Common): Output the library graph after it has
	been augmented with invocation edges. Output just the components
	instead of outputting the whole library graph again.
	(Elaborate_Units_Dynamic, Elaborate_Units_Static): Output the
	dependencies as expressed in the library graph.
	* bindo-units.adb (Invocation_Graph_Encoding): Update the
	extraction of the invocation graph encoding.
	* bindo-writers.adb: Add with and use clauses for Binderr and
	Butil.
	(palgc, plgc): New debug routine.
	(Write_Components): Moved to the spec. Add a header for the
	output.
	(Write_Dependencies, Write_Dependencies_Of_Vertex,
	Write_Dependency_Edge): New routine.
	(Write_Elaboration_Order): Update the logic to follow the format
	of Binde's order output.
	(Write_Library_Graph): Do not output the components every time
	the graph is written.
	(Write_Unit): Output the invocation graph encoding of the unit.
	Output the invocation constructs and relations for the unit
	only.
	* bindo-writers.ads (Write_Components): Moved from the body.
	(Write_Dependencies): New routine.
	* bindusg.adb: Prepare the routine for the switch from the old
	to the new elaboration order mechanism.
	* debug.adb: Binder switch -d_O is now not associated with any
	functionality.
	* einfo.adb (Is_Elaboration_Target): The attribute applies to
	packages, as specified by the comment on the attribute usage.
	* opt.ads: Add a global flag which controls the choice between
	the new and the legacy elaboration order mechanism.
	* sem_elab.adb: Add Package_Target to type Target_Kind.
	(Build_Elaborate_Body_Procedure, Build_Elaborate_Procedure,
	Build_Elaborate_Spec_Procedure, Check_Elaboration_Scenarios,
	Check_SPARK_Model_In_Effect): Use Main_Unit_Entity to obtain the
	entity of the main unit.
	(Create_Package_Rep): New routine.
	(Create_Target_Rep): Add processing for packages.
	(Declaration_Placement_Of_Node, Has_Prior_Elaboration): Use
	Main_Unit_Entity to obtain the entity of the main
	 unit.
	(Invocation_Graph_Recording_OK): Prepare the routine for the
	switch from the old to the new elaboration order mechanism.
	(Main_Unit_Entity): New routine.
	(Meet_Elaboration_Requirement,
	Process_Conditional_ABE_Variable_Reference): Use
	Main_Unit_Entity to obtain the entity of the main unit.
	(Process_Invocation_Instantiation): New routine.
	(Process_Invocation_Scenario): Add processing for
	instantiations.
	* switch-b.adb (Scan_Binder_Switches): Prepare the routine for
	the switch from the old to the new elaboration order mechanism.

From-SVN: r273128

1 files changed, 144 insertions, 14 deletions

diff --git a/gcc/ada/bindo.adb b/gcc/ada/bindo.adb
index 039fd0d..b3106ad 100644
--- a/gcc/ada/bindo.adb
+++ b/gcc/ada/bindo.adb
@@ -32,10 +32,10 @@ use  Bindo.Elaborators;
 package body Bindo is
 
    ---------------------------------
-   -- Elaboration order mechanism --
+   -- Elaboration-order mechanism --
    ---------------------------------
 
-   --  The elaboration order (EO) mechanism implemented in this unit and its
+   --  The elaboration-order (EO) mechanism implemented in this unit and its
    --  children has the following objectives:
    --
    --    * Find an ordering of all library items (historically referred to as
@@ -272,7 +272,7 @@ package body Bindo is
    --          whose elaboration cannot be guaranteed.
    --
    --        - A detailed traceback of the cycle, showcasing the transition
-   --          between units, along with any other elaboration order-related
+   --          between units, along with any other elaboration-order-related
    --          information.
    --
    --        - A set of suggestions on how to break the cycle considering the
@@ -308,18 +308,13 @@ package body Bindo is
    --
    --        GNATbind utilizes the new bindo elaboration order
    --
-   --  -d_O  Output elaboration order
-   --
-   --        GNATbind outputs the elaboration order in text format to standard
-   --        output.
-   --
    --  -d_P  Output cycle paths
    --
    --        GNATbind output the cycle paths in text format to standard output
    --
-   --  -d_T  Output elaboration order trace information
+   --  -d_T  Output elaboration-order trace information
    --
-   --        GNATbind outputs trace information on elaboration order and cycle
+   --        GNATbind outputs trace information on elaboration-order and cycle-
    --        detection activities to standard output.
    --
    --  -d_V  Validate bindo cycles, graphs, and order
@@ -327,12 +322,126 @@ package body Bindo is
    --        GNATbind validates the invocation graph, library graph along with
    --        its cycles, and elaboration order by detecting inconsistencies and
    --        producing error reports.
+   --
+   --  -e    Output complete list of elaboration-order dependencies
+   --
+   --        GNATbind outputs the dependencies between units to standard
+   --        output.
+   --
+   --  -f    Force elaboration order from given file
+   --
+   --        GNATbind applies an additional set of edges to the library graph.
+   --        The edges are read from a file specified by the argument of the
+   --        flag.
+   --
+   --  -H    Legacy elaboration-order model enabled
+   --
+   --        GNATbind uses the library-graph and heuristics-based elaboration-
+   --        order model.
+   --
+   --  -l    Output chosen elaboration order
+   --
+   --        GNATbind outputs the elaboration order in text format to standard
+   --        output.
+   --
+   --  -p    Pessimistic (worst-case) elaboration order
+   --
+   --        This switch is not used in Bindo and its children.
 
    ----------------------------------------
-   -- Debugging elaboration order issues --
+   -- Debugging elaboration-order issues --
    ----------------------------------------
 
-   --  ??? more on this later
+   --  Prior to debugging elaboration-order-related issues, enable all relevant
+   --  debug flags to collect as much information as possible. Depending on the
+   --  number of files in the bind, Bindo may emit anywhere between several MBs
+   --  to several hundred MBs of data to standard output. The switches are:
+   --
+   --    -d_A -d_C -d_I -d_L -d_P -d_T -d_V
+   --
+   --  Bindo offers several debugging routines that can be invoked from gdb.
+   --  Those are defined in the body of Bindo.Writers, in sections denoted by
+   --  header Debug. For quick reference, the routines are:
+   --
+   --    palgc  --  print all library-graph cycles
+   --    pau    --  print all units
+   --    pc     --  print component
+   --    pige   --  print invocation-graph edge
+   --    pigv   --  print invocation-graph vertex
+   --    plgc   --  print library-graph cycle
+   --    plge   --  print library-graph edge
+   --    plgv   --  print library-graph vertex
+   --    pu     --  print units
+   --
+   --  * Invalid elaboration order
+   --
+   --    The elaboration order is invalid when:
+   --
+   --      - A unit that requires elaboration is missing from the order
+   --      - A unit that does not require elaboration is present in the order
+   --
+   --    Examine the output of the elaboration algorithm available via switch
+   --    -d_T to determine how the related units were included in or excluded
+   --    from the order. Determine whether the library graph contains all the
+   --    relevant edges for those units.
+   --
+   --    Units and routines of interest:
+   --      Bindo.Elaborators
+   --      Elaborate_Library_Graph
+   --      Elaborate_Units_Common
+   --      Elaborate_Units_Dynamic
+   --      Elaborate_Units_Static
+   --
+   --  * Invalid invocation graph
+   --
+   --    The invocation graph is invalid when:
+   --
+   --      - An edge lacks an attribute
+   --      - A vertex lacks an attribute
+   --
+   --    Find the malformed edge or vertex and determine which attribute is
+   --    missing. Examine the contents of the invocation-related ALI tables
+   --    available via switch -d_A. If the invocation construct or relation
+   --    is missing, verify the ALI file. If the ALI lacks all the relevant
+   --    information, then Sem_Elab most likely failed to discover a valid
+   --    elaboration path.
+   --
+   --    Units and routines of interest:
+   --      Bindo.Builders
+   --      Bindo.Graphs
+   --      Add_Edge
+   --      Add_Vertex
+   --      Build_Invocation_Graph
+   --
+   --  * Invalid library graph
+   --
+   --    The library graph is invalid when:
+   --
+   --      - An edge lacks an attribute
+   --      - A vertex lacks an attribute
+   --
+   --    Find the malformed edge or vertex and determine which attribute is
+   --    missing.
+   --
+   --    Units and routines of interest:
+   --      Bindo.Builders
+   --      Bindo.Graphs
+   --      Add_Edge
+   --      Add_Vertex
+   --      Build_Library_Graph
+   --
+   --  * Invalid library-graph cycle
+   --
+   --    A library-graph cycle is invalid when:
+   --
+   --      - It lacks enough edges to form a circuit
+   --      - At least one edge in the circuit is repeated
+   --
+   --    Find the malformed cycle and determine which attribute is missing.
+   --
+   --    Units and routines of interest:
+   --      Bindo.Graphs
+   --      Find_Cycles
 
    ----------------------------
    -- Find_Elaboration_Order --
@@ -343,7 +452,28 @@ package body Bindo is
       Main_Lib_File : File_Name_Type)
    is
    begin
-      --  Use the invocation and library graph-based elaboration order when
+      --  ??? Enable the following code when switching from the old to the new
+      --  elaboration-order mechanism.
+
+      --  Use the library graph and heuristic-based elaboration order when
+      --  switch -H (legacy elaboration-order mode enabled).
+
+      --  if Legacy_Elaboration_Order then
+      --     Binde.Find_Elab_Order (Order, Main_Lib_File);
+
+      --  Otherwise use the invocation and library-graph-based elaboration
+      --  order.
+
+      --  else
+      --     Invocation_And_Library_Graph_Elaborators.Elaborate_Units
+      --       (Order         => Order,
+      --        Main_Lib_File => Main_Lib_File);
+      --  end if;
+
+      --  ??? Remove the following code when switching from the old to the new
+      --  elaboration-order mechanism.
+
+      --  Use the invocation and library-graph-based elaboration order when
       --  switch -d_N (new bindo order) is in effect.
 
       if Debug_Flag_Underscore_NN then
@@ -351,7 +481,7 @@ package body Bindo is
            (Order         => Order,
             Main_Lib_File => Main_Lib_File);
 
-      --  Otherwise use the library graph and heuristic-based elaboration
+      --  Otherwise use the library-graph and heuristic-based elaboration
       --  order.
 
       else