Running a separate instance

Since GNOME Terminal has a client/server architecture, in order to debug the terminal you will most likely need to run a separate instance of it. In the commands below, replace the exact paths with the real ones if you have installed gnome-terminal under a different prefix.

1. For versions up to 3.6

$ gdb --args /usr/bin/gnome-terminal --disable-factory
(gdb) run

2. For versions 3.7 and higher

First create a separate instance of the server:

$ gdb --args /usr/libexec/gnome-terminal-server --app-id my.foo.Terminal
(gdb) run

Now you have 10 seconds to use the client to create a terminal inside this new server:

$ gnome-terminal --app-id my.foo.Terminal

Valgrind

You can also use valgrind instead of gdb --args in the commands above. Note that since this makes startup slower, you may need to delay the client part of the commands, or repeat them until they succeed.

Special environment variables

1. Extra debug messages

For extra debug messages, you need to compile gnome-terminal with the --enable-debug flag to configure, then run the new server instance with the GNOME_TERMINAL_DEBUG environment variable set. Use GNOME_TERMINAL_DEBUG=help to get a list of all possible values.

You can enable even more debug messages by compiling vte with -Ddebugg=true (not a typo!) and setting the VTE_DEBUG environment variable, which works the same way as GNOME_TERMINAL_DEBUG.

To print out all possible debug messages, use GNOME_TERMINAL_DEBUG=all and/or VTE_DEBUG=all.

2. Debugging a D-Bus error

When the gnome-terminal server process crashes due to a D-Bus error (for example "The connection is closed"), you need to reproduce the bug while getting gdbus debug output. Set the environment variable G_DBUS_DEBUG=all when running the gnome-terminal server as detailed above.

3. Debugging an X error

When the gnome-terminal server process crashes with an X error ("The program '...' received an X Window System Error."), then you need to follow the instructions given in the full error message, ie. set the environment variable GDK_SYNCHRONIZE=1 when running the gnome-terminal server as detailed above, and break on gdk_x_error in gdb.

4. Exclude ubuntu modules

If you're running on ubuntu, you must make sure the bug isn't due to the ubuntu gtk modules. To do so, set these environment variables when running the gnome-terminal server process as detailed above: LIBOVERLAY_SCROLLBAR=0 UBUNTU_MENUPROXY=0 NO_UNITY_GTK_MODULE=1

Note that this only applies if you're running the ubuntu packaged version of gnome-terminal, or a version prior to 3.8.0; if you compiled gnome-terminal yourself from either tarball or from GIT after version 3.8.0, this is done automatically.