Documentation > Linux > Debugging Graphical Linux Applications (X11)

Debugging Graphical Linux Applications (X11)

If you use VisualGDB to debug graphical Linux applications (X11), you can configure it to display the GUI on the Linux machine, the Windows machine, or completely suppress it. You can change this behavior via VisualGDB Project Properties -> Debug Settings -> Program Output:

The rest of this page explains how X11 forwarding works and how to troubleshoot various issues that could arise with it.

X11 Forwarding Basics

Whenever you start an X11-based graphical application (in the terminal or via SSH), it uses the steps below to display the actual GUI:

  1. Checks the DISPLAY environment variable that should contain the location of the X11 server.
  2. Translates it to the full form (e.g. “:0” corresponds to localhost:6000, “1” – to localhost:6001, etc).
  3. Connects to that TCP port and authenticates with the X11 server
  4. Sends requests to the server to display the actual GUI

Changing the X11 forwarding mode in VisualGDB properties simply controls the value of the DISPLAY variable passed to the program.

Displaying the GUI on the Windows side

If you choose to display the X11 GUI on the Windows side (default setting), VisualGDB won’t change the DISPLAY variable and instead, it will ask the SSH server to perform SSH forwarding:

  1. The SSH server on the Linux side will open a new TCP port for incoming X11 connections, and will set the DISPLAY variable for the SSH clients to point to it.
  2. Whenever a program running in an SSH session connects to that port, the SSH server forward the connection to the SSH client (part of VisualGDB).
  3. VisualGDB will then launch vcxsrv or XMing (Windows port of the X11 server) and will relay the requests to it.
  4. The X11 server running on the Windows machine will create the X11 windows showing the content requested by the program.

If this mode is not working, check the SSH server configuration. The X11Forwarding parameter needs to be turned on in sshd_config. You can also try viewing the DISPLAY variable from any SSH client. It should be automatically set by the X11 server to something different than the default value of “:0“:

Displaying the GUI on the Linux side

When you configure VisualGDB to display the GUI on the Linux side, it will simply set the DISPLAY variable to “:0”, overriding the value provided by the X11 server. In order for this to work, 2 assumptions should hold:

  • The X server running on the Linux machine should be using the default port 6000 (DISPLAY=:0)
  • The debugged program should use the same SSH user that is currently logged on to the normal X server

You can test out this mechanism by viewing the value of DISPLAY directly on the target computer, and then setting it manually in an SSH session before running a graphical application:

If the DISPLAY value used by the normal X server is not :0, you can configure VisualGDB to use it by adding it to VisualGDB Project Properties -> Debug Settings -> Common Settings -> Debugger Environment:Make sure you revert the normal X11 mode setting in VisualGDB Project Properties to the default value (forward to Windows machine).

If the target uses the DISPLAY value of :0, but setting it via SSH doesn’t work, double-check that the X authorization is configured correctly. You can find more information about it on this page.