{"id":15635977,"url":"https://github.com/cyrus-and/gdb","last_synced_at":"2025-07-13T09:34:27.982Z","repository":{"id":31366150,"uuid":"34929104","full_name":"cyrus-and/gdb","owner":"cyrus-and","description":"Go GDB/MI interface","archived":false,"fork":false,"pushed_at":"2023-03-21T22:46:10.000Z","size":49,"stargazers_count":82,"open_issues_count":0,"forks_count":21,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-22T01:38:43.747Z","etag":null,"topics":["debugger","gdb","go"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/cyrus-and.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}},"created_at":"2015-05-01T23:43:19.000Z","updated_at":"2025-04-08T12:26:52.000Z","dependencies_parsed_at":"2022-08-24T14:21:50.568Z","dependency_job_id":"d756c97e-2c54-4ee4-b6ef-dbc56be03b16","html_url":"https://github.com/cyrus-and/gdb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cyrus-and/gdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-and%2Fgdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-and%2Fgdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-and%2Fgdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-and%2Fgdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyrus-and","download_url":"https://codeload.github.com/cyrus-and/gdb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-and%2Fgdb/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265120702,"owners_count":23714493,"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","gdb","go"],"created_at":"2024-10-03T11:01:31.014Z","updated_at":"2025-07-13T09:34:27.935Z","avatar_url":"https://github.com/cyrus-and.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gdb\n\nPackage `gdb` provides a convenient way to interact with the GDB/MI interface. The methods offered by this module are very low level, the main goals are:\n\n- avoid the tedious parsing of the MI2 line-based text interface;\n\n- bypass a [known bug][mi2-bug] which prevents to distinguish the target program's output from MI2 records.\n\n## Web interface\n\nThis package comes with an additional [HTTP/WebSocket interface](web/) which aims to provide a straightforward way to start developing web-based GDB front ends.\n\nA dummy example can be found in the [example folder](web/example).\n\n## Example\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"github.com/cyrus-and/gdb\"\n\t\"io\"\n\t\"os\"\n)\n\nfunc main() {\n\t// start a new instance and pipe the target output to stdout\n\tgdb, _ := gdb.New(nil)\n\tgo io.Copy(os.Stdout, gdb)\n\n\t// evaluate an expression\n\tgdb.Send(\"var-create\", \"x\", \"@\", \"40 + 2\")\n\tfmt.Println(gdb.Send(\"var-evaluate-expression\", \"x\"))\n\n\t// load and run a program\n\tgdb.Send(\"file-exec-file\", \"wc\")\n\tgdb.Send(\"exec-arguments\", \"-w\")\n\tgdb.Write([]byte(\"This sentence has five words.\\n\\x04\")) // EOT\n\tgdb.Send(\"exec-run\")\n\n\tgdb.Exit()\n}\n```\n\n## Installation\n\n```\ngo get -u github.com/cyrus-and/gdb\n```\n\n## Documentation\n\n[GoDoc][godoc].\n\n## Data representation\n\nThe objects returned as a result of the commands or as asynchronous notifications are generic Go maps suitable to be converted to JSON format with `json.Marshal()`. The fields present in such objects are blindly added according to the records returned from GDB (see the [command syntax][mi2-syntax]): tuples are `map[string]interface{}` and lists are `[]interface{}`.\n\nYet, some additional fields are added:\n\n- the record class, where present, is represented by the `\"class\"` field;\n\n- the record type is represented using the `\"type\"` field as follows:\n    - `+`: `\"status\"`\n    - `=`: `\"notify\"`\n    - `~`: `\"console\"`\n    - `@`: `\"target\"`\n    - `\u0026`: `\"log\"`\n\n- the optional result list is stored into a tuple under the `\"payload\"` field.\n\nFor example, the notification:\n\n```\n=thread-group-exited,id=\"i1\",exit-code=\"0\"\n```\n\nbecomes the Go map:\n\n```go\nmap[type:notify class:thread-group-exited payload:map[id:i1 exit-code:0]]\n```\n\nwhich can be converted to JSON with `json.Marshal()` obtaining:\n\n```json\n{\n    \"class\": \"thread-group-exited\",\n    \"payload\": {\n        \"exit-code\": \"0\",\n        \"id\": \"i1\"\n    },\n    \"type\": \"notify\"\n}\n```\n\n## Mac OS X\n\n### Setting up GDB on Darwin\n\nTo use this module is mandatory to have a working version of GDB installed, Mac OS X users may obtain a copy using [Homebrew][homebrew] for example, then they may need to give GDB permission to control other processes as described [here][gdb-on-mac].\n\n### Issues\n\nThe Mac OS X support, though, is partial and buggy due to the following issues.\n\n#### Pseudoterminals\n\nI/O operations on the target program happens through a pseudoterminal obtained using the [pty][pty] package which basically uses the `/dev/ptmx` on *nix systems to request new terminal instances.\n\nThere are some unclear behaviors on Mac OS X. Calling `gdb.Write()` when the target program is not running is a no-op, on Linux instead writes are somewhat buffered and delivered later. Likewise, `gdb.Read()` may returns EOF even though there is actually data to read, a solution may be keep trying.\n\n#### Interrupt\n\nSending a `SIGINT` signal to GDB has no effect on Mac OS X, on Linux instead this is equivalent to typing `^C`, so `gdb.Interrupt()` will not work.\n\n## Development\n\nThe [goyacc](https://pkg.go.dev/golang.org/x/tools/cmd/goyacc) tool is needed to generate the `grammar.go` file. Install it with:\n\n```\ngo install golang.org/x/tools/cmd/goyacc@latest\n```\n\nAfter that use the following to update the `grammar.go` file:\n\n```\ngo generate -x\n```\n\n## Resources\n\n- [The `GDB/MI` Interface][gdb-mi]\n\n[mi2-bug]: https://sourceware.org/bugzilla/show_bug.cgi?id=8759\n[mi2-syntax]: https://sourceware.org/gdb/onlinedocs/gdb/GDB_002fMI-Output-Syntax.html\n[godoc]: https://godoc.org/github.com/cyrus-and/gdb\n[homebrew]: http://brew.sh/\n[gdb-on-mac]: http://sourceware.org/gdb/wiki/BuildingOnDarwin\n[pty]: https://github.com/kr/pty\n[gdb-mi]: https://sourceware.org/gdb/onlinedocs/gdb/GDB_002fMI.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrus-and%2Fgdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyrus-and%2Fgdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrus-and%2Fgdb/lists"}