Elaboration Order Handling in GNAT

This appendix describes the handling of elaboration code in Ada and GNAT, and discusses how the order of elaboration of program units can be controlled in GNAT, either automatically or with explicit programming features.

Elaboration Code

Ada defines the term execution as the process by which a construct achieves its run-time effect. This process is also referred to as elaboration for declarations and evaluation for expressions.

The execution model in Ada allows for certain sections of an Ada program to be executed prior to execution of the program itself, primarily with the intent of initializing data. These sections are referred to as elaboration code. Elaboration code is executed as follows:

• All partitions of an Ada program are executed in parallel with one another, possibly in a separate address space, and possibly on a separate computer.

• The execution of a partition involves running the environment task for that partition.

• The environment task executes all elaboration code (if available) for all units within that partition. This code is said to be executed at elaboration time.

• The environment task executes the Ada program (if available) for that partition.

In addition to the Ada terminology, this appendix defines the following terms:

• Invocation

  The act of calling a subprogram, instantiating a generic, or activating a task.

• Scenario

  A construct that is elaborated or invoked by elaboration code is referred to as an elaboration scenario or simply a scenario. GNAT recognizes the following scenarios:

  • 'Access of entries, operators, and subprograms

  • Activation of tasks

  • Calls to entries, operators, and subprograms

  • Instantiations of generic templates

• Target

  A construct elaborated by a scenario is referred to as elaboration target or simply target. GNAT recognizes the following targets:

  • For 'Access of entries, operators, and subprograms, the target is the entry, operator, or subprogram being aliased.

  • For activation of tasks, the target is the task body

  • For calls to entries, operators, and subprograms, the target is the entry, operator, or subprogram being invoked.

  • For instantiations of generic templates, the target is the generic template being instantiated.

Elaboration code may appear in two distinct contexts:

• Library level

  A scenario appears at the library level when it is encapsulated by a package [body] compilation unit, ignoring any other package [body] declarations in between.

  with Server;
  package Client is
     procedure Proc;
  
     package Nested is
        Val : ... := Server.Func;
     end Nested;
  end Client;
  

  In the example above, the call to Server.Func is an elaboration scenario because it appears at the library level of package Client. Note that the declaration of package Nested is ignored according to the definition given above. As a result, the call to Server.Func will be invoked when the spec of unit Client is elaborated.

• Package body statements

  A scenario appears within the statement sequence of a package body when it is bounded by the region starting from the begin keyword of the package body and ending at the end keyword of the package body.

  package body Client is
     procedure Proc is
     begin
        ...
     end Proc;
  begin
     Proc;
  end Client;
  

  In the example above, the call to Proc is an elaboration scenario because it appears within the statement sequence of package body Client. As a result, the call to Proc will be invoked when the body of Client is elaborated.

Elaboration Order

The sequence by which the elaboration code of all units within a partition is executed is referred to as elaboration order.

Within a single unit, elaboration code is executed in sequential order.

package body Client is
   Result : ... := Server.Func;

   procedure Proc is
      package Inst is new Server.Gen;
   begin
      Inst.Eval (Result);
   end Proc;
begin
   Proc;
end Client;

In the example above, the elaboration order within package body Client is as follows:

1. The object declaration of Result is elaborated.

   • Function Server.Func is invoked.

2. The subprogram body of Proc is elaborated.

3. Procedure Proc is invoked.

   • Generic unit Server.Gen is instantiated as Inst.

   • Instance Inst is elaborated.

   • Procedure Inst.Eval is invoked.

The elaboration order of all units within a partition depends on the following factors:

• withed units

• parent units

• purity of units

• preelaborability of units

• presence of elaboration-control pragmas

• invocations performed in elaboration code

A program may have several elaboration orders depending on its structure.

package Server is
   function Func (Index : Integer) return Integer;
end Server;

package body Server is
   Results : array (1 .. 5) of Integer := (1, 2, 3, 4, 5);

   function Func (Index : Integer) return Integer is
   begin
      return Results (Index);
   end Func;
end Server;

with Server;
package Client is
   Val : constant Integer := Server.Func (3);
end Client;

with Client;
procedure Main is begin null; end Main;

The following elaboration order exhibits a fundamental problem referred to as access-before-elaboration or simply ABE.

spec of Server
spec of Client
body of Server
body of Main

