3.10.1.2 Debugging - A Special Case ¶

A common use of conditional code is to execute statements (for example dynamic checks, or output of intermediate results) under control of a debug switch, so that the debugging behavior can be turned on and off. You can do this by using a Boolean constant to control whether the debug code is active:

if Debugging then
   Put_Line ("got to the first stage!");
end if;

or

if Debugging and then Temperature > 999.0 then
   raise Temperature_Crazy;
end if;

Since this is a common case, GNAT provides special features to deal with this in a convenient manner. For the case of tests, Ada 2005 has added a pragma Assert that you can use for such tests. This pragma is modeled on the Assert pragma that has always been available in GNAT, so you can use this feature with GNAT even if you are not using Ada 2005 features. The use of pragma Assert is described in the GNAT_Reference_Manual, but as an example, the last test could be written:

pragma Assert (Temperature <= 999.0, "Temperature Crazy");

or simply

pragma Assert (Temperature <= 999.0);

In both cases, if assertions are active and the temperature is excessive, the exception Assert_Failure is raised with the exception message using the specified string in the first case or a string indicating the location of the pragma in the second case.

You can turn assertions on and off by using the Assertion_Policy pragma.

This is an Ada 2005 pragma that is implemented in all modes by GNAT. Alternatively, you can use the -gnata switch to enable assertions from the command line, which also applies to all versions of Ada.

For the example above with the Put_Line, the GNAT-specific pragma Debug can be used:

pragma Debug (Put_Line ("got to the first stage!"));

If debug pragmas are enabled, the argument, which must be of the form of a procedure call, is executed (in this case, Put_Line is called). You can specify only one call, but you can of course include a special debugging procedure containing any code you like in the program and call it in a pragma Debug argument as needed.

One advantage of pragma Debug over the if Debugging then construct is that pragma Debug can appear in declarative contexts, such as at the very beginning of a procedure, before local declarations have been elaborated.

You can enable debug pragmas using either the -gnata switch that also controls assertions, or with a separate Debug_Policy pragma.

The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used in Ada 95 and Ada 83 programs as well) and is analogous to pragma Assertion_Policy to control assertions.

Assertion_Policy and Debug_Policy are configuration pragmas, and thus can appear in gnat.adc if you are not using a project file or in the file designated to contain configuration pragmas in a project file. They then apply to all subsequent compilations. In practice the use of the -gnata switch is often the most convenient method of controlling the status of these pragmas.

Note that a pragma is not a statement, so in contexts where a statement sequence is required, you can’t just write a pragma on its own. You have to add a null statement.

if ... then
   ... -- some statements
else
   pragma Assert (Num_Cases < 10);
   null;
end if;