4.3.15 Debugging Control

-gnatd`x'

Activate internal debugging switches. x is a letter or digit, or string of letters or digits, which specifies the type of debugging outputs desired. Normally these are used only for internal development or system debugging purposes. You can find full documentation for these switches in the body of the Debug unit in the compiler source file debug.adb.

-gnatG[=`nn']

This switch causes the compiler to generate auxiliary output containing a pseudo-source listing of the generated expanded code. Like most Ada compilers, GNAT works by first transforming the high level Ada code into lower level constructs. For example, tasking operations are transformed into calls to the tasking run-time routines. A unique capability of GNAT is to list this expanded code in a form very close to normal Ada source. This is very useful in understanding the implications of various Ada usage on the efficiency of the generated code. There are many cases in Ada (e.g., the use of controlled types), where simple Ada statements can generate a lot of run-time code. By using -gnatG you can identify these cases, and consider whether it may be desirable to modify the coding approach to improve efficiency.

The optional parameter nn if present after -gnatG specifies an alternative maximum line length that overrides the normal default of 72. This value is in the range 40-999999, values less than 40 being silently reset to 40. The equal sign is optional.

The format of the output is very similar to standard Ada source, and is easily understood by an Ada programmer. The following special syntactic additions correspond to low level features used in the generated code that do not have any exact analogies in pure Ada source form. The following is a partial list of these special constructions. See the spec of package Sprint in file sprint.ads for a full list.

If the switch -gnatL is used in conjunction with -gnatG, then the original source lines are interspersed in the expanded source (as comment lines with the original line number).

new `xxx' [storage_pool = `yyy']

Shows the storage pool being used for an allocator.

at end `procedure-name';

Shows the finalization (cleanup) procedure for a scope.

(if `expr' then `expr' else `expr')

Conditional expression equivalent to the x?y:z construction in C.

`target'^(`source')

A conversion with floating-point truncation instead of rounding.

`target'?(`source')

A conversion that bypasses normal Ada semantic checking. In particular enumeration types and fixed-point types are treated simply as integers.

`target'?^(`source')

Combines the above two cases.

`x' #/ `y'

`x' #mod `y'

`x' # `y'

`x' #rem `y'

A division or multiplication of fixed-point values which are treated as integers without any kind of scaling.

free `expr' [storage_pool = `xxx']

Shows the storage pool associated with a free statement.

[subtype or type declaration]

Used to list an equivalent declaration for an internally generated type that is referenced elsewhere in the listing.

freeze `type-name' [`actions']

Shows the point at which type-name is frozen, with possible associated actions to be performed at the freeze point.

reference `itype'

Reference (and hence definition) to internal type itype.

`function-name'! (`arg', `arg', `arg')

Intrinsic function call.

`label-name' : label

Declaration of label labelname.

#$ `subprogram-name'

An implicit call to a run-time support routine (to meet the requirement of H.3.1(9) in a convenient manner).

`expr' && `expr' && `expr' ... && `expr'

A multiple concatenation (same effect as expr & expr & expr, but handled more efficiently).

[constraint_error]

Raise the Constraint_Error exception.

`expression''reference

A pointer to the result of evaluating {expression}.

`target-type'!(`source-expression')

An unchecked conversion of source-expression to target-type.

[`numerator'/`denominator']

Used to represent internal real literals (that) have no exact representation in base 2-16 (for example, the result of compile time evaluation of the expression 1.0/27.0).

-gnatD[=nn]

When used in conjunction with -gnatG, this switch causes the expanded source, as described above for -gnatG to be written to files with names xxx.dg, where xxx is the normal file name, instead of to the standard output file. For example, if the source file name is hello.adb, then a file hello.adb.dg will be written. The debugging information generated by the gcc -g switch will refer to the generated xxx.dg file. This allows you to do source level debugging using the generated code which is sometimes useful for complex code, for example to find out exactly which part of a complex construction raised an exception. This switch also suppresses generation of cross-reference information (see -gnatx) since otherwise the cross-reference information would refer to the .dg file, which would cause confusion since this is not the original source file.

Note that -gnatD actually implies -gnatG automatically, so it is not necessary to give both options. In other words -gnatD is equivalent to -gnatDG).