The elaboration of Server’s spec materializes function Func, making it callable. The elaboration of Client’s spec elaborates the declaration of Val. This invokes function Server.Func, however the body of Server.Func has not been elaborated yet because Server’s body comes after Client’s spec in the elaboration order. As a result, the value of constant Val is now undefined.

Without any guarantees from the language, an undetected ABE problem may hinder proper initialization of data, which in turn may lead to undefined behavior at run time. To prevent such ABE problems, Ada employs dynamic checks in the same vein as index or null exclusion checks. A failed ABE check raises exception Program_Error.

The following elaboration order avoids the ABE problem and the program can be successfully elaborated.

spec of Server
body of Server
spec of Client
body of Main

Ada states that a total elaboration order must exist, but it does not define what this order is. A compiler is thus tasked with choosing a suitable elaboration order which satisfies the dependencies imposed by with clauses, unit categorization, elaboration-control pragmas, and invocations performed in elaboration code. Ideally an order that avoids ABE problems should be chosen, however a compiler may not always find such an order due to complications with respect to control and data flow.

Checking the Elaboration Order

To avoid placing the entire elaboration-order burden on the programmer, Ada provides three lines of defense:

• Static semantics

  Static semantic rules restrict the possible choice of elaboration order. For instance, if unit Client withs unit Server, then the spec of Server is always elaborated prior to Client. The same principle applies to child units - the spec of a parent unit is always elaborated prior to the child unit.

• Dynamic semantics

  Dynamic checks are performed at run time, to ensure that a target is elaborated prior to a scenario that invokes it, thus avoiding ABE problems. A failed run-time check raises exception Program_Error. The following restrictions apply:

  • Restrictions on calls

    An entry, operator, or subprogram can be called from elaboration code only when the corresponding body has been elaborated.

  • Restrictions on instantiations

    A generic unit can be instantiated by elaboration code only when the corresponding body has been elaborated.

  • Restrictions on task activation

    A task can be activated by elaboration code only when the body of the associated task type has been elaborated.

  The restrictions above can be summarized by the following rule:

  If a target has a body, then this body must be elaborated prior to the scenario that invokes the target.

• Elaboration control

  Pragmas are provided for the programmer to specify the desired elaboration order.

Controlling the Elaboration Order in Ada

Ada provides several idioms and pragmas to aid the programmer with specifying the desired elaboration order and avoiding ABE problems altogether.

• Packages without a body

  A library package which does not require a completing body does not suffer from ABE problems.

  package Pack is
     generic
        type Element is private;
     package Containers is
        type Element_Array is array (1 .. 10) of Element;
     end Containers;
  end Pack;
  

  In the example above, package Pack does not require a body because it does not contain any constructs which require completion in a body. As a result, generic Pack.Containers can be instantiated without encountering any ABE problems.

• pragma Pure

  Pragma Pure places sufficient restrictions on a unit to guarantee that no scenario within the unit can result in an ABE problem.

• pragma Preelaborate

  Pragma Preelaborate is slightly less restrictive than pragma Pure, but still strong enough to prevent ABE problems within a unit.

• pragma Elaborate_Body

  Pragma Elaborate_Body requires that the body of a unit is elaborated immediately after its spec. This restriction guarantees that no client scenario can invoke a server target before the target body has been elaborated because the spec and body are effectively “glued” together.

  package Server is
     pragma Elaborate_Body;
  
     function Func return Integer;
  end Server;
  

  package body Server is
     function Func return Integer is
     begin
        ...
     end Func;
  end Server;
  

  with Server;
  package Client is
     Val : constant Integer := Server.Func;
  end Client;
  

  In the example above, pragma Elaborate_Body guarantees the following elaboration order:

  spec of Server
  body of Server
  spec of Client
  

  because the spec of Server must be elaborated prior to Client by virtue of the with clause, and in addition the body of Server must be elaborated immediately after the spec of Server.

  Removing pragma Elaborate_Body could result in the following incorrect elaboration order:

  spec of Server
  spec of Client
  body of Server
  

  where Client invokes Server.Func, but the body of Server.Func has not been elaborated yet.

The pragmas outlined above allow a server unit to guarantee safe elaboration use by client units. Thus it is a good rule to mark units as Pure or Preelaborate, and if this is not possible, mark them as Elaborate_Body.

There are however situations where Pure, Preelaborate, and Elaborate_Body are not applicable. Ada provides another set of pragmas for use by client units to help ensure the elaboration safety of server units they depend on.

