README.md

   1 gdbpimp - a console gui for gdb
   2 ===============================
   3
   4 ![screenshot](https://user-images.githubusercontent.com/341425/111042524-ae757b00-8435-11eb-9dcf-c09fea159ed1.png)
   5
   6 unlike the other gdb guis, like gdbgui, pwndbg, peda, etc this
   7 one works with a plain gdb binary, regardless of whether
   8 built with or without shared libs and python scripting support.
   9 and regardless of version. the ones mentioned here tend to only
  10 work properly with the latest and greatest gdb, while this here
  11 was tested with gdb 7.6 and should work with older and newer
  12 versions as well, because it works on stdin/stdout of gdb.
  13
  14 additionally it doesn't have a shitload of library dependencies.
  15 you only need `prompt-toolkit` and `pygments`.
  16
  17 you also dont need to install a .gdbinit file which overrides
  18 normal functioning of gdb.
  19
  20 whereas pwndbg, peda, gef and gdb-dashboard focus on assembly
  21 level debugging, this one is focused on source-level C debugging.
  22
  23 usage:
  24 ------
  25
  26     python2 gdb.py /bin/program arg1 arg2
  27
  28 keyboard shortcuts:
  29 -------------------
  30
  31 - F7     - step into (s)
  32 - F8     - step over (n)
  33 - CTRL-B - set breakpoint at current line in codeview
  34 - TAB    - circle focus
  35
  36 - CTRL-Q - quit
  37 - F1     - switch input applet mode to python or gdb repl
  38 - F2     - toggle mouse support on or off.
  39
  40 these last ones are likely to change in future versions.
  41
  42 other functionality
  43 -------------------
  44
  45 *gdb prompt:*
  46 you can enter arbitrary gdb command in the gdb prompt in the bottom line.
  47
  48 *python prompt:*
  49 you can toggle the gdb prompt to a python repl prompt with `F1`. This allows
  50 to execute code in the context of gdbpimp, can be useful for debugging.
  51
  52 *expression sidebar:*
  53 you can add expressions to the `expr` sidebar, e.g. the value of a struct
  54 member, some memory region etc.
  55 to add an expression, write `:expr add name expression` in the gdb prompt.
  56 expression can be any expression understood by gdb that returns a string,
  57 for instance `p/x mystruct.member`.
  58 The expression will be evaluated on every step in the program and the actual
  59 contents displayed.
  60 an expression can be removed via `:expr del name`.
  61 expressions are saved to a file if not removed and loaded next time you
  62 debug the same binary.
  63
  64 Dependencies
  65 ------------
  66
  67 This app was written for and with python2. I don't plan on porting it
  68 to python 3. I will however accept a PR that can make it work on both
  69 py2 and py3, if it's reasonably clean.
  70
  71 required python libs are `prompt-toolkit` 2.x; it was developed with 2.0.6
  72 but should work with 2.0.10 (last py2 compatible release) too.
  73 prompt-toolkit itself depends on `pygments` and `wcwidth` packages, tested are
  74 version 2.2.0 and 0.1.7, respectively.
  75
  76 TODO
  77 ----
  78 - source file selection dialog
  79 - dialog showing backtrace with possibility to select a frame
  80 - keyboard shortcuts for: runtocursor, stepout
  81   ( see https://www.shortcuts-keyboard.com/visual-basic-6-0-default-shortcut-keys/ )
  82   stepout functionality might require an additional dependency on `pycparser`.
  83 - nicer way to highlight the actual line in the codeview
  84   (optimally red bar over the entire line)
  85 - ability to customize size of controls