{"id":13559645,"url":"https://github.com/ftilde/ugdb","last_synced_at":"2025-04-03T15:30:47.996Z","repository":{"id":34410089,"uuid":"177319901","full_name":"ftilde/ugdb","owner":"ftilde","description":"An alternative TUI for gdb","archived":false,"fork":false,"pushed_at":"2025-03-09T11:00:15.000Z","size":1255,"stargazers_count":380,"open_issues_count":8,"forks_count":8,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-09T12:17:49.435Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ftilde.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-03-23T17:33:01.000Z","updated_at":"2025-03-09T11:00:18.000Z","dependencies_parsed_at":"2024-01-14T02:42:37.771Z","dependency_job_id":"6dbfd76b-ce28-4eb7-9762-7766c31007e5","html_url":"https://github.com/ftilde/ugdb","commit_stats":{"total_commits":407,"total_committers":7,"mean_commits":"58.142857142857146","dds":"0.16707616707616713","last_synced_commit":"a8e063fb9d1c37ab49c460ce991bf6457eb942f5"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ftilde%2Fugdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ftilde%2Fugdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ftilde%2Fugdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ftilde%2Fugdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ftilde","download_url":"https://codeload.github.com/ftilde/ugdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247027700,"owners_count":20871574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T13:00:30.403Z","updated_at":"2025-04-03T15:30:47.988Z","avatar_url":"https://github.com/ftilde.png","language":"Rust","readme":"# ugdb\n\nugdb is an [unsegen](https://github.com/ftilde/unsegen) based alternative TUI for [gdb](https://www.gnu.org/software/gdb/).\n\n## Screenshots\n![](screenshot.png)\n\nWhat's that? Oh, yes. Yes, you can totally use `ugdb` to debug `ugdb` debugging `ugdb`.\n\n![](ugdbception.png)\n\n## Building\n\nugdb is written in Rust and needs a working installation of cargo to build.\n\n```\n$ git clone https://github.com/ftilde/ugdb\n$ cd ugdb\n$ cargo build --release\n$ target/release/ugdb\n```\n\n## Installation\n\nIf you're an Arch Linux user, then you can install `ugdb` from the [arch user repository](https://aur.archlinux.org/packages/ugdb/):\n```\nyay -S ugdb\n```\n\n`ugdb` can also be installed from [crates.io](https://crates.io/crates/ugdb) using [cargo](https://github.com/rust-lang/cargo/):\n```\ncargo install ugdb\n```\n\n## Usage\n\nThe command line interface is aimed to be *mostly* compatible with gdb:\n```\n$ ugdb --help\nugdb 0.1.12\nftilde \u003cftilde@REDACTED\u003e\nAn alternative TUI for gdb\n\nUSAGE:\n    ugdb [FLAGS] [OPTIONS] [--] [program]...\n\nFLAGS:\n    -h, --help       Prints help information\n        --nh         Do not execute commands from ~/.gdbinit.\n    -n, --nx         Do not execute commands from any .gdbinit initialization files.\n    -q, --quiet      \"Quiet\".  Do not print the introductory and copyright messages.  These messages are also suppressed\n                     in batch mode.\n        --rr         Start ugdb as an interface for rr. Trailing ugdb arguments will be passed to rr replay instead.\n    -V, --version    Prints version information\n\nOPTIONS:\n    -b \u003cbps\u003e\n            Set the line speed (baud rate or bits per second) of any serial interface used by GDB for remote debugging.\n\n        --cd \u003ccd\u003e\n            Run GDB using directory as its working directory, instead of the current directory.\n\n    -x, --command \u003ccommand_file\u003e                                      Execute GDB commands from file.\n    -c, --core \u003ccore_file\u003e                                            Use file file as a core dump to examine.\n        --gdb \u003cgdb_path\u003e                                              Path to alternative gdb binary. [default: gdb]\n    -e, --initial-expression \u003cinitial_expression_table_entries\u003e...    Define initial entries for the expression table.\n        --layout \u003clayout\u003e\n            Define the initial tui layout via a format string. [default: (1s-1c)|(1e-1t)]\n\n        --log_dir \u003clog_dir\u003e\n            Directory in which the log file will be stored. [default: /tmp]\n\n    -p, --pid \u003cproc_id\u003e                                               Attach to process with given id.\n        --rr-path \u003crr_path\u003e                                           Path to alternative rr binary. [default: rr]\n    -d, --directory \u003csource_dir\u003e\n            Add directory to the path to search for source files.\n\n    -s, --symbols \u003csymbol_file\u003e                                       Read symbols from the given file.\n\nARGS:\n    \u003cprogram\u003e...    Path to program to debug (with arguments).\n```\n\nSome notable differences:\n\n* Command line arguments to the program to be debugged can be specified without the `-a`-flag of gdb. (But don't forget `--`!)\n* You can specify an alternative gdb via the `--gdb` argument. Go debug your Rust: `$ ugdb --gdb=rust-gdb`! By default, `gdb` in `$PATH` will be used.\n* An alternative log file directory can be specified using `--log_dir` argument. By default, log files are created in `/tmp/`.\n* Some flags might be missing either because they make no sense (e.g., `--tui`) or because I forgot to add them. In the latter case feel free to open an issue.\n\n\n## User interface\nThe interface consists of 4 containers between which the user can switch with vim-like controls:\nTo enter selection mode, press `ESC` (indicated by orange separators).\nYou can then navigate between containers using arrow keys or hjkl.\nPress `Enter` to enter *insert*-mode and interact with the selected container.\nAlternatively press the shortcut key for the specific container to directly enter it (see below) from selection mode.\n\n### GDB console\n\nInteract using the standard gdb interface. Enter by pressing `i`.\n\n* `PageUp`/`PageDown` scroll the output of the console.\n* `Ctrl-b`/`Ctrl-e` jump to the beginning/end of the buffer.\n* Use arrow keys/Backspace/`Home`/`End` to move the cursor.\n* Characters are inserted at the cursor position.\n* Use `Tab`/`Ctrl-n`/`Ctrl-p` for identifier and gdb command completion.\n* Use `Ctrl-r` to initiate history search and `Ctrl-c`/left/right to accept and continue editing.\n\n### Pager\n\nView and browse source code or assembly around the current program location. Enter by pressing `s`.\n\n* Scroll up/down using arrow keys or jk and jump using `Home`/`End`.\n* Navigate the stack using `PageUp`/`PageDown`.\n* Use `Space` to toggle breakpoints at the current location in the pager.\n* Toggle between source, assembly, and side-by-side mode using `d` (if available).\n\n### Expression table\n\nView and watch the (structured) results of gdb expressions (everything you can put after `p` in the console).\nChanges between steps are highlighted.\nEnter by pressing `e`.\n\n* Enter an expression in the left column\n* Press `Enter` to advance to the next row to enter another expression.\n* Navigate using arrow keys.\n* Use `Space` in the right column to interact with the structure viewer.\n* Use `Tab`/`Ctrl-n`/`Ctrl-p` for identifier completion.\n* Use `Ctrl-f` to cycle through original/hex/decimal/octal/binary format for integers.\n* Use `Ctrl-w` to (try to) set an access watchpoint for the current expression.\n\nNote: The viewer is somewhat broken for displaying structures with custom pretty-printers.\nA workaround would be to use [variable objects](https://sourceware.org/gdb/onlinedocs/gdb/GDB_002fMI-Variable-Objects.html), but that would not allow for evaluation of arbitrary expressions.\n\n### Terminal\n\nThe tty of the program to be debugged is automatically redirected to this virtual terminal.\nEnter by pressing `t`, or press `T` for *locked mode*.\nLocked mode can only be exited by pressing `Esc` twice in rapid succession.\nAll other input is directly sent to the virtual terminal.\nHowever, for most application the regular insert mode is sufficient and can be left by a single press of `Esc`.\n\n* Scroll up/down using `PageUp`/`PageDown`.\n* `Home`/`End` directly jump to the beginning/end of the output.\n\nThe virtual terminal does not yet properly implement all ansi functions, but it quite usable for a number of terminal applications.\n\n## IPC Interface\n\n`ugdb` can be controlled remotely via a unix domain socket-based IPC interface.\nThe interface is documented [here](https://github.com/ftilde/ugdb/blob/master/IPC.md).\nIn practice this means that you can install [vim-ugdb](https://github.com/ftilde/vim-ugdb) and set breakpoints in ugdb from vim using the `UGDBBreakpoint` command.\n\n## Builtin commands\n\nThese commands all start with a leading `!` and can be entered instead of regular gdb commands into the gdb console.\n\n### `!reload`\n\nRead the current executable from disk.\nYou should run this, for example, when you have recompiled the binary that you are debugging and want to reuse an existing ugdb session.\n\n### `!show \u003cfile\u003e`\n\nShow the specified file in the pager.\nThis may be useful if you interactively want to set breakpoints, but can't or don't want to use the IPC call from your editor (see [vim-ugdb](https://github.com/ftilde/vim-ugdb)).\n\n### `!layout \u003clayout_string\u003e`\n\nChange ugdb's tui layout at runtime.\nThe layout string represents a tree with single letters as leafs representing the different panes of ugdb (`c` for the GDB console, `s` for the pager, `e` for the expression table, and `t` for the terminal).\nNodes can be arranged in horizontal (e.g., `c|s|e`) or vertical (e.g., `c-s-e`) layouts using the separators `|` and `-`.\nBrackets can be used to nest horizontal and vertical layouts (e.g., `(c|s)-e`).\nFinally, integers preceding a node optionally define a weight (other than the default weight of 1) that will be used when assigning screen space to the node.\nFor example, `1c|3s` will create arrange the console and pager horizontally while assigning roughly 25% of the space to the console and 75% to the pager.\nThe default layout of ugdb is `(1s-1c)|(1e-1t)`.\nAn initial layout can also be specified using the command line parameter `--layout`.\n\n## FAQ\n\n### I get the error message \"Cannot *something* because gdb is busy\"\n\nBecause we communicate with gdb in synchronous mode, some tasks that require cooperation of gdb (such as setting breakpoints and disassembling source files) cannot be done when gdb is busy, i.e., when the currently debugged program is running.\nIn this case you have to interrupt execution by pressing Ctrl-C in the console first.\nIt may be possible to lift this limitation in the future using the [non-stop-mode](https://sourceware.org/gdb/current/onlinedocs/gdb/Asynchronous-and-non_002dstop-modes.html#Asynchronous-and-non_002dstop-modes), but there are no immediate plans for implementation.\n\n## Some notes on the status\n\nThis project mostly scratches my own itch -- successfully. I use it as my primary debugger. In that sense I consider this project as \"done\", but additional sub-itches may be sub-scratched in the future.\n\n## Licensing\n\n`ugdb` is released under the MIT license.\n","funding_links":[],"categories":["Rust","Dev-Utilities"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fftilde%2Fugdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fftilde%2Fugdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fftilde%2Fugdb/lists"}