.. _debugging-options:

*Tutorial: Debugging with Intel® Distribution for GDB\**


Debugging Options
=================


Auto-Attach
-----------


The auto-attach feature enables listening to debug events from the GPU.


This feature allows the debugger to launch a ``gdbserver-gt`` process to
listen to GPU debug events and add the ``gdbserver-gt`` to the debugger
as an inferior. This feature is designed to improve your debugging
experience and ensure that you can debug the kernel offloaded to GPU.


The auto-attach feature is enabled by default.


The feature does not affect the debugging capability on the CPU device.
However, to eliminate the extra output the feature creates, you can turn
it off with the ``INTELGT_AUTO_ATTACH_DISABLE`` environment variable. To
do it, execute the following command on the shell before starting
``gbd-oneapi``:


.. code-block::


   export INTELGT_AUTO_ATTACH_DISABLE=1


To enable the feature again:


.. code-block::


   unset INTELGT_AUTO_ATTACH_DISABLE


Pretty-Printing
---------------


The pretty-printing feature simplifies the display of complex objects.
If a pretty-printer is registered for the type of value you are going to
print, the debugger simplifies the output. Otherwise, the debugger
prints the value normally.


Intel® Distribution for GDB\* supports pretty-printing for SYCL\* types
``id``, ``buffer``, and ``range`` from the ``cl::sycl`` namespace.


To display the list of pretty-printers available, run the following
command:


.. code-block::


   info pretty-print


Example output:


.. code-block::


   global pretty-printers:
     SYCL
       cl::sycl::buffer
       cl::sycl::id
       cl::sycl::range
     builtin
       mpx_bound128


Pretty-printing is enabled by default. For example, when you print a
value of the ``index`` variable:


.. code-block::


   print index


The output is the following:


.. code-block::


   $10 = cl::sycl::id<1> = {32}


To disable pretty-printing and display raw content instead, use the
``/r`` flag:


.. code-block::


   print /r index


Example output:


.. code-block::


   $11 = {<cl::sycl::detail::array<1>> = {common_array = {32, <No data fields>}}}


To disable all pretty-printers, use the following command:


.. code-block::


   disable pretty-printer


To enable pretty-printers:


.. code-block::


   enable pretty-printer