{"id":27000483,"url":"https://github.com/jvalcher/termfu","last_synced_at":"2025-04-04T03:27:12.070Z","repository":{"id":193299772,"uuid":"688516324","full_name":"jvalcher/termfu","owner":"jvalcher","description":"Multi-language TUI debugger with custom layouts","archived":false,"fork":false,"pushed_at":"2025-03-26T13:44:03.000Z","size":8560,"stargazers_count":87,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-26T14:44:11.413Z","etag":null,"topics":["bash","debugger","debugger-frontend","debugging","gdb","gnu","gnu-linux","linux","multilanguage-support","pdb","terminal","terminal-based","tui"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jvalcher.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-07T14:03:55.000Z","updated_at":"2025-03-26T13:44:07.000Z","dependencies_parsed_at":"2024-02-07T23:29:47.929Z","dependency_job_id":"68d1a45a-d5f7-4d60-9bfa-d5b828b3906e","html_url":"https://github.com/jvalcher/termfu","commit_stats":null,"previous_names":["jvalcher/gdb-tuiffic","jvalcher/termide","jvalcher/term_debug","jvalcher/terminal_debugger","jvalcher/termvu","jvalcher/termfu"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvalcher%2Ftermfu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvalcher%2Ftermfu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvalcher%2Ftermfu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jvalcher%2Ftermfu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jvalcher","download_url":"https://codeload.github.com/jvalcher/termfu/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247116290,"owners_count":20886291,"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":["bash","debugger","debugger-frontend","debugging","gdb","gnu","gnu-linux","linux","multilanguage-support","pdb","terminal","terminal-based","tui"],"created_at":"2025-04-04T03:27:11.585Z","updated_at":"2025-04-04T03:27:12.064Z","avatar_url":"https://github.com/jvalcher.png","language":"C","funding_links":[],"categories":["\u003ca name=\"programming\"\u003e\u003c/a\u003eProgramming"],"sub_categories":[],"readme":"\n\u003ch1 align=\"center\"\u003etermfu\u003c/h1\u003e\n\nA multi-language debugger frontend for the Linux terminal\n\n- ___Fast___\n- Easy to configure\n- Key bindings documented on-screen\n- Switch between custom layouts while debugging\n- Scrollable window data\n- Breakpoint, watchpoint persistence\n- Debugger prompt access\n\n\u003cbr\u003e\n\u003cp align=\"center\"\u003e\u003cimg margin-left=\"auto\" src=\"./misc/layout1.png\"\u003e\u003c/p\u003e\n\u003cbr\u003e\n\n\n## Support\n\n| Debugger   | Languages |\n|   :----:   | -----     |\n| [GDB](https://sourceware.org/gdb/) | C, C++, D, Go, Objective-C, Fortran, OpenCL C, Pascal, Rust, assembly, Modula-2, Ada |\n| [PDB](https://docs.python.org/3/library/pdb.html) | Python |\n\u003cbr\u003e\n\n## Installation\n\n### Dependencies\n\n```\nsudo apt-get install make gcc libncurses-dev gdb python3\n ```\n\n### Build and install\n```\nmake\nsudo make install\n```\n\u003cbr\u003e\n\n\n## Usage\n\n- The program can be run as follows in the same directory as a `.termfu` configuration file.\n- Breakpoint and watchpoint data will be stored in `.termfu_data`.\n```bash\ntermfu\n```\n\n### Flags\n- `-h` prints usage instructions.\n- `-c` sets the configuration file path.\n- `-p` sets the data persistence file path.\n```bash\ntermfu -c .termfu_01 -p .termfu_01_data\n```\n\n### Basics\n- Switch between layouts with your `(l)ayouts` key.\n- Scroll window data by selecting the window via its key binding and then using the arrow, page up, etc. keys. You can also use the `hjkl` keys.\n\u003cbr\u003e\u003cbr\u003e\n\n## Configuration\n\n### Example `.termfu` configuration\n\n\n```\n\n[ command ]\n\ngdb --interpreter=mi a.out\n\n[ plugins ]\n\n# header commands\nAtP : A : (A)ttach\nCon : c : (c)ontinue\nFin : f : (f)inish\nKil : k : (k)ill\nLay : l : (l)ayouts\nNxt : n : (n)ext\nPrm : m : pro(m)pt\nQut : q : (q)uit\nRun : r : (r)un\nStp : s : (s)tep\nUnt : u : (u)ntil\n\n# windows\nAsm : a : (a)ssembly\nBrk : b : (b)reakpoints\nDbg : d : (d)ebug out\nLcV : v : local (v)ars\nPrg : p : (p)rogram out\nReg : g : re(g)isters\nSrc : o : s(o)urce file\nStk : t : s(t)ack\nWat : w : (w)atch\n\n\n[ layout : Main ]\n\n\u003eh\nmlq\nrnscufk\n\n\u003ew\nbbbooooo\nwwwooooo\nvvvooooo\nttpppddd\n\n[ layout : Assembly / Registers ]\n\n\u003eh\nmlq\nrnscufk\n\n\u003ew\noag\noag\noag\nwdt\n\n```\n\u003cbr\u003e\n\n\n### Resulting layouts\n\n\u003cimg src='./misc/layout1.png'\u003e\n\u003cimg src='./misc/layout2.png'\u003e\n\u003cbr\u003e\n\n### Command\n\n```\n[ command ]\n\ngdb --interpreter=mi a.out\n\n````\n\n| Debugger | Command |\n| :-----:  | ------  |\n| GDB      | `gdb --interpreter=mi a.out` |\n| PDB      | `python -m pdb app.py` |\n\u003cbr\u003e\n\n### Plugins\n\n```\n[ plugins ]\n\n# \u003cplugin code\u003e : \u003ckey binding\u003e : \u003ctitle\u003e\n\nAtP : A : (A)ttach\nCon : c : (c)ontinue\n\n```\n\n- Each three-character, case-sensitive plugin code corresponds to a specific header command or window. \n- Add parentheses around a key binding in its `(t)itle` for easy reference. This character will have a different color than the surrounding characters.\n\n\u003cbr\u003e\n\n__Header Commands__\n\u003cbr\u003e\n\n| Code    | Description           | GDB                | PDB                |\n| :-----: | ------                | :----:             | :----:             |\n| AtP     | Attach to PID, file   | :heavy_check_mark: |                    |\n| Con     | Continue              | :heavy_check_mark: | :heavy_check_mark: |\n| Fin     | Finish                | :heavy_check_mark: | :heavy_check_mark: |\n| Kil     | Kill                  | :heavy_check_mark: | :heavy_check_mark: |\n| Lay     | Choose layout         | :heavy_check_mark: | :heavy_check_mark: |\n| Nxi     | Next instruction      | :heavy_check_mark: |                    |\n| Nxt     | Next                  | :heavy_check_mark: | :heavy_check_mark: |\n| Prm     | Debugger prompt       | :heavy_check_mark: | :heavy_check_mark: |\n| Qut     | Quit                  | :heavy_check_mark: | :heavy_check_mark: |\n| Run     | Run, reload program   | :heavy_check_mark: | :heavy_check_mark: |\n| Sti     | Step instruction      | :heavy_check_mark: |                    |\n| Stp     | Step                  | :heavy_check_mark: | :heavy_check_mark: |\n| Unt     | Until                 | :heavy_check_mark: | :heavy_check_mark: |\n\u003cbr\u003e\n\n__Windows__\n\u003cbr\u003e\n\n| Code    | Description      | GDB                | PDB                |\n| :-----: | -----            | :-----:            | :------:           |\n| Asm     | Assembly code    | :heavy_check_mark: |                    |   \n| Brk     | Breakpoints      | :heavy_check_mark: | :heavy_check_mark: |\n| Dbg     | Debugger output  | :heavy_check_mark: | :heavy_check_mark: |\n| LcV     | Local variables  | :heavy_check_mark: | :heavy_check_mark: |\n| Prg     | Program output   | :heavy_check_mark: | :heavy_check_mark: |\n| Reg     | Registers        | :heavy_check_mark: |                    |\n| Src     | Source file      | :heavy_check_mark: | :heavy_check_mark: |\n| Stk     | Stack            | :heavy_check_mark: | :heavy_check_mark: |\n| Wat     | Watchpoints      | :heavy_check_mark: | :heavy_check_mark: |\n\u003cbr\u003e\n\n\n### Layouts\n\n```\n[ layout : Main ]\n\n\u003eh\nmlqrns\ncufk\n\n\u003ew\neeeooooo\nwwwooooo\nvvvooooo\nTTpppddd\n```\n\n- The order and row of each header (`\u003eh`) key binding in the configuration determines the corresponding title's position in the header window.\n- Window (`\u003ew`) size ratios and positions are determinded via \"key-binding ASCII art.\"\n\u003cbr\u003e\n\n\n## Contributing\n\n### General Guidelines\n- Submit PRs to branch [release-0.3.1](https://github.com/jvalcher/termfu/tree/release-0.3.1).\n- Bug fixes, optimizations, new debugger implementations, and plugins are welcome.\n- Use existing code conventions.\n\n### Developer notes\n- Run `make help` to print all scripts.\n- Run `make todo` to print all source file tags, such as `TODO`, `FIX`, etc.\n- Run `make build` to compile all test programs.\n- The `logd()` function in `src/utilities.h` allows for `printf()`-style debugging when running `ncurses` by outputting to `debug.out`.\n- It is recommended to create a shortcut for refreshing your terminal screen, as `ncurses` will make a mess of it when not shut down properly.\n\n### Debugging `termfu_dev` with `termfu`\n- Run `$ make debug` to start the termfu debugger. This requires `termfu` to be in your path.\n- Open a separate terminal for the debugged process.\n- Run `$ tty` and copy the terminal file name's path, e.g. `/dev/pts/1`.\n- Run `$ sleep 99999`.\n- Back in the debugger, open the prompt and run `\u003e\u003e\u003e tty /dev/pts/\u003cx\u003e`, substituting your debugged process's terminal file name.\n- Set your breakpoint and start debugging.\n\n\u003cbr\u003e\u003cbr\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjvalcher%2Ftermfu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjvalcher%2Ftermfu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjvalcher%2Ftermfu/lists"}