Running Locally

After downloading gdbgui, you can launch it like so:

• gdbgui (or whatever the binary name is, i.e. gdbgui_0.10.0.0)
• gdbgui "./mybinary -myarg value -flag1 -flag2" (note the quotes around the arguments)
• gdbgui --args "./mybinary -myarg value -flag1 -flag2" (note the quotes around the arguments)

See more examples when launching here.

A new tab in your browser will open with gdbgui in it. If a browser tab did not open, navigate to the ip/port that gdbgui is being served on (i.e. http://localhost:5000).

Now that gdbgui is open, you can interactively run a program with it.

• Type the path to the executable in the input at the top (next to "Load Binary"). The executable should already exist and have been compiled with the -g flag.
• Click Load Binary. The program and symbols will load, but will not begin running. A breakpoint will be added to main automatically. This can be changed in settings if you prefer not to do this.
• The line of source code corresponding to main will display if the program was compiled with the -g flag debug symbols.
• Click the Run button, which is on the top right and looks like a circular arrow.
• Step through the program by clicking the Next, Step, Continue, icons as desired. These are also on the top right.

For a list of gdbgui arguments, see the Arguments section below or type gdbgui --help.

Debugging Rust Programs

gdbgui can be used to debug programs written in Rust. Assuming you use Cargo to create a new program and build it in Debug mode in the standard way:

cargo new myprog
cd myprog
cargo build

You can start debugging with a simple

gdbgui target/debug/myprog

There are a couple of small difficulties.

1.) Instead of showing your main function the initial screen will be blank and gdbgui will print File not found: main. You need to help gdbgui out by typing main into the file browser box:

and selecting the main.rs file. The source code should then appear in the browser and you can click to set breakpoints and run the program. Of course, if you want to break in some other file, you can find that in the file browser instead.

Note for macOS Users: When you load your rust binary on a mac, you may see many warnings like this

warning /Users/user/examples/rust/target/debug/deps/hello-486956f9dde465e5.9elsx31vb4it187.rcgu.o': can't open to read symbols: No such file or directory.

Symbols are names of variables, functions and types defined in your program. You can define symbols for your program by loading symbol files. gdb usually does this automatically for you, but sometimes has trouble finding the right paths.

In this case, you need to manually tell gdb where the symbol files is; it's usually the first part of the missing file. In the above example, it's hello-486956f9dde465e5.9elsx31vb4it187.rcgu.o.

You can load this into gdb with the following command (changed as appropriate):

symbol-file /Users/user/git/gdbgui/examples/rust/target/debug/deps/hello-486956f9dde465e5

2.) The GDB pretty-printing macros that Rust ships with. GDB can't find these by default, which makes it print the message