• pragma Elaborate (Unit)

  Pragma Elaborate can be placed in the context clauses of a unit, after a with clause. It guarantees that both the spec and body of its argument will be elaborated prior to the unit with the pragma. Note that other unrelated units may be elaborated in between the spec and the body.

  package Server is
     function Func return Integer;
  end Server;
  

  package body Server is
     function Func return Integer is
     begin
        ...
     end Func;
  end Server;
  

  with Server;
  pragma Elaborate (Server);
  package Client is
     Val : constant Integer := Server.Func;
  end Client;
  

  In the example above, pragma Elaborate guarantees the following elaboration order:

  spec of Server
  body of Server
  spec of Client
  

  Removing pragma Elaborate could result in the following incorrect elaboration order:

  spec of Server
  spec of Client
  body of Server
  

  where Client invokes Server.Func, but the body of Server.Func has not been elaborated yet.

• pragma Elaborate_All (Unit)

  Pragma Elaborate_All is placed in the context clauses of a unit, after a with clause. It guarantees that both the spec and body of its argument will be elaborated prior to the unit with the pragma, as well as all units withed by the spec and body of the argument, recursively. Note that other unrelated units may be elaborated in between the spec and the body.

  package Math is
     function Factorial (Val : Natural) return Natural;
  end Math;
  

  package body Math is
     function Factorial (Val : Natural) return Natural is
     begin
        ...;
     end Factorial;
  end Math;
  

  package Computer is
     type Operation_Kind is (None, Op_Factorial);
  
     function Compute
       (Val : Natural;
        Op  : Operation_Kind) return Natural;
  end Computer;
  

  with Math;
  package body Computer is
     function Compute
       (Val : Natural;
        Op  : Operation_Kind) return Natural
     is
        if Op = Op_Factorial then
           return Math.Factorial (Val);
        end if;
  
        return 0;
     end Compute;
  end Computer;
  

  with Computer;
  pragma Elaborate_All (Computer);
  package Client is
     Val : constant Natural :=
             Computer.Compute (123, Computer.Op_Factorial);
  end Client;
  

  In the example above, pragma Elaborate_All can result in the following elaboration order:

  spec of Math
  body of Math
  spec of Computer
  body of Computer
  spec of Client
  

  Note that there are several allowable suborders for the specs and bodies of Math and Computer, but the point is that these specs and bodies will be elaborated prior to Client.

  Removing pragma Elaborate_All could result in the following incorrect elaboration order:

  spec of Math
  spec of Computer
  body of Computer
  spec of Client
  body of Math
  

  where Client invokes Computer.Compute, which in turn invokes Math.Factorial, but the body of Math.Factorial has not been elaborated yet.

All pragmas shown above can be summarized by the following rule:

If a client unit elaborates a server target directly or indirectly, then if the server unit requires a body and does not have pragma Pure, Preelaborate, or Elaborate_Body, then the client unit should have pragma Elaborate or Elaborate_All for the server unit.

If the rule outlined above is not followed, then a program may fall in one of the following states:

• No elaboration order exists

  In this case a compiler must diagnose the situation, and refuse to build an executable program.

• One or more incorrect elaboration orders exist

  In this case a compiler can build an executable program, but Program_Error will be raised when the program is run.

• Several elaboration orders exist, some correct, some incorrect

  In this case the programmer has not controlled the elaboration order. As a result, a compiler may or may not pick one of the correct orders, and the program may or may not raise Program_Error when it is run. This is the worst possible state because the program may fail on another compiler, or even another version of the same compiler.

• One or more correct orders exist

  In this case a compiler can build an executable program, and the program is run successfully. This state may be guaranteed by following the outlined rules, or may be the result of good program architecture.

Note that one additional advantage of using Elaborate and Elaborate_All is that the program continues to stay in the last state (one or more correct orders exist) even if maintenance changes the bodies of targets.

Controlling the Elaboration Order in GNAT

In addition to Ada semantics and rules synthesized from them, GNAT offers three elaboration models to aid the programmer with specifying the correct elaboration order and to diagnose elaboration problems.

• Dynamic elaboration model

  This is the most permissive of the three elaboration models and emulates the behavior specified by the Ada Reference Manual. When the dynamic model is in effect, GNAT makes the following assumptions:

  • All code within all units in a partition is considered to be elaboration code.

  • Some of the invocations in elaboration code may not take place at run time due to conditional execution.

  GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios that invoke internal targets. In addition, GNAT generates run-time checks for all external targets and for all scenarios that may exhibit ABE problems.

  The elaboration order is obtained by honoring all with clauses, purity and preelaborability of units, and elaboration-control pragmas. The dynamic model attempts to take all invocations in elaboration code into account. If an invocation leads to a circularity, GNAT ignores the invocation based on the assumptions stated above. An order obtained using the dynamic model may fail an ABE check at run time when GNAT ignored an invocation.

  The dynamic model is enabled with compiler switch -gnatE.

