5. Debugging Information

There are two kinds of the debugging information available in ASIS-for-GNAT — debug images returned by the ASIS query Debug_Image (for Contexts, Compilation_Units and Elements); and debug output generated by ASIS queries when the corresponding implementation debug flag is set ON during ASIS initialization (see Parameters of Asis.Implementation.Initialize).

5.1. Interpreting Debug Images

It is straightforward to interpret the debug images generated for the main ASIS abstractions, because most of the information directly corresponds to ASIS concepts. The following details of debug images are implementation specific.

  • Context

    • Context Id

      This is the internal Context Id used in the implementation data structures. This Id is assigned to a Context when it is associated for the first time, and it remains unchanged and unique until ASIS is finalized.

    • All tree files

      The number of tree files making up the given Context.

  • Compilation_Unit

    • Compilation_Unit Id

      This is the internal Compilation_Unit Id used in the implementation data structures. This Id remains unchanged and unique until the unit’s enclosed Context is closed.

    • Is consistent

      True if the same version of the unit’s source was used for all the tree files making up the enclosed unit’s context, and False otherwise

  • Element

    • Node, R_Node, Node_Field_1

      Tree nodes on which the internal representation of a given Element is based. They are meaningful only in the tree file indicated in the Enclosing_Tree field of the debug image

    • Special Case

      Implementation-specific indication of the cases when the Element needs some special processing.

    • Obtained from the tree

      The Id and the name of the tree file from which the tree-specific fields of the internal representation of given Element were obtained

    • Rel_Sloc

      Indicates the (relative) position of the source text of the Element, counting from the beginning of the source of its enclosing compilation unit. Applies to implicit Elements also.

5.2. ASIS Debug Flags

ASIS provides several internal debug flags, which are described in a_debug.adb. When one or more of these flags is set, useful internal debugging information is directed to Standard_Output. Although this information is not always user-oriented, you may find the following debug flags helpful when you are developing an ASIS application:

-dc
Outputs the content of the internal data structures for a Context, when the Context is closed and dissociated. By analyzing this information, you may map other debug information onto unit and tree Ids.
-di
Turns off including the location of an Element into the result generated by Debug_Image. This may be useful if an ASIS program crashes because of some problem with ASIS structural queries (structural queries are used by Element‘s Debug_Image query to compute the source location of the argument).
-do
When the Context is opened, lists the tree files being processed, and the ones selected to represent a given Context
-dt
Outputs a message whenever a tree file is read in. This information may be useful for analyzing and reducing the tree swapping profile of your application.