misc/README.md.erb in debug-1.2.4 vs misc/README.md.erb in debug-1.3.0

- old
+ new

@@ -9,11 +9,13 @@ * Fast: No performance penalty on non-stepping mode and non-breakpoints. * [Remote debugging](#remote-debugging): Support remote debugging natively. * UNIX domain socket * TCP/IP - * VSCode/DAP integration ([VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg)) + * Integeration with rich debugger frontend + * VSCode/DAP ([VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg)) + * Chrome DevTools * Extensible: application can introduce debugging support with several ways: * By `rdbg` command * By loading libraries with `-r` command line option * By calling Ruby's method explicitly * Misc @@ -334,10 +336,101 @@ ```shell $ RUBY_DEBUG_PORT=12345 ruby target.rb ``` +### Integration with external debugger frontend + +You can attach with external debuger frontend with VSCode and Chrome. + +``` +$ rdbg --open=[frontend] target.rb +``` + +will open a debug port and `[frontned]` can attache to the port. + +Also `open` command allows opening the debug port. + +#### VSCode integration + +If you don't run a debuggee Ruby process on VSCode, you can attach with VSCode later with the fowllowing steps. + +`rdbg --open=vscode` opens the debug port and tries to invoke the VSCode (`code` command). + +``` +$ rdbg --open=vscode target.rb +DEBUGGER: Debugger can attach via UNIX domain socket (/tmp/ruby-debug-sock-1000/ruby-debug-ko1-27706) +DEBUGGER: wait for debugger connection... +Launching: code /tmp/ruby-debug-vscode-20211014-27706-gd7e85/ /tmp/ruby-debug-vscode-20211014-27706-gd7e85/README.rb +DEBUGGER: Connected. +``` + +And it tris to invoke the new VSCode window and VSCode starts attaching to the debuggee Ruby program automatically. + +You can also use `open vscode` command in REPL. + +``` +$ rdbg target.rb +[1, 8] in target.rb + 1| +=> 2| p a = 1 + 3| p b = 2 + 4| p c = 3 + 5| p d = 4 + 6| p e = 5 + 7| + 8| __END__ +=>#0 <main> at target.rb:2 +(rdbg) open vscode # command +DEBUGGER: wait for debugger connection... +DEBUGGER: Debugger can attach via UNIX domain socket (/tmp/ruby-debug-sock-1000/ruby-debug-ko1-28337) +Launching: code /tmp/ruby-debug-vscode-20211014-28337-kg9dm/ /tmp/ruby-debug-vscode-20211014-28337-kg9dm/README.rb +DEBUGGER: Connected. +``` + +If the machine which runs the Ruby process doesn't have a `code` command, the following message will be shown: + +``` +(rdbg) open vscode +DEBUGGER: wait for debugger connection... +DEBUGGER: Debugger can attach via UNIX domain socket (/tmp/ruby-debug-sock-1000/ruby-debug-ko1-455) +Launching: code /tmp/ruby-debug-vscode-20211014-455-gtjpwi/ /tmp/ruby-debug-vscode-20211014-455-gtjpwi/README.rb +DEBUGGER: Can not invoke the command. +Use the command-line on your terminal (with modification if you need). + + code /tmp/ruby-debug-vscode-20211014-455-gtjpwi/ /tmp/ruby-debug-vscode-20211014-455-gtjpwi/README.rb + +If your application is running on a SSH remote host, please try: + + code --remote ssh-remote+[SSH hostname] /tmp/ruby-debug-vscode-20211014-455-gtjpwi/ /tmp/ruby-debug-vscode-20211014-455-gtjpwi/README.rb + +``` + +and try to use proposed commands. + +Note that you can attach with `rdbg --attach` and continue REPL debugging. + +#### Chrome DevTool integration + +With `rdbg --open=chrome` command will shows the following message. + +``` +$ rdbg target.rb --open=chrome +DEBUGGER: Debugger can attach via TCP/IP (127.0.0.1:43633) +DEBUGGER: With Chrome browser, type the following URL in the address-bar: + + devtools://devtools/bundled/inspector.html?ws=127.0.0.1:43633 + +DEBUGGER: wait for debugger connection... +``` + +Type `devtools://devtools/bundled/inspector.html?ws=127.0.0.1:43633` in the address-bar on Chrome browser, and you can continue the debugging with chrome browser. + +Also `open chrome` command works like `open vscode`. + +For more information about how to use Chrome debugging, you might want to read [here](https://developer.chrome.com/docs/devtools/) + ## Configuration You can configure the debugger's behavior with debug commands and environment variables. When the debug session is started, initial scripts are loaded so you can put your favorite configurations in the initial scripts. @@ -478,5 +571,6 @@ Please also check the [contributing guideline](/CONTRIBUTING.md). # Acknowledgement * Some tests are based on [deivid-rodriguez/byebug: Debugging in Ruby 2](https://github.com/deivid-rodriguez/byebug) +* Several codes in `server_cdp.rb` are based on [geoffreylitt/ladybug: Visual Debugger](https://github.com/geoffreylitt/ladybug)