• Static elaboration model

  This is the middle ground of the three models. When the static model is in effect, GNAT makes the following assumptions:

  • Only code at the library level and in package body statements within all units in a partition is considered to be elaboration code.

  • All invocations in elaboration will take place at run time, regardless of conditional execution.

  GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios that invoke internal targets. In addition, GNAT generates run-time checks for all external targets and for all scenarios that may exhibit ABE problems.

  The elaboration order is obtained by honoring all with clauses, purity and preelaborability of units, presence of elaboration-control pragmas, and all invocations in elaboration code. An order obtained using the static model is guaranteed to be ABE problem-free, excluding dispatching calls and access-to-subprogram types.

  The static model is the default model in GNAT.

• SPARK elaboration model

  This is the most conservative of the three models and enforces the SPARK rules of elaboration as defined in the SPARK Reference Manual, section 7.7. The SPARK model is in effect only when a scenario and a target reside in a region subject to SPARK_Mode On, otherwise the dynamic or static model is in effect.

  The SPARK model is enabled with compiler switch -gnatd.v.

• Legacy elaboration models

  In addition to the three elaboration models outlined above, GNAT provides the following legacy models:

  • Legacy elaboration-checking model available in pre-18.x versions of GNAT. This model is enabled with compiler switch -gnatH.

  • Legacy elaboration-order model available in pre-20.x versions of GNAT. This model is enabled with binder switch -H.

The dynamic, legacy, and static models can be relaxed using compiler switch -gnatJ, making them more permissive. Note that in this mode, GNAT may not diagnose certain elaboration issues or install run-time checks.

Mixing Elaboration Models

It is possible to mix units compiled with a different elaboration model, however the following rules must be observed:

• A client unit compiled with the dynamic model can only with a server unit that meets at least one of the following criteria:

  • The server unit is compiled with the dynamic model.

  • The server unit is a GNAT implementation unit from the Ada, GNAT, Interfaces, or System hierarchies.

  • The server unit has pragma Pure or Preelaborate.

  • The client unit has an explicit Elaborate_All pragma for the server unit.

These rules ensure that elaboration checks are not omitted. If the rules are violated, the binder emits a warning:

warning: "x.ads" has dynamic elaboration checks and with's
warning:   "y.ads" which has static elaboration checks

The warnings can be suppressed by binder switch -ws.

ABE Diagnostics

GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios that invoke internal targets, regardless of whether the dynamic, SPARK, or static model is in effect.

Note that GNAT emits warnings rather than hard errors whenever it encounters an elaboration problem. This is because the elaboration model in effect may be too conservative, or a particular scenario may not be invoked due conditional execution. The warnings can be suppressed selectively with pragma Warnings (Off) or globally with compiler switch -gnatwL.

A guaranteed ABE arises when the body of a target is not elaborated early enough, and causes all scenarios that directly invoke the target to fail.

package body Guaranteed_ABE is
   function ABE return Integer;

   Val : constant Integer := ABE;

   function ABE return Integer is
   begin
     ...
   end ABE;
end Guaranteed_ABE;

In the example above, the elaboration of Guaranteed_ABE’s body elaborates the declaration of Val. This invokes function ABE, however the body of ABE has not been elaborated yet. GNAT emits the following diagnostic:

4.    Val : constant Integer := ABE;
                                |
   >>> warning: cannot call "ABE" before body seen
   >>> warning: Program_Error will be raised at run time

A conditional ABE arises when the body of a target is not elaborated early enough, and causes some scenarios that directly invoke the target to fail.

 1. package body Conditional_ABE is
 2.    procedure Force_Body is null;
 3.
 4.    generic
 5.       with function Func return Integer;
 6.    package Gen is
 7.       Val : constant Integer := Func;
 8.    end Gen;
 9.
