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 subprogramsActivation 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 packageClient
. Note that the declaration of packageNested
is ignored according to the definition given above. As a result, the call toServer.Func
will be invoked when the spec of unitClient
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 theend
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 bodyClient
. As a result, the call toProc
will be invoked when the body ofClient
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:
The object declaration of
Result
is elaborated.Function
Server.Func
is invoked.
The subprogram body of
Proc
is elaborated.Procedure
Proc
is invoked.Generic unit
Server.Gen
is instantiated asInst
.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, genericPack.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 pragmaPure
, 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 toClient
by virtue of the with clause, and in addition the body ofServer
must be elaborated immediately after the spec ofServer
.Removing pragma
Elaborate_Body
could result in the following incorrect elaboration order:spec of Server spec of Client body of Server
where
Client
invokesServer.Func
, but the body ofServer.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
invokesServer.Func
, but the body ofServer.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
andComputer
, but the point is that these specs and bodies will be elaborated prior toClient
.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
invokesComputer.Compute
, which in turn invokesMath.Factorial
, but the body ofMath.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
, orSystem
hierarchies.The server unit has pragma
Pure
orPreelaborate
.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
.
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)