/*
 * This file is part of the StarPU Handbook.
 * Copyright (C) 2009--2011  Universit@'e de Bordeaux
 * Copyright (C) 2010, 2011, 2012, 2013, 2014  CNRS
 * Copyright (C) 2011, 2012 INRIA
 * See the file version.doxy for copying conditions.
 */

/*! \page DebuggingTools Debugging Tools

StarPU provides several tools to help debugging applications. Execution traces
can be generated and displayed graphically, see \ref
GeneratingTracesWithFxT.

Some gdb helpers are also provided to show the whole StarPU state:

\verbatim
(gdb) source tools/gdbinit
(gdb) help starpu
\endverbatim

For instance, one can print all tasks with <c>starpu-print-all-tasks</c>,
print all datas with <c>starpu-print-datas</c>, print all pending data
transfers with <c>starpu-print-prequests</c>, <c>starpu-print-requests</c>, <c>starpu-print-frequests</c>, <c>starpu-print-irequests</c>,
print pending MPI requests with
<c>starpu-mpi-print-detached-requests</c>

Some functions can only work if --enable-debug was passed to ./configure
(because they impact performance)

Valgrind can be used on StarPU: valgrind.h just needs to be found at ./configure
time, to tell valgrind about some known false positives and disable host memory
pinning. Other known false positives can be suppressed by giving the suppression
files in tools/valgrind/ *.suppr to valgrind's --suppressions option.

The environment variable \ref STARPU_DISABLE_KERNELS can also be set to 1 to make
StarPU do everything (schedule tasks, transfer memory, etc.) except actually
calling the application-provided kernel functions, i.e. the computation will not
happen. This permits to quickly check that the task scheme is working properly.

The Temanejo task debugger can also be used, see \ref UsingTheTemanejoTaskDebugger.

\section UsingTheTemanejoTaskDebugger Using The Temanejo Task Debugger

StarPU can connect to Temanejo >= 1.0rc2 (see
http://www.hlrs.de/temanejo), to permit
nice visual task debugging. To do so, build Temanejo's <c>libayudame.so</c>,
install <c>Ayudame.h</c> to e.g. <c>/usr/local/include</c>, apply the
<c>tools/patch-ayudame</c> to it to fix C build, re-<c>./configure</c>, make
sure that it found it, rebuild StarPU.  Run the Temanejo GUI, give it the path
to your application, any options you want to pass it, the path to <c>libayudame.so</c>.

It permits to visualize the task graph, add breakpoints, continue execution
task-by-task, and run gdb on a given task, etc.

\image html temanejo.png
\image latex temanejo.png "" width=\textwidth

Make sure to specify at least the same number of CPUs in the dialog box as your
machine has, otherwise an error will happen during execution. Future versions
of Temanejo should be able to tell StarPU the number of CPUs to use.

Tag numbers have to be below <c>4000000000000000000ULL</c> to be usable for
Temanejo (so as to distinguish them from tasks).



*/