10.    function ABE return Integer;
11.
12.    function Cause_ABE return Boolean is
13.       package Inst is new Gen (ABE);
14.    begin
15.       ...
16.    end Cause_ABE;
17.
18.    Val : constant Boolean := Cause_ABE;
19.
20.    function ABE return Integer is
21.    begin
22.       ...
23.    end ABE;
24.
25.    Safe : constant Boolean := Cause_ABE;
26. end Conditional_ABE;

In the example above, the elaboration of package body Conditional_ABE elaborates the declaration of Val. This invokes function Cause_ABE, which instantiates generic unit Gen as Inst. The elaboration of Inst invokes function ABE, however the body of ABE has not been elaborated yet. GNAT emits the following diagnostic:

13.       package Inst is new Gen (ABE);
          |
    >>> warning: in instantiation at line 7
    >>> warning: cannot call "ABE" before body seen
    >>> warning: Program_Error may be raised at run time
    >>> warning:   body of unit "Conditional_ABE" elaborated
    >>> warning:   function "Cause_ABE" called at line 18
    >>> warning:   function "ABE" called at line 7, instance at line 13

Note that the same ABE problem does not occur with the elaboration of declaration Safe because the body of function ABE has already been elaborated at that point.

SPARK Diagnostics

GNAT enforces the SPARK rules of elaboration as defined in the SPARK Reference Manual section 7.7 when compiler switch -gnatd.v is in effect. Note that GNAT emits hard errors whenever it encounters a violation of the SPARK rules.

1. with Server;
2. package body SPARK_Diagnostics with SPARK_Mode is
3.    Val : constant Integer := Server.Func;
                                      |
   >>> call to "Func" during elaboration in SPARK
   >>> unit "SPARK_Diagnostics" requires pragma "Elaborate_All" for "Server"
   >>>   body of unit "SPARK_Model" elaborated
   >>>   function "Func" called at line 3

4. end SPARK_Diagnostics;

Elaboration Circularities

An elaboration circularity occurs whenever the elaboration of a set of units enters a deadlocked state, where each unit is waiting for another unit to be elaborated. This situation may be the result of improper use of with clauses, elaboration-control pragmas, or invocations in elaboration code.

The following example exhibits an elaboration circularity.

with B; pragma Elaborate (B);
package A is
end A;

package B is
   procedure Force_Body;
end B;

with C;
package body B is
   procedure Force_Body is null;

   Elab : constant Integer := C.Func;
end B;

package C is
   function Func return Integer;
end C;

with A;
package body C is
   function Func return Integer is
   begin
      ...
   end Func;
end C;

The binder emits the following diagnostic:

error: Elaboration circularity detected
info:
info:    Reason:
info:
info:      unit "a (spec)" depends on its own elaboration
info:
info:    Circularity:
info:
info:      unit "a (spec)" has with clause and pragma Elaborate for unit "b (spec)"
info:      unit "b (body)" is in the closure of pragma Elaborate
info:      unit "b (body)" invokes a construct of unit "c (body)" at elaboration time
info:      unit "c (body)" has with clause for unit "a (spec)"
info:
info:    Suggestions:
info:
info:      remove pragma Elaborate for unit "b (body)" in unit "a (spec)"
info:      use the dynamic elaboration model (compiler switch -gnatE)

The diagnostic consist of the following sections:

• Reason

  This section provides a short explanation describing why the set of units could not be ordered.

• Circularity

  This section enumerates the units comprising the deadlocked set, along with their interdependencies.

• Suggestions

  This section enumerates various tactics for eliminating the circularity.

Resolving Elaboration Circularities

The most desirable option from the point of view of long-term maintenance is to rearrange the program so that the elaboration problems are avoided. One useful technique is to place the elaboration code into separate child packages. Another is to move some of the initialization code to explicitly invoked subprograms, where the program controls the order of initialization explicitly. Although this is the most desirable option, it may be impractical and involve too much modification, especially in the case of complex legacy code.

When faced with an elaboration circularity, the programmer should also consider the tactics given in the suggestions section of the circularity diagnostic. Depending on the units involved in the circularity, their with clauses, purity, preelaborability, presence of elaboration-control pragmas and invocations at elaboration time, the binder may suggest one or more of the following tactics to eliminate the circularity:

• Pragma Elaborate elimination

  remove pragma Elaborate for unit "..." in unit "..."
  

  This tactic is suggested when the binder has determined that pragma Elaborate:

  • Prevents a set of units from being elaborated.

  • The removal of the pragma will not eliminate the semantic effects of the pragma. In other words, the argument of the pragma will still be elaborated prior to the unit containing the pragma.

  • The removal of the pragma will enable the successful ordering of the units.

  The programmer should remove the pragma as advised, and rebuild the program.