warning: Missing auto-load script at offset 0 in section .debug_gdb_scripts of file /home/phil/temp/myprog/target/debug/myprog.
Use `info auto-load python-scripts [REGEXP]' to list them.

You can safely ignore this, but the Rust issue describes the workarounds necessary (create a .gdbinit file and paste a few lines into the Python helper script).

• On Windows Rust defaults to the MSVC toolchain, and gdbgui can't debug binaries compiled that way. If you want to use gdbgui, you'll have to switch to the GNU toolchain.
• If you want to debug programs compiled in Release mode, you will need to create a profile.release section in your Cargo.toml and add debug = true to it. See the Cargo manifest for details.

and now gdb will be able to see which files were used to compile your binary, among other things.

Running gdbgui Remotely

Because gdbgui is a server, it naturally allows you to debug programs running on other computers.

• ssh into the computer with the program that needs to be debugged.
• run gdbgui -r on the remote machine (this will serve publicly so beware of security here)
• on your local machine, open your browser and access the remote machine's ip and port
• debug the remote computer in your local browser

Connecting to gdbserver

Like gdb, gdbserver is also made by gnu, but with the following important differences:

• it is much smaller than gdb
• it is easier to port to other architectures than all of gdb

gdbserver runs on a remote machine or embedded target, which, as the name suggests, runs a server. gdb communicates with gdbserver so you can debug on your local machine. To do this, the remote machine must run the server and program:

gdbserver 0.0.0.0:9000 mybinary.a

Then you can launch gdb or gdbgui and connect to it. In gdbgui, use the dropdown to select Connect to gdbserver, and enter

<remote ip address>:9000

Read more at the gdbserver homepage.

Settings

gdbgui settings can be accessed by clicking the gear icon in the top right of the frontend. Most of these settings persist between sessions for a given url and port.

Keyboard Shortcuts

The following keyboard shortcuts are available when the focus is not in an input field. They have the same effect as when the button is pressed.

• Run: r
• Continue: c
• Next: n or right arrow
• Step: s or down arrow
• Up: u or up arrow
• Next Instruction: m
• Step Instruction: ,

Debugging Faults

If your program exits unexpectedly from something like a SEGFAULT, gdbgui displays a button in the console to re-enter the state the program was in when it exited. This allows you to inspect the stack, the line on which the program exited, memory, variables, registers, etc.

Command line API

This is the output of the commandgdbgui -horgdbgui --help

usage: gdbgui [-h] [-g GDB] [--gdb-args GDB_ARGS] [--rr] [-p PORT]
              [--host HOST] [-r] [--auth-file AUTH_FILE] [--user USER]
              [--password PASSWORD] [--key KEY] [--cert CERT]
              [--remap-sources REMAP_SOURCES] [--project PROJECT] [-v]
              [--hide-gdbgui-upgrades] [-n] [-b BROWSER] [--license LICENSE]
              [--debug] [--args ...]
              [cmd]

A server that provides a graphical user interface to the gnu debugger (gdb).
https://github.com/cs01/gdbgui

positional arguments:
  cmd                   The executable file and any arguments to pass to it.
                        To pass flags to the binary, wrap in quotes, or use
                        --args instead. Example: gdbgui ./mybinary [other-
                        gdbgui-args...] Example: gdbgui './mybinary myarg
                        -flag1 -flag2' [other gdbgui args...]

optional arguments:
  -h, --help            show this help message and exit
  --args ...            Specify the executable file and any arguments to pass
                        to it. All arguments are taken literally, so if used,
                        this must be the last argument passed to gdbgui.
                        Example: gdbgui [...] --args ./mybinary myarg -flag1
                        -flag2

gdb settings:
  -g GDB, --gdb GDB     Path to debugger. Default: gdb
  --gdb-args GDB_ARGS   Arguments passed directly to gdb when gdb is invoked.
                        For example,--gdb-args="--nx --tty=/dev/ttys002"
  --rr                  Use `rr replay` instead of gdb. Replays last recording
                        by default. Replay arbitrary recording by passing
                        recorded directory as an argument. i.e. gdbgui
                        /recorded/dir --rr. See http://rr-project.org/.

gdbgui network settings:
  -p PORT, --port PORT  The port on which gdbgui will be hosted. Default: 5000
  --host HOST           The host ip address on which gdbgui serve. Default:
                        127.0.0.1
  -r, --remote          Shortcut to set host to 0.0.0.0 and suppress browser
                        from opening. This allows remote access to gdbgui and
                        is useful when running on a remote machine that you
                        want to view/debug from your local browser, or let
                        someone else debug your application remotely.

security settings:
  --auth-file AUTH_FILE
                        Require authentication before accessing gdbgui in the
                        browser. Specify a file that contains the HTTP Basic
                        auth username and password separate by newline.
  --user USER           Username when authenticating
  --password PASSWORD   Password when authenticating
  --key KEY             SSL private key. Generate with:openssl req -newkey
                        rsa:2048 -nodes -keyout host.key -x509 -days 365 -out
                        host.cert
  --cert CERT           SSL certificate. Generate with:openssl req -newkey
                        rsa:2048 -nodes -keyout host.key -x509 -days 365 -out
                        host.cert

other settings:
  --remap-sources REMAP_SOURCES, -m REMAP_SOURCES
                        Replace compile-time source paths to local source
                        paths. Pass valid JSON key/value pairs.i.e. --remap-
                        sources='{"/buildmachine": "/home/chad"}'
  --project PROJECT     Set the project directory. When viewing the "folders"
                        pane, paths are shown relative to this directory.
  -v, --version         Print version
  --hide-gdbgui-upgrades
                        Hide messages regarding newer version of gdbgui.
                        Default: False.
  -n, --no-browser      By default, the browser will open with gdbgui. Pass
                        this flag so the browser does not open.
  -b BROWSER, --browser BROWSER
                        Use the given browser executable instead of the system
                        default.
  --license LICENSE     Store gdbgui ad-free license key.
  --debug               The debug flag of this Flask application. Pass this
                        flag when debugging gdbgui itself to automatically
                        reload the server when changes are detected