{"id":13578151,"url":"https://github.com/godzie44/BugStalker","last_synced_at":"2025-04-05T16:32:00.615Z","repository":{"id":65041869,"uuid":"579992560","full_name":"godzie44/BugStalker","owner":"godzie44","description":"Rust debugger for Linux x86-64","archived":false,"fork":false,"pushed_at":"2024-04-12T16:31:20.000Z","size":6403,"stargazers_count":278,"open_issues_count":5,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-14T15:24:23.026Z","etag":null,"topics":["debugger","linux","rust"],"latest_commit_sha":null,"homepage":"","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/godzie44.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,"dei":null}},"created_at":"2022-12-19T13:02:37.000Z","updated_at":"2024-07-27T12:40:19.860Z","dependencies_parsed_at":"2023-02-18T08:15:15.487Z","dependency_job_id":"d49af095-35c6-496a-b1ea-e7b8dbd41e71","html_url":"https://github.com/godzie44/BugStalker","commit_stats":null,"previous_names":["godzie44/bugstalker"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godzie44%2FBugStalker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godzie44%2FBugStalker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godzie44%2FBugStalker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godzie44%2FBugStalker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/godzie44","download_url":"https://codeload.github.com/godzie44/BugStalker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247366422,"owners_count":20927503,"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":["debugger","linux","rust"],"created_at":"2024-08-01T15:01:27.938Z","updated_at":"2025-04-05T16:32:00.610Z","avatar_url":"https://github.com/godzie44.png","language":"Rust","funding_links":[],"categories":["Rust","Development tools","⭐ Top Extensions","Recently Updated","linux","💻 Apps"],"sub_categories":["Debugging","[May 05, 2025](/content/2025/05/05/README.md)","⌨️ Development Tools"],"readme":"# BugStalker\n\n\u003e Modern debugger for Linux x86-64. Written in Rust for Rust programs.\n\n![debugger-demo](doc/demo.gif)\n\n---\n\n# Table of Contents\n\n- [BugStalker](#bugstalker)\n    * [Supported rustc versions](#supported-rustc-versions)\n    * [Features](#features)\n    * [Installation](#installation)\n    * [Start debugger session](#start-debugger-session)\n    * [Help](#help)\n    * [Start and restart](#start-and-restart)\n    * [Stopping and continuing](#stopping-and-continuing)\n        * [Breakpoints](#breakpoints)\n        * [Watchpoints](#watchpoints)\n        * [Steps](#steps)\n        * [Signals](#signals)\n    * [Examining the stack](#examining-the-stack)\n    * [Examining source files](#examining-source-files)\n    * [Examining data](#examining-data)\n    * [Other commands](#other-commands)\n    * [Tui interface](#tui-interface)\n        * [Configuration](#configuration)\n    * [Oracles](#oracles)\n- [Contributing](#contributing)\n\n---\n\n## Supported rustc versions\n\n- 1.75\n- 1.76\n- 1.77\n- 1.78\n- 1.79\n- 1.80\n- 1.81\n- 1.82\n- 1.83\n- 1.84\n- 1.85\n\n---\n\n## Features\n\n* written in rust for rust language with simplicity as a priority goal\n* [breakpoints, steps, signals, watchpoints](#stopping-and-continuing)\n* multithreaded application support\n* [data query expressions](#examining-data)\n* support for a rust type system (collections, smart pointers, thread locals and\n  many others), not only for printing but also for interaction\n* two ui types: console and [tui](#tui-interface), switch available at any\n  moment\n* [oracle](#oracles) as an extension mechanism\n* builtin [tokio oracle](#oracles) -\n  like [tokio_console](https://github.com/tokio-rs/console) but there is no need\n  to make changes to the source codes\n* and much more!\n\n---\n\n## Installation\n\nFirst check if the necessary dependencies\n(`pkg-config` and `libunwind-dev`) are installed:\n\nFor example, ubuntu/debian:\n\n```shell\napt install pkg-config libunwind-dev\n```\n\nFor example, fedora:\n\n```shell\ndnf install pkg-config libunwind-devel\n```\n\nNow install debugger:\n\n```shell\ncargo install bugstalker\n```\n\nThat's all, `bs` command is available now!\n\n\u003cdetails\u003e\n  \u003csummary\u003eProblem with libunwind?\u003c/summary\u003e\nIf you have any issues with `libunwind`, you can try to install `bs` with\nnative unwinder \n(currently, I don't recommend this method because libunwind is better :))\n\n```shell\ncargo install bugstalker --no-default-features\n```\n\n\u003c/details\u003e\n\n### Distro Packages\n\n\u003cdetails\u003e\n  \u003csummary\u003ePackaging status\u003c/summary\u003e\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/bugstalker.svg)](https://repology.org/project/bugstalker/versions)\n\n\u003c/details\u003e\n\n#### Arch Linux\n\n```shell\npacman -S bugstalker\n```\n\n#### Nix package manager\n\nThere's flake which you can use to start using it.\nJust [enable flakes](https://wiki.nixos.org/wiki/Flakes#Enable_flakes_temporarily)\nthen you're able to use it with:\n\n```\nnix run github:godzie44/BugStalker\n```\n\n`bugstalker` also provides a package which you can include to your NixOS config.\nFor example:\n\n\u003cdetails\u003e\n\n```nix\n{\n  inputs = {\n    nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n    bugstalker.url = \"github:godzie44/BugStalker\";\n  };\n\n  outpus = {nixpkgs, bugstalker, ...}: {\n    nixosConfigurations.your_hostname = nixpkgs.lib.nixosSystem {\n      modules = [\n        ({...}: {\n          environment.systemPackages = [\n            # assuming your system runs on a x86-64 cpu\n            bugstalker.packages.\"x86_64-linux\".default\n          ];\n        })\n      ];\n    };\n  };\n}\n```\n\n\u003c/details\u003e\n\n##### Home-Manager\n\nThere's a home-manager module which adds `programs.bugstalker` to your home-manager config.\nYou can add it by doing the following:\n\n\u003cdetails\u003e\n\n```nix\n{\n  description = \"NixOS configuration\";\n\n  inputs = {\n    nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n    home-manager.url = \"github:nix-community/home-manager\";\n    home-manager.inputs.nixpkgs.follows = \"nixpkgs\";\n    bugstalker.url = \"github:godzie44/BugStalker\";\n  };\n\n  outputs = inputs@{ nixpkgs, home-manager, bugstalker, ... }: {\n    nixosConfigurations = {\n      hostname = nixpkgs.lib.nixosSystem {\n        system = \"x86_64-linux\";\n        modules = [\n          ./configuration.nix\n          home-manager.nixosModules.home-manager\n          {\n            home-manager.sharedModules = [\n              bugstalker.homeManagerModules.default\n              ({...}: {\n                programs.bugstalker = {\n                  enable = true;\n                  # the content of `keymap.toml`\n                  keymap = {\n                    common = {\n                      up = [\"k\"];\n                    }\n                  };\n                };\n              })\n            ];\n          }\n        ];\n      };\n    };\n  };\n}\n```\n\n\u003c/details\u003e\n\n---\n\n## Start debugger session\n\nTo start with program from binary file use:\n\n```shell\nbs my_cool_program\n```\n\nOr with arguments:\n\n```shell\nbs my_cool_program -- --arg1 val1 --arg2 val2\n```\n\nOr attach to program by its pid:\n\n```shell\nbs -p 123\n```\n\n## Help\n\nPrint `help` for view all available commands.\n\n## Start and restart\n\n[demo](https://github.com/godzie44/BugStalker/blob/master/doc/demo_run.gif)\n\n- `run` - start or restart a program (alias: `r`)\n\n## Stopping and continuing\n\nThe Debugger stops your program when breakpoints are hit,\nor after watchpoint are hit,\nor after steps commands,\nor when the OS signal is coming.\nBugStalker always stops the whole program, meaning that all threads are stopped.\nThread witch initiated a stop become a current selected thread.\n\n### Continue execution\n\n[demo](https://github.com/godzie44/BugStalker/blob/master/doc/demo_cont.gif)\n\n- `continue` - resume a stopped program\n\n### Breakpoints\n\n[demo](https://github.com/godzie44/BugStalker/blob/master/doc/demo_brkpt.gif)\n\n- `break {file}:{line}` - set breakpoint at line (alias: `b {file}:{line}`)\n- `break {function name}` - set breakpoint at start of the function (\n  alias: `b {function_name}`)\n- `break {instruction address}` - set breakpoint at instruction (\n  alias: `b {instruction address}`)\n- `break remove {number}` - remove breakpoint by its number (\n  alias: `b r {number}`)\n- `break remove {file}:{line}` - remove breakpoint at line (\n  alias: `b r {file}:{line}`)\n- `break remove {function name}` - remove breakpoint at start of the function (\n  alias: `b r {function name}`)\n- `break info` - print all breakpoints\n\n### Watchpoints\n\n[demo](https://github.com/godzie44/BugStalker/blob/master/doc/demo_watch.gif)\n\nWatchpoint is a \"data breakpoint\".\nThis means that the program stops when the variable (or expression, or just raw memory region)\nobserved by watchpoint is changed.\nCurrently, watchpoints feature based on `x86-64` hardware breakpoints.\nTherefore, there are two limitations:\n\n- only 4 watchpoints are possible at one time\n- watchpoint \"observe\" memory region of 1/2/4/8 bytes size\n\nYou can set watchpoint at variables (global or locals), or at expression based on variables.\nWatchpoints for local variables will be removed automatically, when variable out of scope.\nIf watchpoint observes a global variable, then it will live as long as the debugger is running.\n\nLets look at examples:\n\n- `watch my_var` - stop when variable value is rewriting (alias: `w my_var`)\n- `watch +rw my_var` - stop when variable value is reading or rewriting\n- `watch my_vector[0]` - stop when first vector element is rewriting\n- `watch (~my_vector).len` - stop when vector length is changed\n- `watch 0x100:4` - stop when writing to memory region [0x100:0x103]\n\n### Steps\n\n[demo](https://github.com/godzie44/BugStalker/blob/master/doc/demo_step.gif)\n\n- `stepi` - step a single instruction\n- `step` - step a program until it reaches a different source line (\n  alias: `stepinto`)\n- `next` - step a program, stepping over subroutine (function) calls (\n  alias: `stepover`)\n- `finish` - execute a program until selected stack frame returns (\n  alias: `stepout`)\n\n### Signals\n\n[demo](https://github.com/godzie44/BugStalker/blob/master/doc/demo_signal.gif)\n\n`BugStalker` will catch signals sent from OS to debugee program and stop execution.\nFor example, try to send SIGINT (ctrl+c) to the debugee program to stop it.\n\n### Change current selected thread\n\n[demo](https://github.com/godzie44/BugStalker/blob/master/doc/demo_thread.gif)\n\n- `thread info` - print list with information about threads\n- `thread current` - prints current selected thread\n- `thread switch {number}` - switch selected thread\n\n## Examining the stack\n\nWhen your program has stopped,\nthe first thing you need to know is where it stopped and how it got there.\n\nEach time your program performs a function call,\nthe information about where in your program the call was made from is saved in a\nblock of data\ncalled a stack frame.\nThe frame also contains the arguments of the call and the local variables of the\nfunction\nthat was called.\nAll the stack frames are allocated in a region of memory called the call stack.\n\n### Stack frames\n\nThe call stack is divided up into contiguous pieces called stack frames.\nEach frame is the data associated with one call to one function.\nThe frame contains the arguments given to the function,\nthe function's local variables,\nand the address at which the function is executed.\n\n### Backtrace\n\n[demo](https://github.com/godzie44/BugStalker/blob/master/doc/demo_bt.gif)\n\n- `backtrace` - print backtrace of current stopped thread (alias: `bt`).\n  Backtrace contains information about thread\n  (number, pid, address of instruction where thread stopped)\n  and all frames starting with the currently executing frame (frame zero),\n  followed by its caller (frame one), and on up the stack.\n- `backtrace all` - print backtraces of all active threads (alias: `bt all`).\n\n### Select a frame\n\n[demo](https://github.com/godzie44/BugStalker/blob/master/doc/demo_frame.gif)\n\nMost commands\nfor examining the stack and other data in your program works\non whichever stack frame is selected at the moment.\n\n- `frame info` - print information about current selected frame.\n- `frame switch {num}` - change current selected frame.\n\n## Examining source files\n\n[demo](https://github.com/godzie44/BugStalker/blob/master/doc/demo_source.gif)\n\nBugStalker can print parts of your program's source code.\nWhen your program stops,\nthe debugger spontaneously prints the line where it stopped.\nThere is `source` commands for print more.\n\n- `source fn` - print current selected function\n- `source {num}` - print lines range [current_line-num; current_line+num]\n- `source asm` - print assembly representation of current selected function\n\n## Examining data\n\n[demo](https://github.com/godzie44/BugStalker/blob/master/doc/demo_data.gif)\n\nOf course, you need a way to examine data of your program.\n\n- `var {expression}|locals` command for print local and global variables\n- `arg {expression}|all` command for print a function arguments\n\nThese commands accept expressions as input or have a special mode\n(`var locals` print all local variables, `args all` print all arguments).\n\n### Expression\n\nBugStalker has a special syntax for explore program data.\nYou can dereference references, get structure fields,\nslice arrays or get elements from vectors by its index (and much more!).\n\nOperator available in expressions:\n\n- select variable by its name (ex. `var a`)\n- dereference pointers/references/smart pointers (ex. `var *ref_to_a`)\n- take a structure field (ex. `var some_struct.some_field`)\n- take an element by index or key from arrays, slices, vectors, hashmaps (\n  ex. `var arr[1]` or even `var hm[{a: 1, b: 2}]`)\n- slice arrays, vectors, slices (ex. `var some_vector[1..3]`\n  or `var some_vector[1..]`)\n- cast constant address to a pointer of a concrete type (\n  ex. `var (*mut SomeType)0x123AABCD`)\n- take address (ex. `var \u0026some_struct.some_field`)\n- show canonic representation (for example, show vector header instead of vector data `var ~myvec`)\n- parentheses for control an operator execution ordering\n\nWrite expressions is simple, and you can do it right now!\nSome examples:\n\n- `var *some_variable` - dereference and print value of `some_variable`\n- `var hm[{a: 1, b: *}]` - print value from hashmap corresponding to the key.\n  Literal `{a: 1, b: *}` matches to any structure with field `a` equals to 1 and field `b` equals to any value\n- `var some_array[0][2..5]` - print three elements, starts from index 2 from\n  zero element of `some_array`\n- `var *some_array[0]` - print dereferenced value of `some_array[0]`\n- `var \u0026some_array[0]` - print address of `some_array[0]`\n- `var (~some_vec).len` - print len field from vector header\n- `var (*some_array)[0]` - print a zero element of `*some_array`\n- `var *(*(var1.field1)).field2[1][2]` - print dereferenced value of element at\n  index 2 in\n  element at index 1 at field `field2` in dereferenced value of field `field1`\n  at variable var1 🤡\n\n## Other commands\n\nOf course, the debugger provides many more commands:\n\n- `symbol {name or regex}` - print symbol kind and address\n- `memory read {addr}` - read debugged program memory (alias: `mem read`)\n- `memory write {addr} {value}` - write into debugged program memory (\n  alias: `mem write`)\n- `register read {reg_name}` - print value of register by name (x86_64 register\n  name in lowercase) (alias: `reg read`)\n- `register write {reg_name} {value}` - set new value to register by name (\n  alias: `reg write`)\n- `register info` - print list of registers with it values (alias: `reg info`)\n- `sharedlib info` - show list of shared libraries\n- `quit` - exit the BugStalker (alias: `q`)\n\n## Tui interface\n\n[demo](https://github.com/godzie44/BugStalker/blob/master/doc/demo_tui.gif)\n\nOne of the most funny BugStalker features is switching between old school\nterminal interface and pretty tui at any moment.\n\n- `tui` - switch too terminal ui (in tui use `Esc` for switch back)\n\n### Configuration\n\nThere is a `keymap.toml` file with tui keybindings configuration.\nYou can find the default configuration files\nat https://github.com/godzie44/BugStalker/tree/master/src/ui/tui/config/preset/keymap.toml.\n\nTo override any of the defaults, begin by creating the corresponding file (from the file linked above) to:\n`~/.config/bs/keymap.toml`.\nYou can change keybindings configuration file by exporting the `KEYMAP_FILE` environment variable.\n\n## Oracles\n\n[demo console](https://github.com/godzie44/BugStalker/blob/master/doc/demo_oracle.gif)\n\n[demo tui](https://github.com/godzie44/BugStalker/blob/master/doc/demo_oracle_tui.gif)\n\nOracle is a module that expands the capabilities of the debugger.\nOracles can monitor the internal state of a program\nto display interesting information.\nFor example, tokio oracle is able\nto provide information about tokio runtime during program debugging without the\nneed\nto change the source code.\nYou must run the debugger with enabled oracle, for example, for tokio oracle:\n\n```bash\nbs --oracle tokio ...\n```\n\nThen use `oracle` command for view oracle information:\n\n- `oracle {oracle name} {subcommands}` - run oracle (ex. `oracle tokio`)\n\nOracles also available in tui.\nCurrently, there is only one builtin oracle - tokio oracle.\n\n## Contributing\n\nFeel free to suggest changes, ask a question or implement a new feature.\nAny contributions are very welcome.\n\n[How to contribute](https://github.com/godzie44/BugStalker/blob/master/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgodzie44%2FBugStalker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgodzie44%2FBugStalker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgodzie44%2FBugStalker/lists"}