• Pragma Elaborate_All elimination

  remove pragma Elaborate_All for unit "..." in unit "..."
  

  This tactic is suggested when the binder has determined that pragma Elaborate_All:

  • Prevents a set of units from being elaborated.

  • The removal of the pragma will not eliminate the semantic effects of the pragma. In other words, the argument of the pragma along with its with closure will still be elaborated prior to the unit containing the pragma.

  • The removal of the pragma will enable the successful ordering of the units.

  The programmer should remove the pragma as advised, and rebuild the program.

• Pragma Elaborate_All downgrade

  change pragma Elaborate_All for unit "..." to Elaborate in unit "..."
  

  This tactic is always suggested with the pragma Elaborate_All elimination tactic. It offers a different alternative of guaranteeing that the argument of the pragma will still be elaborated prior to the unit containing the pragma.

  The programmer should update the pragma as advised, and rebuild the program.

• Pragma Elaborate_Body elimination

  remove pragma Elaborate_Body in unit "..."
  

  This tactic is suggested when the binder has determined that pragma Elaborate_Body:

  • Prevents a set of units from being elaborated.

  • The removal of the pragma will enable the successful ordering of the units.

  Note that the binder cannot determine whether the pragma is required for other purposes, such as guaranteeing the initialization of a variable declared in the spec by elaboration code in the body.

  The programmer should remove the pragma as advised, and rebuild the program.

• Use of pragma Restrictions

  use pragma Restrictions (No_Entry_Calls_In_Elaboration_Code)
  

  This tactic is suggested when the binder has determined that a task activation at elaboration time:

  • Prevents a set of units from being elaborated.

  Note that the binder cannot determine with certainty whether the task will block at elaboration time.

  The programmer should create a configuration file, place the pragma within, update the general compilation arguments, and rebuild the program.

• Use of dynamic elaboration model

  use the dynamic elaboration model (compiler switch -gnatE)
  

  This tactic is suggested when the binder has determined that an invocation at elaboration time:

  • Prevents a set of units from being elaborated.

  • The use of the dynamic model will enable the successful ordering of the units.

  The programmer has two options:

  • Determine the units involved in the invocation using the detailed invocation information, and add compiler switch -gnatE to the compilation arguments of selected files only. This approach will yield safer elaboration orders compared to the other option because it will minimize the opportunities presented to the dynamic model for ignoring invocations.

  • Add compiler switch -gnatE to the general compilation arguments.

• Use of detailed invocation information

  use detailed invocation information (compiler switch -gnatd_F)
  

  This tactic is always suggested with the use of the dynamic model tactic. It causes the circularity section of the circularity diagnostic to describe the flow of elaboration code from a unit to a unit, enumerating all such paths in the process.

  The programmer should analyze this information to determine which units should be compiled with the dynamic model.

• Forced-dependency elimination

  remove the dependency of unit "..." on unit "..." from the argument of switch -f
  

  This tactic is suggested when the binder has determined that a dependency present in the forced-elaboration-order file indicated by binder switch -f:

  • Prevents a set of units from being elaborated.

  • The removal of the dependency will enable the successful ordering of the units.

  The programmer should edit the forced-elaboration-order file, remove the dependency, and rebind the program.

• All forced-dependency elimination

  remove switch -f
  

  This tactic is suggested in case editing the forced-elaboration-order file is not an option.

  The programmer should remove binder switch -f from the binder arguments, and rebind.

• Multiple-circularities diagnostic

  diagnose all circularities (binder switch -d_C)
  

  By default, the binder will diagnose only the highest-precedence circularity. If the program contains multiple circularities, the binder will suggest the use of binder switch -d_C in order to obtain the diagnostics of all circularities.

  The programmer should add binder switch -d_C to the binder arguments, and rebind.

If none of the tactics suggested by the binder eliminate the elaboration circularity, the programmer should consider using one of the legacy elaboration models, in the following order:

• Use the pre-20.x legacy elaboration-order model, with binder switch -H.

• Use both pre-18.x and pre-20.x legacy elaboration models, with compiler switch -gnatH and binder switch -H.

• Use the relaxed static-elaboration model, with compiler switches -gnatH -gnatJ and binder switch -H.

• Use the relaxed dynamic-elaboration model, with compiler switches -gnatH -gnatJ -gnatE and binder switch -H.