If the switch -gnatL is used in conjunction with -gnatDG, then the original source lines are interspersed in the expanded source (as comment lines with the original line number).

The optional parameter nn if present after -gnatD specifies an alternative maximum line length that overrides the normal default of 72. This value is in the range 40-999999, values less than 40 being silently reset to 40. The equal sign is optional.

-gnatr

This switch causes pragma Restrictions to be treated as Restriction_Warnings so that violation of restrictions causes warnings rather than illegalities. This is useful during the development process when new restrictions are added or investigated. The switch also causes pragma Profile to be treated as Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set restriction warnings rather than restrictions.

-gnatR[0|1|2|3|4][e][j][m][s]

This switch controls output from the compiler of a listing showing representation information for declared types, objects and subprograms. For -gnatR0, no information is output (equivalent to omitting the -gnatR switch). For -gnatR1 (which is the default, so -gnatR with no parameter has the same effect), size and alignment information is listed for declared array and record types.

For -gnatR2, size and alignment information is listed for all declared types and objects. The Linker_Section is also listed for any entity for which the Linker_Section is set explicitly or implicitly (the latter case occurs for objects of a type for which a Linker_Section is set).

For -gnatR3, symbolic expressions for values that are computed at run time for records are included. These symbolic expressions have a mostly obvious format with #n being used to represent the value of the n’th discriminant. See source files repinfo.ads/adb in the GNAT sources for full details on the format of -gnatR3 output.

For -gnatR4, information for relevant compiler-generated types is also listed, i.e. when they are structurally part of other declared types and objects.

If the switch is followed by an e (e.g. -gnatR2e), then extended representation information for record sub-components of records is included.

If the switch is followed by an m (e.g. -gnatRm), then subprogram conventions and parameter passing mechanisms for all the subprograms are included.

If the switch is followed by a j (e.g., -gnatRj), then the output is in the JSON data interchange format specified by the ECMA-404 standard. The semantic description of this JSON output is available in the specification of the Repinfo unit present in the compiler sources.

If the switch is followed by an s (e.g., -gnatR3s), then the output is to a file with the name file.rep where file is the name of the corresponding source file, except if j‘ is also specified, in which case the file name is file.json.

Note that it is possible for record components to have zero size. In this case, the component clause uses an obvious extension of permitted Ada syntax, for example at 0 range 0 .. -1.

-gnatS

The use of the switch -gnatS for an Ada compilation will cause the compiler to output a representation of package Standard in a form very close to standard Ada. It is not quite possible to do this entirely in standard Ada (since new numeric base types cannot be created in standard Ada), but the output is easily readable to any Ada programmer, and is useful to determine the characteristics of target dependent types in package Standard.

-gnatx

Normally the compiler generates full cross-referencing information in the ALI file. This information is used by a number of tools, including gnatfind and gnatxref. The -gnatx switch suppresses this information. This saves some space and may slightly speed up compilation, but means that these tools cannot be used.

-fgnat-encodings=[all|gdb|minimal]

This switch controls the balance between GNAT encodings and standard DWARF emitted in the debug information.

Historically, old debug formats like stabs were not powerful enough to express some Ada types (for instance, variant records or fixed-point types). To work around this, GNAT introduced proprietary encodings that embed the missing information ("GNAT encodings").

Recent versions of the DWARF debug information format are now able to correctly describe most of these Ada constructs ("standard DWARF"). As third-party tools started to use this format, GNAT has been enhanced to generate it. However, most tools (including GDB) are still relying on GNAT encodings.

To support all tools, GNAT needs to be versatile about the balance between generation of GNAT encodings and standard DWARF. This is what -fgnat-encodings is about.

• * =all: Emit all GNAT encodings, and then emit as much standard DWARF as possible so it does not conflict with GNAT encodings.
• * =gdb: Emit as much standard DWARF as possible as long as the current GDB handles it. Emit GNAT encodings for the rest.
• * =minimal: Emit as much standard DWARF as possible and emit GNAT encodings for the rest.