Valgrind
========

`Valgrind <http://valgrind.org/>`_ is a programmer tool that allows to track
memory related errors in C and C++ programs.

.. hint::

   You can read a `full introduction <https://valgrind.org/docs/manual/quick-start.html#quick-start.intro>`_
   on the Valgrind website.

This page includes some tips on how to proficiently use valgrind on GTK/GNOME
programs. Feel free to add your own tricks or expand the page with more detailed
explanations.

Memcheck
--------

Memcheck is the main valgrind tool, it allows to detect memory leaks and other
memory management errors. To run a gnome program under memcheck run:

::

    valgrind \
      --leak-check=full \
      --num-callers=20 \
      --log-file=vgdump.txt\
      your-program

If the program you are debugging uses dynamically loaded modules with
``GModule`` (for instance it has a ``GModule`` based plugin system) you should
use ``G_DEBUG=resident-modules`` to make sure that the modules do not get
unloaded and valgrind can retrieve the function names when writing its log:

::

    G_DEBUG=resident-modules valgrind \
      --leak-check=full \
      --num-callers=20 \
      --log-file=vgdump.txt \
      your-program

.. note::

   If you are still using Autotools as your build system, your binary is really
   a libtool-generated temporary wrapper, the above command line will run
   valgrind on your shell which is probably not what you want. You will need to
   use ``libtool --mode=execute valgrind ...`` instead.

After running the program you can inspect the log in the vgdump file. The log
contains a list of memory related issues and in particular memory leaks. Memory
leaks are marked in three ways: definitely lost, possibly lost and still
reachable. For a start, concentrate on the definitely lost ones, which are bits
of memory leaked for sure—you can filter for them by passing
``--show-leak-kinds=definite``. For each leak valgrind provides a backtrace which
lets you pinpoint exactly where the leaks happens, in particular if your program
was compiled with debugging symbols, valgrind will tell you the exact line and
file of the leak.

Suppression files
^^^^^^^^^^^^^^^^^

GLib and other libraries often make one-off allocations that are meant to exist
until the end of the lifetime of your application. These are not leaks, but
Valgrind will mark them as such. In order to avoid cluttering your reports, you
can use "suppression files", to tell Valgrind to eliminate known one-off
allocations. GLib and GTK provide suppression files that you can use.

Assuming your copy of GLib and GTK are installed under ``/usr``, the Valgrind
suppression files are located here:

* ``/usr/share/glib-2.0/valgrind/glib.supp``
* ``/usr/share/gtk-4.0/valgrind/gtk.supp``

You can use them with the ``--suppressions`` argument for the memcheck tool, e.g.:

::

    valgrind \
      --suppressions=/usr/share/glib-2.0/valgrind/glib.supp \
      --suppressions=/usr/share/gtk-4.0/valgrind/gtk.supp \
      your-gtk-app

.. hint::

   You can use multiple ``--suppressions`` arguments, one for each suppression
   file.

If your project has its own one-off allocations you wish to suppress, you can
write your own suppression file by following the `instructions in the Valgrind
documentation <https://valgrind.org/docs/manual/manual-core.html#manual-core.suppress>`_.