.. _Debugging_Information:

*********************
Debugging Information
*********************

.. index:: Debugging information
.. index:: Debug_Image query

There are two kinds of the debugging information available in ASIS-for-GNAT
--- debug images returned by the ASIS query ``Debug_Image``
(for ``Context``\ s,
``Compilation_Unit``\ s and ``Element``\ s); and debug output generated by
ASIS queries when the corresponding implementation debug flag is set ON during
ASIS initialization (see :ref:`Parameters_of_Asis.Implementation.Initialize`).

.. _Interpreting_Debug_Images:

Interpreting Debug Images
=========================

.. index:: 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
        ``Element``\ s also.

.. _ASIS_Debug_Flags:

ASIS Debug Flags
================

.. index:: Debug flags

ASIS provides several internal debug flags, which are described in
:file:`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.

  .. index:: Tree swapping profile