Elaboration-related Compiler Switches

GNAT has several switches that affect the elaboration model and consequently the elaboration order chosen by the binder.

-gnatE

Dynamic elaboration checking mode enabled

When this switch is in effect, GNAT activates the dynamic model.

-gnatel

Turn on info messages on generated Elaborate[_All] pragmas

This switch is only applicable to the pre-20.x legacy elaboration models. The post-20.x elaboration model no longer relies on implicitly generated Elaborate and Elaborate_All pragmas to order units.

When this switch is in effect, GNAT will emit the following supplementary information depending on the elaboration model in effect.

• Dynamic model

  GNAT will indicate missing Elaborate and Elaborate_All pragmas for all library-level scenarios within the partition.

• Static model

  GNAT will indicate all scenarios invoked during elaboration. In addition, it will provide detailed traceback when an implicit Elaborate or Elaborate_All pragma is generated.

• SPARK model

  GNAT will indicate how an elaboration requirement is met by the context of a unit. This diagnostic requires compiler switch -gnatd.v.

  1. with Server; pragma Elaborate_All (Server);
  2. package Client with SPARK_Mode is
  3.    Val : constant Integer := Server.Func;
                                        |
     >>> info: call to "Func" during elaboration in SPARK
     >>> info: "Elaborate_All" requirement for unit "Server" met by pragma at line 1
  
  4. end Client;
  

-gnatH

Legacy elaboration checking mode enabled

When this switch is in effect, GNAT will utilize the pre-18.x elaboration model.

-gnatJ

Relaxed elaboration checking mode enabled

When this switch is in effect, GNAT will not process certain scenarios, resulting in a more permissive elaboration model. Note that this may eliminate some diagnostics and run-time checks.

-gnatw.f

Turn on warnings for suspicious Subp’Access

When this switch is in effect, GNAT will treat 'Access of an entry, operator, or subprogram as a potential call to the target and issue warnings:

 1. package body Attribute_Call is
 2.    function Func return Integer;
 3.    type Func_Ptr is access function return Integer;
 4.
 5.    Ptr : constant Func_Ptr := Func'Access;
                                      |
    >>> warning: "Access" attribute of "Func" before body seen
    >>> warning: possible Program_Error on later references
    >>> warning:   body of unit "Attribute_Call" elaborated
    >>> warning:   "Access" of "Func" taken at line 5

 6.
 7.    function Func return Integer is
 8.    begin
 9.       ...
10.    end Func;
11. end Attribute_Call;

In the example above, the elaboration of declaration Ptr is assigned Func'Access before the body of Func has been elaborated.

-gnatwl

Turn on warnings for elaboration problems

When this switch is in effect, GNAT emits diagnostics in the form of warnings concerning various elaboration problems. The warnings are enabled by default. The switch is provided in case all warnings are suppressed, but elaboration warnings are still desired.

-gnatwL

Turn off warnings for elaboration problems

When this switch is in effect, GNAT no longer emits any diagnostics in the form of warnings. Selective suppression of elaboration problems is possible using pragma Warnings (Off).

 1. package body Selective_Suppression is
 2.    function ABE return Integer;
 3.
 4.    Val_1 : constant Integer := ABE;
                                   |
    >>> warning: cannot call "ABE" before body seen
    >>> warning: Program_Error will be raised at run time

 5.
 6.    pragma Warnings (Off);
 7.    Val_2 : constant Integer := ABE;
 8.    pragma Warnings (On);
 9.
10.    function ABE return Integer is
11.    begin
12.       ...
13.    end ABE;
14. end Selective_Suppression;

Note that suppressing elaboration warnings does not eliminate run-time checks. The example above will still fail at run time with an ABE.

Summary of Procedures for Elaboration Control

A programmer should first compile the program with the default options, using none of the binder or compiler switches. If the binder succeeds in finding an elaboration order, then apart from possible cases involving dispatching calls and access-to-subprogram types, the program is free of elaboration errors.

If it is important for the program to be portable to compilers other than GNAT, then the programmer should use compiler switch -gnatel and consider the messages about missing or implicitly created Elaborate and Elaborate_All pragmas.

If the binder reports an elaboration circularity, the programmer has several options:

• Ensure that elaboration warnings are enabled. This will allow the static model to output trace information of elaboration issues. The trace information could shed light on previously unforeseen dependencies, as well as their origins. Elaboration warnings are enabled with compiler switch -gnatwl.

