{"id":19789527,"url":"https://github.com/webfreak001/code-debug","last_synced_at":"2025-05-15T13:07:14.691Z","repository":{"id":3408675,"uuid":"49376523","full_name":"WebFreak001/code-debug","owner":"WebFreak001","description":"Native debugging for VSCode","archived":false,"fork":false,"pushed_at":"2025-03-31T21:35:56.000Z","size":1250,"stargazers_count":422,"open_issues_count":142,"forks_count":122,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-15T13:07:13.371Z","etag":null,"topics":["debugger","extension","gdb","gdb-server","lldb","mago","ssh","vscode"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebFreak001.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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-01-10T17:09:09.000Z","updated_at":"2025-04-25T14:30:13.000Z","dependencies_parsed_at":"2024-02-07T06:31:27.918Z","dependency_job_id":"4f5f492d-2158-4a5c-9919-3a7014e64325","html_url":"https://github.com/WebFreak001/code-debug","commit_stats":{"total_commits":306,"total_committers":37,"mean_commits":8.27027027027027,"dds":0.5980392156862745,"last_synced_commit":"eb9f5e4dd7dc64f6e6e8a40115d47d30e522525c"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebFreak001%2Fcode-debug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebFreak001%2Fcode-debug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebFreak001%2Fcode-debug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebFreak001%2Fcode-debug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebFreak001","download_url":"https://codeload.github.com/WebFreak001/code-debug/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"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","extension","gdb","gdb-server","lldb","mago","ssh","vscode"],"created_at":"2024-11-12T06:33:51.183Z","updated_at":"2025-05-15T13:07:14.662Z","avatar_url":"https://github.com/WebFreak001.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Debug\n\n[![VS Marketplace](https://img.shields.io/visual-studio-marketplace/v/webfreak.debug?label=VS%20Marketplace)](https://marketplace.visualstudio.com/items?itemName=webfreak.debug)\n[![Open VSX Registry](https://img.shields.io/open-vsx/v/webfreak/debug?label=Open%20VSX)](https://open-vsx.org/extension/webfreak/debug)\n[![GitHub CI Status](https://img.shields.io/github/workflow/status/WebFreak001/code-debug/Unit%20Test%20Project?label=CI\u0026logo=GitHub)](https://github.com/WebFreak001/code-debug/actions/workflows/unit_test.yml)\n[![Coverage Status](https://img.shields.io/codecov/c/github/WebFreak001/code-debug)](https://codecov.io/github/WebFreak001/code-debug)\n\nNative VSCode debugger. Supports both GDB and LLDB.\n\n## Installation\n\nPress ctrl-p (cmd+p on OS X) and run `ext install webfreak.debug` in visual studio code and install GDB/LLDB. See `Usage` for details on how to set it up.\n\n![Preview](images/preview.png)\n\n## Usage\n\n![Image with red circle around a gear and a red arrow pointing at GDB and LLDB](images/tutorial1.png)\n\nOr if you already have an existing debugger in your project setup you can click \"Create Configuration\" or use the auto completion instead:\n\n![Visual studio code debugger launch.json auto completion showing alternative way to create debuggers](images/tutorial1-alt.png)\n\nOpen your project and click the debug button in your sidebar. At the top right press\nthe little gear icon and select GDB or LLDB. It will automatically generate the configuration\nyou need.\n\n*Note: for LLDB you need to have `lldb-mi` in your PATH*\n\nIf you are on OS X you can add `lldb-mi` to your path using\n`ln -s /Applications/Xcode.app/Contents/Developer/usr/bin/lldb-mi /usr/local/bin/lldb-mi` if you have Xcode.\n\n![Default config with a red circle around the target](images/tutorial2.png)\n\nNow you need to change `target` to the application you want to debug relative\nto the `cwd`. (Which is the workspace root by default)\n\nAdditionally you can set `terminal` if you want to run the program in a separate terminal with\nsupport for input. On Windows set it to an empty string (`\"\"`) to enable this feature. On linux\nset it to an empty string (`\"\"`) to use the default terminal emulator specified with `x-terminal-emulator`\nor specify a custom one. Note that it must support the `-e` argument.\n\nBefore debugging you need to compile your application first, then you can run it using\nthe green start button in the debug sidebar. For this you could use the `preLaunchTask`\nargument vscode allows you to do. Adding breakpoints while the program runs will not\ninterrupt it immediately. For that you need to pause \u0026 resume the program once first.\nHowever adding breakpoints while its paused works as expected.\n\nExtending variables is very limited as it does not support child values of variables.\nWatching expressions works partially but the result does not get properly parsed and\nit shows the raw output of the command. It will run `data-evaluate-expression`\nto check for variables.\n\nWhile running you will get a console where you can manually type GDB/LLDB commands or MI\ncommands prepended with a hyphen `-`. The console shows all output separated\nin `stdout` for the application, `stderr` for errors and `log` for log messages.\n\nSome exceptions/signals like segmentation faults will be caught and displayed but\nit does not support for example most D exceptions.\n\nSupport exists for stopping at the entry point of the application.  This is controlled\nthrough the `stopAtEntry` setting.  This value may be either a boolean or a string.  In\nthe case of a boolean value of `false` (the default), this setting is disabled.  In the\ncase of a boolean value of `true`, if this is a launch configuration and the debugger\nsupports the `start` (or `exec-run --start` MI feature, more specifically), than this\nwill be used to run to the entry point of the application.  Note that this appears to\nwork fine for GDB, but LLDB doesn't necessarily seem to adhere to this, even though it may\nindicate that it supports this feature.  The alternative configuration option for the\n`stopAtEntry` setting is to specify a string where the string represents the entry point\nitself.  In this situation a temporary breakpoint will be set at the specified entry point\nand a normal run will occur for a launch configuration.  This (setting a temporary\nbreakpoint) is also the behavior that occurs when the debugger does not support the\n`start` feature and the `stopAtEntry` was set to `true`.  In that case the entry point will\ndefault to \"main\".  Thus, the most portable way to use this configuration is to explicitly\nspecify the entry point of the application.  In the case of an attach configuration, similar\nbehavior will occur, however since there is no equivalent of the `start` command for\nattaching, a boolean value of `true` for the `stopAtEntry` setting in a launch configuration\nwill automatically default to an entry point of \"main\", while a string value for this\nsetting will be interpreted as the entry point, causing a temporary breakpoint to be set at\nthat location prior to continuing execution.  Note that stopping at the entry point for the\nattach configuration assumes that the entry point has not yet been entered at the time of\nattach, otherwise this will have no affect.\n\nThere is a Registers view in the VARIABLES view. As we fetch all registers at once, there can\nbe cases where a register that cannot be fetched causes the entire register request to fail,\ncorrupting the entire Registers output. If this happens, you might need to set the\n`registerLimit` option to specify which registers you want the debugger to fetch\nautomatically.\n\nFor example, to display only registers `rax` and `rip` in an x64 debug session, send the\ncommand `-data-list-register-names` in the debug console of an active x64 debug session.\nYou will then receive a response containing an array starting with `[\"rax\",\"rbx\" ...]`.\nIn this array, the index of `rax` is 0 and `rip` is 16, so set the option as\n`\"registerLimit\": \"0 16\"`. If you find the response text hard to navigate, you can paste\nit into a browser's developer tools console and press enter to get an expandable response\nobject with array elements' indices explicitly displayed.\n\n### Attaching to existing processes\n\nAttaching to existing processes currently only works by specifying the PID in the\n`launch.json` and setting `request` to `\"attach\"`. You also need to specify the executable\npath for the debugger to find the debug symbols.\n\n```\n\"request\": \"attach\",\n\"executable\": \"./bin/executable\",\n\"target\": \"4285\"\n```\n\nThis will attach to PID 4285 which should already run. GDB will pause the program on entering and LLDB will keep it running.\n\n### Using `gdbserver` for remote debugging (GDB only)\n\nYou can also connect to a gdbserver instance and debug using that. For that modify the\n`launch.json` by setting `request` to `\"attach\"` and `remote` to `true` and specifying the\nport and optionally hostname in `target`.\n\n```\n\"request\": \"attach\",\n\"executable\": \"./bin/executable\",\n\"target\": \":2345\",\n\"cwd\": \"${workspaceRoot}\",\n\"remote\": true\n```\n\nThis will attach to the running process managed by gdbserver on localhost:2345. You might\nneed to hit the start button in the debug bar at the top first to start the program.\n\nControl over whether the debugger should continue executing on connect can be configured\nby setting `stopAtConnect`.  The default value is `false` so that execution will continue\nafter connecting.\n\n### Using ssh for debugging on remote\n\nDebugging using ssh automatically converts all paths between client \u0026 server and also optionally\nredirects X11 output from the server to the client.  \nSimply add a `ssh` object in your `launch` request.\n\n```\n\"request\": \"launch\",\n\"target\": \"./executable\",\n\"cwd\": \"${workspaceRoot}\",\n\"ssh\": {\n\t\"forwardX11\": true,\n\t\"host\": \"192.168.178.57\",\n\t\"cwd\": \"/home/remoteUser/project/\",\n\t\"keyfile\": \"/path/to/.ssh/key\", // OR\n\t\"password\": \"password123\",\n\t\"user\": \"remoteUser\",\n\t\"x11host\": \"localhost\",\n\t// x11port may also be specified as string containing only numbers (useful to use configuration variables)\n\t\"x11port\": 6000,\n\t// Optional, content will be executed on the SSH host before the debugger call.\n\t\"bootstrap\": \"source /home/remoteUser/some-env\"\n}\n```\n\n`ssh.sourceFileMap` will be used to trim off local paths and map them to the server. This is\nrequired for basically everything except watched variables or user commands to work.\n\nFor backward compatibility you can also use `cwd` and `ssh.cwd` for the mapping, this is only used\nif the newer `ssh.sourceFileMap` is not configured.\n\nFor X11 forwarding to work you first need to enable it in your Display Manager and allow the\nconnections. To allow connections you can either add an entry for applications or run `xhost +`\nin the console while you are debugging and turn it off again when you are done using `xhost -`.\n\nBecause some builds requires one or more environment files to be sourced before running any\ncommand, you can use the `ssh.bootstrap` option to add some extra commands which will be prepended\nto the debugger call (using `\u0026\u0026` to join both).\n\n### Debugging a process from a different user (especially root/system processes)\n\nTo debug a program that needs additional privileges you may use one of the two approaches:\n\n1. start vscode with the necessary rights (so both the program and the started debugger instance will\n   have root rights) - `sudo code` / `sudo codium` or \"start as admin\".  \n   Note that this has a lot of security implications and will have the user settings of vscode for this user.\n3. preferred: use a small wrapper script that calls `sudo gdb $*` / `runas /profile /user:admin-user`\n   (or the debugger of your choice) and configure this extension to use it (for example with `gdbpath`)\n\n### Extra Debugger Arguments\n\nAdditional arguments can be supplied to the debugger if needed.  These will be added when\nthe debugger executable (e.g., gdb, lldb-mi, etc.) is launched.  Extra debugger arguments\nare supplied via the `debugger_args` setting.  Note that the behavior of escaping these\noptions depends on the environment in which the debugger is started.  For non-SSH\ndebugging, the options are passed directly to the application and therefore no escaping is\nnecessary (other than what is necessary for the JSON configuration). However, as a result\nof the options being passed directly to the application, care must be taken to place\nswitches and switch values as separate entities in `debugger_args`, if they would normally\nbe separated by a space.   For example, supplying the option and value\n`-iex \"set $foo = \\\"bar\\\"\"` would consist of the following `debugger_args`:\n```json\n\"debugger_args\" : [\"-iex\", \"set $foo = \\\"bar\\\"\"]\n```\nIf `=` is used to associate switches with their values, than the switch and value should\nbe placed together instead.  In fact, the following example shows 4 different ways in\nwhich to specify the same switch and value, using both short and long format, as well as\nswitch values supplied as a separate parameter or supplied via the `=`:\n- ```json\n  \"debugger_args\" : [\"-iex\", \"set $foo = \\\"bar\\\"\"]\n  ```\n- ```json\n  \"debugger_args\" : [\"-iex=set $foo = \\\"bar\\\"\"]\n  ```\n- ```json\n  \"debugger_args\" : [\"--init-eval-command\", \"set $foo = \\\"bar\\\"\"]\n  ```\n- ```json\n  \"debugger_args\" : [\"--init-eval-command=set $foo = \\\"bar\\\"\"]\n  ```\nWhere escaping is really necessary is when running the debugger over SSH.  In this case,\nthe options are not passed directly to the application, but are instead combined with the\napplication name, joined together with any other options, and sent to the remote system to\nbe parsed and executed.  Thus, depending on the remote system, different escaping may be\nnecessary.  The following shows how the same command as above needs to be escaped\ndifferently based on whether the remote system is a POSIX or a Windows system.\n- SSH to Linux machine:\n  ```json\n  \"debugger_args\": [\"-iex\", \"'set $foo = \\\"bar\\\"'\"]\n  ```\n- SSH to Windows machine:\n  ```json\n  \"debugger_args\": [\"-iex\", \"\\\"set $foo = \\\\\\\"bar\\\\\\\"\\\"\"]\n  ```\nYou may need to experiment to find the correct escaping necessary for the command to be\nsent to the debugger as you intended.\n\n### LogMessage\n\nLogMessage will print a message in the debug console when breakpoint is hit. Expressions within {} are interpolated.\n\n![LogMessage](images/logMessage.gif)\n\n## [Issues](https://github.com/WebFreak001/code-debug)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebfreak001%2Fcode-debug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebfreak001%2Fcode-debug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebfreak001%2Fcode-debug/lists"}