[[PageOutline]]

= Debugging WebKitGTK+ =

We sure of checking first the generic instructions about debugging with  [wiki:"GDB" GDB].

You need a compilation with symbols (''take it easy as it'll take some time/hours''):
{{{
#!sh
$ Tools/Scripts/build-webkit --gtk --debug
}}}

On 32-bits arch it is quite unlikely this build will succeed. If you need a build with debug symbols but still without ASSERTs enabled you can try these options:
{{{
#!sh
$ Tools/Scripts/build-webkit --gtk --disable-fast-malloc --enable-debug-symbols=full --disable-optimizations
}}}

If you want to debug the web process, the simplest way is to connect to it using gdb:
{{{
$ gdb -p <pid of WebKitWebProcess>
}}}
However that doesn't work in all cases, because the web process might already have crashed when you are trying to connect to it.

You can use the '''WEB_PROCESS_CMD_PREFIX''' environment variable (only works on Debug builds) for that purpose. If that variable is defined the web process will be run using its value as a prefix.

Example:
{{{
WEB_PROCESS_CMD_PREFIX='/usr/bin/gdbserver localhost:8080' WebKitBuild/Debug/bin/MiniBrowser
}}}
and in a different terminal:
{{{
$ cd WebKitBuild/Debug
$ gdb -q bin/WebKitWebProcess
Reading symbols from bin/WebKitWebProcess...done.
(gdb) target remote localhost:8080
(gdb) continue
}}}

If you want to debug the network process you can use '''NETWORK_PROCESS_CMD_PREFIX''' in a similar way.

Note that these variables are only enabled in debug builds. If you still want to use them in release builds you can remove the relevant
'''#ifndef NDEBUG''' in '''ProcessLauncherGtk.cpp''',
'''ProcessLauncher.h''', '''WebProcessProxyGtk.cpp''' and
'''NetworkProcessProxySoup.cpp'''


= Getting a backtrace =

This works both with release and debug builds. If you are trying to get a backtrace from the WebKitGTK+ packages shipped by your distribution, '''ensure you have the corresponding dbgsym packages installed'''.

* Open a terminal/shell, and enable coredumps
{{{
ulimit -c unlimited
}}}
* From that shell, run the browser and make it crash.
* After it has crashed a file named "core" should have appeared on your working directory.
  * If it wasn't the case ensure that you have not set the sysctl kernel.core_pattern set to another directory/pipe
{{{
$ sudo sysctl kernel.core_pattern=core
}}}
* Once you have the core, get a backtrace from it as follows:
{{{
gdb --batch -ex "thread apply all bt full" /full/path/to/WebKitWebProcess core &> backtrace.txt
}}}
  * If you get a [https://bugs.webkit.org/show_bug.cgi?id=159919 crash on the GDB demangler], you can workaround it as follows:
    * Edit (or create) the file ${HOME}/.gdbinit 
    * Write this line on it
{{{
set demangle-style none
}}}
    * And repeat the operation. You should not have got a backtrace with the files mangled.
      * You can now manually demangle those symbols by piping the output as follows
{{{
cat backtrace.txt | c++filt
}}}






== Logging support ==

Logging and other output/behaviors support is activated by default in a ''Debug'' build only.

In addition to having the logging support activated in the compilation, we need also to turn on the proper logging channels when running.

These channels are defined in the [http://trac.webkit.org/browser/trunk/Source/WebCore/platform/Logging.h Source/WebCore/platform/Logging.h] and [http://trac.webkit.org/browser/trunk/Source/WebKit2/Platform/Logging.h Source/WebKit2/Platform/Logging.h] headers in the code:

For passing the wanted channels to the running process we need to use the ''WEBKIT_DEBUG'' env variable as it is seen in the [http://trac.webkit.org/browser/trunk/Source/WebCore/platform/gtk/LoggingGtk.cpp WebCore/platform/gtk/LoggingGtk.cpp] and [http://trac.webkit.org/browser/trunk/Source/WebKit2/Platform/gtk/LoggingGtk.cpp Source/WebKit2/Platform/gtk/LoggingGtk.cpp] files in the code.
 * Notice also the ''DISABLE_NI_WARNING'' env variable referred there.

It is important to export the ''WEBKIT_DEBUG'' env variable because you will want it to affect also the ''WeProcess''.
 * This is an example for turning '''on''' the logging int he ''Network'' channel. Notice that the channels are case insensitive.
{{{
#!sh
$ export WEBKIT_DEBUG="network"
$ Tools/Scripts/run-minibrowser --gtk
}}}

It is also possible to turn '''on''' the logging and other output/behaviors support in a ''Release'' build by setting the proper C Macros. You may want to check the [http://trac.webkit.org/browser/trunk/Source/WTF/wtf/Assertions.h Source/WTF/wtf/Assertions.h] header.
 * This is a ''Release'' build example in which we want to turn on the logging support
 {{{
#!sh
$ export CPPFLAGS="-DLOG_DISABLED=0"
$ Tools/Scripts/build-webkit --gtk
}}}

=== Network analysis ===

Although ''libsoup'' should log everything we need about the network traffic in the GTK port, we may want to use other mechanisms to get that information because, for example, we don't have a build with logging support available in that moment.

Tools like [http://www.tcpdump.org/ tcpdump] or [https://www.wireshark.org/ WireShark] can be handy in this case.

This is an example of ''tcpdump'' usage to get all the headers of the HTTP traffic going to an HTTP server running in the port ''8000'' of the ''loopback'' interface:
{{{
#!sh
$ tcpdump -vvvs 1024 -l -A -i lo0 'tcp port 8000'
}}}


== Debugging multimedia stuff ==

You can use the environment variable ''GST_DEBUG'':
{{{
#!sh
$ export GST_DEBUG="webkit*:5"
}}}

To debug a multimedia test inside DRT (Dump Render Tree):
{{{
#!sh
$ Tools/Scripts/run-webkit-tests --gtk --additional-env-var=GST_DEBUG=webkit*:5 --additional-env-var=GST_DEBUG_NO_COLOR=1 http/tests/media/video-play-stall.html
}}}

== Debugging tests ==

 * In order to run tests inside the @jhbuild@ shell, these two environment variables must be set:
{{{
#!sh
$ export TEST_RUNNER_TEST_PLUGIN_PATH=$WEBKIT_HOME/WebKitBuild/Release/Libraries/.libs/
$ export TEST_RUNNER_INJECTED_BUNDLE_FILENAME=$WEBKIT_HOME/WebKitBuild/Release/Libraries/libTestRunnerInjectedBundle.la
}}}


== Debugging issues ==

 * Some times when running the WebKitTestRunner (WK2) you can see linking errors like the following one:
{{{
#!sh

(lt-WebKitWebProcess:3392): WARNING **: Error loading the injected bundle (/home/javi/devel/WebKit/webkit.git/WebKitBuild/Debug/Libraries/libTestRunnerInjectedBundle.la): /home/javi/devel/WebKit/webkit.git/WebKitBuild/Debug/Libraries/.libs/libTestRunnerInjectedBundle.so: undefined symbol: _ZTVN7leveldb10ComparatorE
}}}
   * One possible cause of such errors are missing symbols in the '''Source/autotools/symbols.filter'''. These symbols are automatically exposed in the by the '''libWebCoreInternals''' library via tags. Such library expose some symbols for testing purposes, just like the WTR application does.
   * The symbols.filter should be updated by a fresh checkout, but if that's not the case, it's possible to workaround the issue by manually adding the missing symbols to the file.

== Related ==

 * [wiki:"GDB" Tips for debugging using GDB]
 * [wiki:WebKitGTK/TrackingMemoryErrors Tracking memory errors in WebKitGTK+]
 * [wiki:/EnvironmentVariables List of WebKit environment variables]