• Cosider the tactics given in the suggestions section of the circularity diagnostic.

• If none of the steps outlined above resolve the circularity, use a more permissive elaboration model, in the following order:

  • Use the pre-20.x legacy elaboration-order model, with binder switch -H.

  • Use both pre-18.x and pre-20.x legacy elaboration models, with compiler switch -gnatH and binder switch -H.

  • Use the relaxed static elaboration model, with compiler switches -gnatH -gnatJ and binder switch -H.

  • Use the relaxed dynamic elaboration model, with compiler switches -gnatH -gnatJ -gnatE and binder switch -H.

Inspecting the Chosen Elaboration Order

To see the elaboration order chosen by the binder, inspect the contents of file b~xxx.adb. On certain targets, this file appears as b_xxx.adb. The elaboration order appears as a sequence of calls to Elab_Body and Elab_Spec, interspersed with assignments to Exxx which indicates that a particular unit is elaborated. For example:

System.Soft_Links'Elab_Body;
E14 := True;
System.Secondary_Stack'Elab_Body;
E18 := True;
System.Exception_Table'Elab_Body;
E24 := True;
Ada.Io_Exceptions'Elab_Spec;
E67 := True;
Ada.Tags'Elab_Spec;
Ada.Streams'Elab_Spec;
E43 := True;
Interfaces.C'Elab_Spec;
E69 := True;
System.Finalization_Root'Elab_Spec;
E60 := True;
System.Os_Lib'Elab_Body;
E71 := True;
System.Finalization_Implementation'Elab_Spec;
System.Finalization_Implementation'Elab_Body;
E62 := True;
Ada.Finalization'Elab_Spec;
E58 := True;
Ada.Finalization.List_Controller'Elab_Spec;
E76 := True;
System.File_Control_Block'Elab_Spec;
E74 := True;
System.File_Io'Elab_Body;
E56 := True;
Ada.Tags'Elab_Body;
E45 := True;
Ada.Text_Io'Elab_Spec;
Ada.Text_Io'Elab_Body;
E07 := True;

Note also binder switch -l, which outputs the chosen elaboration order and provides a more readable form of the above:

ada (spec)
interfaces (spec)
system (spec)
system.case_util (spec)
system.case_util (body)
system.concat_2 (spec)
system.concat_2 (body)
system.concat_3 (spec)
system.concat_3 (body)
system.htable (spec)
system.parameters (spec)
system.parameters (body)
system.crtl (spec)
interfaces.c_streams (spec)
interfaces.c_streams (body)
system.restrictions (spec)
system.restrictions (body)
system.standard_library (spec)
system.exceptions (spec)
system.exceptions (body)
system.storage_elements (spec)
system.storage_elements (body)
system.secondary_stack (spec)
system.stack_checking (spec)
system.stack_checking (body)
system.string_hash (spec)
system.string_hash (body)
system.htable (body)
system.strings (spec)
system.strings (body)
system.traceback (spec)
system.traceback (body)
system.traceback_entries (spec)
system.traceback_entries (body)
ada.exceptions (spec)
ada.exceptions.last_chance_handler (spec)
system.soft_links (spec)
system.soft_links (body)
ada.exceptions.last_chance_handler (body)
system.secondary_stack (body)
system.exception_table (spec)
system.exception_table (body)
ada.io_exceptions (spec)
ada.tags (spec)
ada.streams (spec)
interfaces.c (spec)
interfaces.c (body)
system.finalization_root (spec)
system.finalization_root (body)
system.memory (spec)
system.memory (body)
system.standard_library (body)
system.os_lib (spec)
system.os_lib (body)
system.unsigned_types (spec)
system.stream_attributes (spec)
system.stream_attributes (body)
system.finalization_implementation (spec)
system.finalization_implementation (body)
ada.finalization (spec)
ada.finalization (body)
ada.finalization.list_controller (spec)
ada.finalization.list_controller (body)
system.file_control_block (spec)
system.file_io (spec)
system.file_io (body)
system.val_uns (spec)
system.val_util (spec)
system.val_util (body)
system.val_uns (body)
system.wch_con (spec)
system.wch_con (body)
system.wch_cnv (spec)
system.wch_jis (spec)
system.wch_jis (body)
system.wch_cnv (body)
system.wch_stw (spec)
system.wch_stw (body)
ada.tags (body)
ada.exceptions (body)
ada.text_io (spec)
ada.text_io (body)
text_io (spec)
gdbstr (body)