debug 1.6.1 → 1.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CONTRIBUTING.md +22 -10
- data/Gemfile +0 -0
- data/LICENSE.txt +0 -0
- data/README.md +84 -55
- data/Rakefile +8 -3
- data/TODO.md +8 -8
- data/debug.gemspec +3 -3
- data/exe/rdbg +19 -4
- data/ext/debug/debug.c +33 -5
- data/ext/debug/extconf.rb +1 -0
- data/ext/debug/iseq_collector.c +2 -0
- data/lib/debug/abbrev_command.rb +77 -0
- data/lib/debug/breakpoint.rb +15 -11
- data/lib/debug/client.rb +26 -8
- data/lib/debug/color.rb +0 -0
- data/lib/debug/config.rb +69 -23
- data/lib/debug/console.rb +8 -29
- data/lib/debug/dap_custom/traceInspector.rb +336 -0
- data/lib/debug/frame_info.rb +9 -0
- data/lib/debug/irb_integration.rb +27 -0
- data/lib/debug/local.rb +16 -10
- data/lib/debug/open.rb +0 -0
- data/lib/debug/open_nonstop.rb +0 -0
- data/lib/debug/prelude.rb +2 -1
- data/lib/debug/server.rb +32 -27
- data/lib/debug/server_cdp.rb +360 -155
- data/lib/debug/server_dap.rb +330 -197
- data/lib/debug/session.rb +494 -258
- data/lib/debug/source_repository.rb +41 -21
- data/lib/debug/start.rb +1 -1
- data/lib/debug/thread_client.rb +241 -82
- data/lib/debug/tracer.rb +4 -5
- data/lib/debug/version.rb +1 -1
- data/lib/debug.rb +7 -2
- data/misc/README.md.erb +50 -44
- metadata +13 -10
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: cbc923d5ce88d6092dbc8125ee988ec386fffdc3409b8bca4113ab925bc61311
|
4
|
+
data.tar.gz: 2e0a5013263c3c220dfee989af1a87c224f36bf03504fef120785717df5b9ef7
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: eb62ffd4d8111449f618b8a91a4ab9b89237916eeb71e0fd57dd1d78d4ddadff4a3897cbdf989cd989b9c0a52103f8bfd02f1e6cd9d2453b70bd72025f1b63aa
|
7
|
+
data.tar.gz: 81607797fa369d2eeed0fe35335d078ea04be3ab653dea8b653b0c25453c2000407a532c17246d41be175f1df34d7bebc069deb83fef976b39a79df2a399b79c
|
data/CONTRIBUTING.md
CHANGED
@@ -149,10 +149,10 @@ If the file already exists, **only method** will be added to it.
|
|
149
149
|
```ruby
|
150
150
|
# frozen_string_literal: true
|
151
151
|
|
152
|
-
require_relative '../support/
|
152
|
+
require_relative '../support/console_test_case'
|
153
153
|
|
154
154
|
module DEBUGGER__
|
155
|
-
class FooTest <
|
155
|
+
class FooTest < ConsoleTestCase
|
156
156
|
def program
|
157
157
|
<<~RUBY
|
158
158
|
1| module Foo
|
@@ -166,7 +166,7 @@ module DEBUGGER__
|
|
166
166
|
9| end
|
167
167
|
RUBY
|
168
168
|
end
|
169
|
-
|
169
|
+
|
170
170
|
def test_1629720194
|
171
171
|
debug_code(program) do
|
172
172
|
type 's'
|
@@ -269,10 +269,10 @@ Currently, there are 2 kinds of test frameworks for DAP and CDP.
|
|
269
269
|
|
270
270
|
If you want to write protocol-based tests, you should use the test generator.
|
271
271
|
To run the test generator, you can enter `$ bin/gentest target.rb --open=vscode` in the terminal, VSCode will be executed.
|
272
|
-
Also, if you enter
|
272
|
+
Also, if you enter `$ bin/gentest target.rb --open=chrome` there, Chrome will be executed.
|
273
273
|
If you need to modify existing tests, it is basically a good idea to regenerate them by the test generator instead of rewriting them directly.
|
274
274
|
Please refer to [the Microsoft "Debug Adapter Protocol" article](https://microsoft.github.io/debug-adapter-protocol/specification) to learn more about DAP formats.
|
275
|
-
Please refer to [
|
275
|
+
Please refer to [the "Chrome DevTools Protocol" official documentation](https://chromedevtools.github.io/devtools-protocol/) to learn more about CDP formats.
|
276
276
|
|
277
277
|
2. High-level tests
|
278
278
|
|
@@ -320,6 +320,22 @@ Execute debugging `program` with `&scenario`. If you want to test it only for DA
|
|
320
320
|
|
321
321
|
`run_protocol_scenario program, cdp: false ...`
|
322
322
|
|
323
|
+
- attach_to_dap_server(terminate_debuggee:)
|
324
|
+
|
325
|
+
Attach to the running DAP server through UNIX Domain Socket.
|
326
|
+
|
327
|
+
- attach_to_cdp_server
|
328
|
+
|
329
|
+
Attach to the running CDP server through TCP/IP.
|
330
|
+
|
331
|
+
- req_dap_disconnect
|
332
|
+
|
333
|
+
Disconnect from the currently connected DAP server.
|
334
|
+
|
335
|
+
- req_cdp_disconnect
|
336
|
+
|
337
|
+
Disconnect from the currently connected CDP server.
|
338
|
+
|
323
339
|
- req_add_breakpoint(lineno, path: temp_file_path, cond: nil)
|
324
340
|
|
325
341
|
Sends request to rdbg to add a breakpoint.
|
@@ -336,7 +352,7 @@ Sends request to rdbg to set exception breakpoints. e.g.
|
|
336
352
|
req_set_exception_breakpoints([{ name: "RuntimeError", condition: "a == 1" }])
|
337
353
|
```
|
338
354
|
|
339
|
-
Please note that `setExceptionBreakpoints` resets all exception breakpoints in every request.
|
355
|
+
Please note that `setExceptionBreakpoints` resets all exception breakpoints in every request.
|
340
356
|
|
341
357
|
So the following code will only set breakpoint for `Exception`.
|
342
358
|
|
@@ -377,10 +393,6 @@ Sends request to rdbg to step back from current method.
|
|
377
393
|
|
378
394
|
Sends request to rdbg to terminate the debuggee.
|
379
395
|
|
380
|
-
- assert_reattach
|
381
|
-
|
382
|
-
Passes if reattaching to rdbg is successful.
|
383
|
-
|
384
396
|
- assert_hover_result(expected, expression)
|
385
397
|
|
386
398
|
Passes if result of `expression` matches `expected`.
|
data/Gemfile
CHANGED
File without changes
|
data/LICENSE.txt
CHANGED
File without changes
|
data/README.md
CHANGED
@@ -2,9 +2,9 @@
|
|
2
2
|
|
3
3
|
# debug.rb
|
4
4
|
|
5
|
-
This library provides debugging functionality to Ruby (MRI) 2.
|
5
|
+
This library provides debugging functionality to Ruby (MRI) 2.7 and later.
|
6
6
|
|
7
|
-
This debug.rb is replacement of traditional lib/debug.rb standard library which is implemented by `set_trace_func`.
|
7
|
+
This debug.rb is the replacement of traditional lib/debug.rb standard library, which is implemented by `set_trace_func`.
|
8
8
|
New debug.rb has several advantages:
|
9
9
|
|
10
10
|
* Fast: No performance penalty on non-stepping mode and non-breakpoints.
|
@@ -18,7 +18,7 @@ New debug.rb has several advantages:
|
|
18
18
|
Connection | UDS, TCP/IP | UDS, TCP/IP | TCP/IP |
|
19
19
|
Requirement | No | [vscode-rdbg](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) | Chrome |
|
20
20
|
|
21
|
-
* Extensible: application can introduce debugging support
|
21
|
+
* Extensible: application can introduce debugging support in several ways:
|
22
22
|
* By `rdbg` command
|
23
23
|
* By loading libraries with `-r` command line option
|
24
24
|
* By calling Ruby's method explicitly
|
@@ -26,7 +26,7 @@ New debug.rb has several advantages:
|
|
26
26
|
* Support threads (almost done) and ractors (TODO).
|
27
27
|
* Support suspending and entering to the console debugging with `Ctrl-C` at most of timing.
|
28
28
|
* Show parameters on backtrace command.
|
29
|
-
* Support recording &
|
29
|
+
* Support recording & replay debugging.
|
30
30
|
|
31
31
|
# Installation
|
32
32
|
|
@@ -55,7 +55,7 @@ To use a debugger, roughly you will do the following steps:
|
|
55
55
|
4. Use debug commands.
|
56
56
|
* [Evaluate Ruby expressions](#evaluate) (e.g. `p lvar` to see the local variable `lvar`).
|
57
57
|
* [Query the program status](#information) (e.g. `info` to see information about the current frame).
|
58
|
-
* [Control program flow](#control-flow) (e.g. move to
|
58
|
+
* [Control program flow](#control-flow) (e.g. move to another line with `step`, to the next line with `next`).
|
59
59
|
* [Set another breakpoint](#breakpoint) (e.g. `catch Exception` to set a breakpoint that'll be triggered when `Exception` is raised).
|
60
60
|
* [Activate tracing in your program](#trace) (e.g. `trace call` to trace method calls).
|
61
61
|
* [Change the configuration](#configuration-1) (e.g. `config set no_color true` to disable coloring).
|
@@ -180,7 +180,7 @@ DEBUGGER: Session start (pid: 7656)
|
|
180
180
|
#1 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
|
181
181
|
```
|
182
182
|
|
183
|
-
You can see that two breakpoints are registered. Let's continue the program by `continue` command.
|
183
|
+
You can see that two breakpoints are registered. Let's continue the program by using the `continue` command.
|
184
184
|
|
185
185
|
```shell
|
186
186
|
(rdbg) continue
|
@@ -200,8 +200,8 @@ Stop by #0 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
|
|
200
200
|
```
|
201
201
|
|
202
202
|
You can see that we can stop at line 3.
|
203
|
-
Let's see the local variables with `info` command, and continue.
|
204
|
-
You can also confirm that the program will suspend at line 5 and you can use `info` command again.
|
203
|
+
Let's see the local variables with the `info` command, and continue.
|
204
|
+
You can also confirm that the program will suspend at line 5 and you can use the `info` command again.
|
205
205
|
|
206
206
|
```shell
|
207
207
|
(rdbg) info
|
@@ -238,14 +238,14 @@ d => 4
|
|
238
238
|
```
|
239
239
|
|
240
240
|
By the way, using `rdbg` command you can suspend your application with `C-c` (SIGINT) and enter the debug console.
|
241
|
-
It will help
|
241
|
+
It will help if you want to know what the program is doing.
|
242
242
|
|
243
243
|
### Use `rdbg` with commands written in Ruby
|
244
244
|
|
245
|
-
If you want to run a command written in Ruby like
|
245
|
+
If you want to run a command written in Ruby like `rake`, `rails`, `bundle`, `rspec`, and so on, you can use `rdbg -c` option.
|
246
246
|
|
247
247
|
* Without `-c` option, `rdbg <name>` means that `<name>` is Ruby script and invoke it like `ruby <name>` with the debugger.
|
248
|
-
* With `-c` option, `rdbg -c <name>` means that `<name>` is command in `PATH` and simply
|
248
|
+
* With `-c` option, `rdbg -c <name>` means that `<name>` is a command in `PATH` and simply invokes it with the debugger.
|
249
249
|
|
250
250
|
Examples:
|
251
251
|
* `rdbg -c -- rails server`
|
@@ -263,27 +263,27 @@ Like other languages, you can use this debugger on the VSCode.
|
|
263
263
|
|
264
264
|
1. Install [VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg)
|
265
265
|
2. Open `.rb` file (e.g. `target.rb`)
|
266
|
-
3. Register breakpoints with "Toggle breakpoint" in Run menu (or type F9 key)
|
266
|
+
3. Register breakpoints with "Toggle breakpoint" in the Run menu (or type F9 key)
|
267
267
|
4. Choose "Start debugging" in "Run" menu (or type F5 key)
|
268
|
-
5. You will see a dialog "Debug command line" and you can choose your favorite command line
|
269
|
-
6. Chosen command line is invoked with `rdbg -c
|
268
|
+
5. You will see a dialog "Debug command line" and you can choose your favorite command line you want to run.
|
269
|
+
6. Chosen command line is invoked with `rdbg -c`, and VSCode shows the details at breakpoints.
|
270
270
|
|
271
|
-
Please refer [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) for operations on VSCode.
|
271
|
+
Please refer to [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) for operations on VSCode.
|
272
272
|
|
273
273
|
You can configure the extension in `.vscode/launch.json`.
|
274
274
|
Please see the extension page for more details.
|
275
275
|
|
276
276
|
## Remote debugging
|
277
277
|
|
278
|
-
You can use this debugger as a remote debugger. For example, it will help the following situations:
|
278
|
+
You can use this debugger as a remote debugger. For example, it will help in the following situations:
|
279
279
|
|
280
|
-
* Your application does not run on TTY and it is hard to use `binding.pry` or `binding.irb`.
|
281
|
-
* Your application is running on Docker container and there is no TTY.
|
280
|
+
* Your application does not run on TTY, and it is hard to use `binding.pry` or `binding.irb`.
|
281
|
+
* Your application is running on a Docker container, and there is no TTY.
|
282
282
|
* Your application is running as a daemon.
|
283
283
|
* Your application uses pipe for STDIN or STDOUT.
|
284
284
|
* Your application is running as a daemon and you want to query the running status (checking a backtrace and so on).
|
285
285
|
|
286
|
-
You can run your application as a remote debuggee and the remote debugger console can attach to the debuggee anytime.
|
286
|
+
You can run your application as a remote debuggee, and the remote debugger console can attach to the debuggee anytime.
|
287
287
|
|
288
288
|
### Invoke as a remote debuggee
|
289
289
|
|
@@ -305,7 +305,7 @@ DEBUGGER: Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock
|
|
305
305
|
DEBUGGER: wait for debugger connection...
|
306
306
|
```
|
307
307
|
|
308
|
-
By default, `rdbg --open` uses UNIX domain socket and generates path name automatically (`/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773` in this case).
|
308
|
+
By default, `rdbg --open` uses UNIX domain socket and generates the path name automatically (`/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773` in this case).
|
309
309
|
|
310
310
|
You can connect to the debuggee with `rdbg --attach` command (`rdbg -A` for short).
|
311
311
|
|
@@ -324,11 +324,11 @@ $ rdbg -A
|
|
324
324
|
(rdbg:remote)
|
325
325
|
```
|
326
326
|
|
327
|
-
If there
|
327
|
+
If there are no other opening ports on the default directory, `rdbg --attach` command chooses the only one opening UNIX domain socket and connects to it. If there are more files, you need to specify the file.
|
328
328
|
|
329
|
-
When `rdbg --attach` connects to the debuggee, you can use any debug commands (set breakpoints, continue the program and so on) like local debug console. When
|
329
|
+
When `rdbg --attach` connects to the debuggee, you can use any debug commands (set breakpoints, continue the program, and so on) like the local debug console. When a debuggee program exits, the remote console will also terminate.
|
330
330
|
|
331
|
-
NOTE: If you use `quit` command, only remote console exits and the debuggee program continues to run (and you can connect it again). If you want to exit the debuggee program, use `kill` command.
|
331
|
+
NOTE: If you use the `quit` command, only the remote console exits and the debuggee program continues to run (and you can connect it again). If you want to exit the debuggee program, use `kill` command.
|
332
332
|
|
333
333
|
If you want to use TCP/IP for the remote debugging, you need to specify the port and host with `--port` like `rdbg --open --port 12345` and it binds to `localhost:12345`.
|
334
334
|
|
@@ -343,11 +343,11 @@ Note that all messages communicated between the debugger and the debuggee are *N
|
|
343
343
|
|
344
344
|
#### `require 'debug/open'` in a program
|
345
345
|
|
346
|
-
If you can modify the program, you can open debugging port by adding `require 'debug/open'` line in the program.
|
346
|
+
If you can modify the program, you can open the debugging port by adding `require 'debug/open'` line in the program.
|
347
347
|
|
348
348
|
If you don't want to stop the program at the beginning, you can also use `require 'debug/open_nonstop'`.
|
349
349
|
Using `debug/open_nonstop` is useful if you want to open a backdoor to the application.
|
350
|
-
However, it is also
|
350
|
+
However, it is also dangerous because it can become another vulnerability.
|
351
351
|
Please use it carefully.
|
352
352
|
|
353
353
|
By default, UNIX domain socket is used for the debugging port. To use TCP/IP, you can set the `RUBY_DEBUG_PORT` environment variable.
|
@@ -372,7 +372,7 @@ Also `open` command allows opening the debug port.
|
|
372
372
|
|
373
373
|
([vscode-rdbg v0.0.9](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) or later is required)
|
374
374
|
|
375
|
-
If you don't run a debuggee Ruby process on VSCode, you can attach
|
375
|
+
If you don't run a debuggee Ruby process on VSCode, you can attach it to VSCode later with the following steps.
|
376
376
|
|
377
377
|
`rdbg --open=vscode` opens the debug port and tries to invoke the VSCode (`code` command).
|
378
378
|
|
@@ -425,7 +425,7 @@ If your application is running on a SSH remote host, please try:
|
|
425
425
|
|
426
426
|
```
|
427
427
|
|
428
|
-
and try to use proposed commands.
|
428
|
+
and try to use the proposed commands.
|
429
429
|
|
430
430
|
Note that you can attach with `rdbg --attach` and continue REPL debugging.
|
431
431
|
|
@@ -438,12 +438,12 @@ $ rdbg target.rb --open=chrome
|
|
438
438
|
DEBUGGER: Debugger can attach via TCP/IP (127.0.0.1:43633)
|
439
439
|
DEBUGGER: With Chrome browser, type the following URL in the address-bar:
|
440
440
|
|
441
|
-
devtools://devtools/bundled/inspector.html?ws=127.0.0.1:
|
441
|
+
devtools://devtools/bundled/inspector.html?v8only=true&panel=sources&ws=127.0.0.1:57231/b32a55cd-2eb5-4c5c-87d8-b3dfc59d80ef
|
442
442
|
|
443
443
|
DEBUGGER: wait for debugger connection...
|
444
444
|
```
|
445
445
|
|
446
|
-
Type `devtools://devtools/bundled/inspector.html?ws=127.0.0.1:
|
446
|
+
Type `devtools://devtools/bundled/inspector.html?v8only=true&panel=sources&ws=127.0.0.1:57231/b32a55cd-2eb5-4c5c-87d8-b3dfc59d80ef` in the address bar on Chrome browser, and you can continue the debugging with chrome browser.
|
447
447
|
|
448
448
|
Also `open chrome` command works like `open vscode`.
|
449
449
|
|
@@ -456,7 +456,7 @@ When the debug session is started, initial scripts are loaded so you can put you
|
|
456
456
|
|
457
457
|
### Configuration list
|
458
458
|
|
459
|
-
You can configure debugger's behavior with environment variables and `config` command. Each configuration has environment variable and
|
459
|
+
You can configure the debugger's behavior with environment variables and `config` command. Each configuration has an environment variable and a name which can be specified by `config` command.
|
460
460
|
|
461
461
|
```
|
462
462
|
# configuration example
|
@@ -469,12 +469,15 @@ config set no_color true
|
|
469
469
|
* UI
|
470
470
|
* `RUBY_DEBUG_LOG_LEVEL` (`log_level`): Log level same as Logger (default: WARN)
|
471
471
|
* `RUBY_DEBUG_SHOW_SRC_LINES` (`show_src_lines`): Show n lines source code on breakpoint (default: 10)
|
472
|
+
* `RUBY_DEBUG_SHOW_EVALEDSRC` (`show_evaledsrc`): Show actually evaluated source (default: false)
|
472
473
|
* `RUBY_DEBUG_SHOW_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2)
|
473
474
|
* `RUBY_DEBUG_USE_SHORT_PATH` (`use_short_path`): Show shorten PATH (like $(Gem)/foo.rb) (default: false)
|
474
475
|
* `RUBY_DEBUG_NO_COLOR` (`no_color`): Do not use colorize (default: false)
|
475
476
|
* `RUBY_DEBUG_NO_SIGINT_HOOK` (`no_sigint_hook`): Do not suspend on SIGINT (default: false)
|
476
477
|
* `RUBY_DEBUG_NO_RELINE` (`no_reline`): Do not use Reline library (default: false)
|
477
478
|
* `RUBY_DEBUG_NO_HINT` (`no_hint`): Do not show the hint on the REPL (default: false)
|
479
|
+
* `RUBY_DEBUG_NO_LINENO` (`no_lineno`): Do not show line numbers (default: false)
|
480
|
+
* `RUBY_DEBUG_IRB_CONSOLE` (`irb_console`): Use IRB as the console (default: false)
|
478
481
|
|
479
482
|
* CONTROL
|
480
483
|
* `RUBY_DEBUG_SKIP_PATH` (`skip_path`): Skip showing/entering frames for given paths
|
@@ -488,12 +491,13 @@ config set no_color true
|
|
488
491
|
* `RUBY_DEBUG_NONSTOP` (`nonstop`): Nonstop mode (default: false)
|
489
492
|
* `RUBY_DEBUG_STOP_AT_LOAD` (`stop_at_load`): Stop at just loading location (default: false)
|
490
493
|
* `RUBY_DEBUG_INIT_SCRIPT` (`init_script`): debug command script path loaded at first stop
|
491
|
-
* `RUBY_DEBUG_COMMANDS` (`commands`): debug commands invoked at first stop.
|
494
|
+
* `RUBY_DEBUG_COMMANDS` (`commands`): debug commands invoked at first stop. Commands should be separated by `;;`
|
492
495
|
* `RUBY_DEBUG_NO_RC` (`no_rc`): ignore loading ~/.rdbgrc(.rb) (default: false)
|
493
496
|
* `RUBY_DEBUG_HISTORY_FILE` (`history_file`): history file (default: ~/.rdbg_history)
|
494
497
|
* `RUBY_DEBUG_SAVE_HISTORY` (`save_history`): maximum save history lines (default: 10000)
|
495
498
|
|
496
499
|
* REMOTE
|
500
|
+
* `RUBY_DEBUG_OPEN` (`open`): Open remote port (same as `rdbg --open` option)
|
497
501
|
* `RUBY_DEBUG_PORT` (`port`): TCP/IP remote debugging: port
|
498
502
|
* `RUBY_DEBUG_HOST` (`host`): TCP/IP remote debugging: host (default: 127.0.0.1)
|
499
503
|
* `RUBY_DEBUG_SOCK_PATH` (`sock_path`): UNIX Domain Socket remote debugging: socket path
|
@@ -501,7 +505,7 @@ config set no_color true
|
|
501
505
|
* `RUBY_DEBUG_LOCAL_FS_MAP` (`local_fs_map`): Specify local fs map
|
502
506
|
* `RUBY_DEBUG_SKIP_BP` (`skip_bp`): Skip breakpoints if no clients are attached (default: false)
|
503
507
|
* `RUBY_DEBUG_COOKIE` (`cookie`): Cookie for negotiation
|
504
|
-
* `
|
508
|
+
* `RUBY_DEBUG_SESSION_NAME` (`session_name`): Session name for differentiating multiple sessions
|
505
509
|
* `RUBY_DEBUG_CHROME_PATH` (`chrome_path`): Platform dependent path of Chrome (For more information, See [here](https://github.com/ruby/debug/pull/334/files#diff-5fc3d0a901379a95bc111b86cf0090b03f857edfd0b99a0c1537e26735698453R55-R64))
|
506
510
|
|
507
511
|
* OBSOLETE
|
@@ -511,7 +515,7 @@ There are other environment variables:
|
|
511
515
|
|
512
516
|
* `NO_COLOR`: If the value is set, set `RUBY_DEBUG_NO_COLOR` ([NO_COLOR: disabling ANSI color output in various Unix commands](https://no-color.org/)).
|
513
517
|
* `RUBY_DEBUG_ENABLE`: If the value is `0`, do not enable debug.gem feature.
|
514
|
-
* `RUBY_DEBUG_ADDED_RUBYOPT`: Remove this value from `RUBYOPT` at first. This feature helps loading debug.gem with `RUBYOPT='-r debug/...'
|
518
|
+
* `RUBY_DEBUG_ADDED_RUBYOPT`: Remove this value from `RUBYOPT` at first. This feature helps loading debug.gem with `RUBYOPT='-r debug/...'`, and you don't want to derive it to child processes. In this case, you can set `RUBY_DEBUG_ADDED_RUBYOPT='-r debug/...'` (same value), and this string will be deleted from `RUBYOPT` at first.
|
515
519
|
* `RUBY_DEBUG_EDITOR` or `EDITOR`: An editor used by `edit` debug command.
|
516
520
|
* `RUBY_DEBUG_BB`: Define `Kernel#bb` method which is alias of `Kernel#debugger`.
|
517
521
|
|
@@ -523,7 +527,7 @@ If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains
|
|
523
527
|
* You can specify the initial script with `rdbg -x initial_script` (like gdb's `-x` option).
|
524
528
|
|
525
529
|
Initial scripts are useful to write your favorite configurations.
|
526
|
-
For example, you can set
|
530
|
+
For example, you can set breakpoints with `break file:123` in `~/.rdbgrc`.
|
527
531
|
|
528
532
|
If there are `~/.rdbgrc.rb` is available, it is also loaded as a ruby script at same timing.
|
529
533
|
|
@@ -533,15 +537,16 @@ On the debug console, you can use the following debug commands.
|
|
533
537
|
|
534
538
|
There are additional features:
|
535
539
|
|
536
|
-
* `<expr>` without debug command is almost same as `pp <expr>`.
|
537
|
-
* If the input line `<expr>` does *NOT* start with any debug command, the line `<expr>` will be evaluated as a Ruby expression and the result will be printed with `pp` method. So that the input `foo.bar` is same as `pp foo.bar`.
|
538
|
-
* If `<expr>` is recognized as a debug command, of course it is not evaluated as a Ruby expression
|
539
|
-
* `
|
540
|
+
* `<expr>` without debug command is almost the same as `pp <expr>`.
|
541
|
+
* If the input line `<expr>` does *NOT* start with any debug command, the line `<expr>` will be evaluated as a Ruby expression, and the result will be printed with `pp` method. So that the input `foo.bar` is the same as `pp foo.bar`.
|
542
|
+
* If `<expr>` is recognized as a debug command, of course, it is not evaluated as a Ruby expression but is executed as debug command. For example, you can not evaluate such single-letter local variables `i`, `b`, `n`, `c` because they are single-letter debug commands. Use `p i` instead.
|
543
|
+
* So the author (Koichi Sasada) recommends using `p`, `pp` or `eval` command to evaluate the Ruby expression every time.
|
544
|
+
* `Enter` without any input repeats the last command (useful when repeating `step`s) for some commands.
|
540
545
|
* `Ctrl-D` is equal to `quit` command.
|
541
546
|
* [debug command compare sheet - Google Sheets](https://docs.google.com/spreadsheets/d/1TlmmUDsvwK4sSIyoMv-io52BUUz__R5wpu-ComXlsw0/edit?usp=sharing)
|
542
547
|
|
543
548
|
You can use the following debug commands. Each command should be written in 1 line.
|
544
|
-
The `[...]` notation means this part can be
|
549
|
+
The `[...]` notation means this part can be eliminated. For example, `s[tep]` means `s` or `step` is a valid command. `ste` is not valid.
|
545
550
|
The `<...>` notation means the argument.
|
546
551
|
|
547
552
|
### Control flow
|
@@ -558,7 +563,14 @@ The `<...>` notation means the argument.
|
|
558
563
|
* Finish this frame. Resume the program until the current frame is finished.
|
559
564
|
* `fin[ish] <n>`
|
560
565
|
* Finish `<n>`th frames.
|
561
|
-
* `
|
566
|
+
* `u[ntil]`
|
567
|
+
* Similar to `next` command, but only stop later lines or the end of the current frame.
|
568
|
+
* Similar to gdb's `advance` command.
|
569
|
+
* `u[ntil] <[file:]line>`
|
570
|
+
* Run til the program reaches given location or the end of the current frame.
|
571
|
+
* `u[ntil] <name>`
|
572
|
+
* Run til the program invokes a method `<name>`. `<name>` can be a regexp with `/name/`.
|
573
|
+
* `c` or `cont` or `continue`
|
562
574
|
* Resume the program.
|
563
575
|
* `q[uit]` or `Ctrl-D`
|
564
576
|
* Finish debugger (with the debuggee process on non-remote debugging).
|
@@ -638,26 +650,35 @@ The `<...>` notation means the argument.
|
|
638
650
|
* Show predecessor lines as opposed to the `list` command.
|
639
651
|
* `l[ist] <start>` or `l[ist] <start>-<end>`
|
640
652
|
* Show current frame's source code from the line <start> to <end> if given.
|
653
|
+
* `whereami`
|
654
|
+
* Show the current frame with source code.
|
641
655
|
* `edit`
|
642
656
|
* Open the current file on the editor (use `EDITOR` environment variable).
|
643
657
|
* Note that edited file will not be reloaded.
|
644
658
|
* `edit <file>`
|
645
659
|
* Open <file> on the editor.
|
646
660
|
* `i[nfo]`
|
647
|
-
|
648
|
-
* `i[nfo]
|
661
|
+
* Show information about current frame (local/instance variables and defined constants).
|
662
|
+
* `i[nfo]` <subcommand>
|
663
|
+
* `info` has the following sub-commands.
|
664
|
+
* Sub-commands can be specified with few letters which is unambiguous, like `l` for 'locals'.
|
665
|
+
* `i[nfo] l or locals or local_variables`
|
649
666
|
* Show information about the current frame (local variables)
|
650
|
-
* It includes `self` as `%self` and a return value as
|
651
|
-
* `i[nfo] i
|
667
|
+
* It includes `self` as `%self` and a return value as `_return`.
|
668
|
+
* `i[nfo] i or ivars or instance_variables`
|
652
669
|
* Show information about instance variables about `self`.
|
653
|
-
* `
|
670
|
+
* `info ivars <expr>` shows the instance variables of the result of `<expr>`.
|
671
|
+
* `i[nfo] c or consts or constants`
|
654
672
|
* Show information about accessible constants except toplevel constants.
|
655
|
-
* `
|
673
|
+
* `info consts <expr>` shows the constants of a class/module of the result of `<expr>`
|
674
|
+
* `i[nfo] g or globals or global_variables`
|
656
675
|
* Show information about global variables
|
676
|
+
* `i[nfo] th or threads`
|
677
|
+
* Show all threads (same as `th[read]`).
|
678
|
+
* `i[nfo] b or breakpoints or w or watchpoints`
|
679
|
+
* Show all breakpoints and watchpoints.
|
657
680
|
* `i[nfo] ... /regexp/`
|
658
681
|
* Filter the output with `/regexp/`.
|
659
|
-
* `i[nfo] th[read[s]]`
|
660
|
-
* Show all threads (same as `th[read]`).
|
661
682
|
* `o[utline]` or `ls`
|
662
683
|
* Show you available methods, constants, local variables, and instance variables in the current scope.
|
663
684
|
* `o[utline] <expr>` or `ls <expr>`
|
@@ -795,7 +816,7 @@ Emacs support available.
|
|
795
816
|
|
796
817
|
#### Start by method
|
797
818
|
|
798
|
-
After loading `debug/session`, you can start debug session with the following methods. They are convenient if you want to specify debug configurations in your program.
|
819
|
+
After loading `debug/session`, you can start a debug session with the following methods. They are convenient if you want to specify debug configurations in your program.
|
799
820
|
|
800
821
|
* `DEBUGGER__.start(**kw)`: start debug session with local console.
|
801
822
|
* `DEBUGGER__.open(**kw)`: open debug port with configuration (without configurations open with UNIX domain socket)
|
@@ -814,21 +835,21 @@ DEBUGGER__.start(no_color: true, # disable colorize
|
|
814
835
|
|
815
836
|
### `binding.break` method
|
816
837
|
|
817
|
-
`binding.break` (or `binding.b`) set breakpoints at written line. It also has several keywords.
|
838
|
+
`binding.break` (or `binding.b`) set breakpoints at the written line. It also has several keywords.
|
818
839
|
|
819
|
-
If `do: 'command'` is specified, the debugger suspends the program
|
840
|
+
If `do: 'command'` is specified, the debugger suspends the program, runs the `command` as a debug command, and continues the program.
|
820
841
|
It is useful if you only want to call a debug command and don't want to stop there.
|
821
842
|
|
822
843
|
```
|
823
844
|
def initialize
|
824
845
|
@a = 1
|
825
|
-
binding.b do: 'watch @a'
|
846
|
+
binding.b do: 'info \n watch @a'
|
826
847
|
end
|
827
848
|
```
|
828
849
|
|
829
|
-
|
850
|
+
In this case, execute the `info` command then register a watch breakpoint for `@a` and continue to run. You can also use `;;` instead of `\n` to separate your commands.
|
830
851
|
|
831
|
-
If `pre: 'command'` is specified, the debugger suspends the program and
|
852
|
+
If `pre: 'command'` is specified, the debugger suspends the program and runs the `command` as a debug command, and keeps suspended.
|
832
853
|
It is useful if you have operations before suspend.
|
833
854
|
|
834
855
|
```
|
@@ -838,7 +859,7 @@ def foo
|
|
838
859
|
end
|
839
860
|
```
|
840
861
|
|
841
|
-
|
862
|
+
In this case, you can see the result of `bar()` every time you stop there.
|
842
863
|
|
843
864
|
## rdbg command help
|
844
865
|
|
@@ -864,6 +885,7 @@ Debug console mode:
|
|
864
885
|
--port=PORT Listening TCP/IP port
|
865
886
|
--host=HOST Listening TCP/IP host
|
866
887
|
--cookie=COOKIE Set a cookie for connection
|
888
|
+
--session-name=NAME Session name
|
867
889
|
|
868
890
|
Debug console mode runs Ruby program with the debug console.
|
869
891
|
|
@@ -890,6 +912,8 @@ Attach mode:
|
|
890
912
|
'rdbg -A host port' tries to connect to host:port via TCP/IP.
|
891
913
|
|
892
914
|
Other options:
|
915
|
+
-v Show version number
|
916
|
+
--version Show version number and exit
|
893
917
|
-h, --help Print help
|
894
918
|
--util=NAME Utility mode (used by tools)
|
895
919
|
--stop-at-load Stop immediately when the debugging feature is loaded.
|
@@ -900,6 +924,11 @@ NOTE
|
|
900
924
|
|
901
925
|
```
|
902
926
|
|
927
|
+
# Additional Resources
|
928
|
+
|
929
|
+
- [From byebug to ruby/debug](https://st0012.dev/from-byebug-to-ruby-debug) by Stan Lo - A migration guide for `byebug` users.
|
930
|
+
- [ruby/debug cheatsheet](https://st0012.dev/ruby-debug-cheatsheet) by Stan Lo
|
931
|
+
|
903
932
|
# Contributing
|
904
933
|
|
905
934
|
Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/debug.
|
data/Rakefile
CHANGED
@@ -35,9 +35,14 @@ task :check_readme do
|
|
35
35
|
end
|
36
36
|
end
|
37
37
|
|
38
|
+
desc "Run debug.gem test-framework tests"
|
39
|
+
Rake::TestTask.new(:test_test) do |t|
|
40
|
+
t.test_files = FileList["test/support/*_test.rb"]
|
41
|
+
end
|
42
|
+
|
38
43
|
desc "Run all debugger console related tests"
|
39
44
|
Rake::TestTask.new(:test_console) do |t|
|
40
|
-
t.test_files = FileList["test/console/*_test.rb"
|
45
|
+
t.test_files = FileList["test/console/*_test.rb"]
|
41
46
|
end
|
42
47
|
|
43
48
|
desc "Run all debugger protocols (CAP & DAP) related tests"
|
@@ -46,7 +51,7 @@ Rake::TestTask.new(:test_protocol) do |t|
|
|
46
51
|
end
|
47
52
|
|
48
53
|
task test: 'test_console' do
|
49
|
-
warn '`rake test` doesn\'t run protocol tests. Use `rake
|
54
|
+
warn '`rake test` doesn\'t run protocol tests. Use `rake test_all` to test all.'
|
50
55
|
end
|
51
56
|
|
52
|
-
task test_all: [:test_console, :test_protocol]
|
57
|
+
task test_all: [:test_test, :test_console, :test_protocol]
|
data/TODO.md
CHANGED
@@ -2,22 +2,22 @@
|
|
2
2
|
|
3
3
|
## Basic functionality
|
4
4
|
|
5
|
-
* Support Ractors
|
6
|
-
* Signal (SIGINT) trap handling
|
5
|
+
* Support Fibers and Ractors
|
7
6
|
|
8
7
|
## UI
|
9
8
|
|
9
|
+
* Multi-line support
|
10
10
|
* Completion for Ruby's code
|
11
11
|
* Interactive breakpoint setting
|
12
12
|
* Interactive record & play debugging
|
13
13
|
* irb integration
|
14
|
-
* Web browser integrated UI
|
15
|
-
* History file
|
16
14
|
|
17
15
|
## Debug command
|
18
16
|
|
19
|
-
* Breakpoints
|
20
|
-
* Lightweight pending method break points with Ruby 3.1 feature (TP:method_added)
|
21
17
|
* Watch points
|
22
|
-
* Lightweight watchpoints for instance variables with Ruby 3.
|
23
|
-
*
|
18
|
+
* Lightweight watchpoints for instance variables with Ruby 3.3 features (TP:ivar_set)
|
19
|
+
* Alias
|
20
|
+
|
21
|
+
## Debug port
|
22
|
+
|
23
|
+
* Debug port for monitoring
|
data/debug.gemspec
CHANGED
@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
|
|
10
10
|
spec.description = %q{Debugging functionality for Ruby. This is completely rewritten debug.rb which was contained by the ancient Ruby versions.}
|
11
11
|
spec.homepage = "https://github.com/ruby/debug"
|
12
12
|
spec.licenses = ["Ruby", "BSD-2-Clause"]
|
13
|
-
spec.required_ruby_version = Gem::Requirement.new(">= 2.
|
13
|
+
spec.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
|
14
14
|
|
15
15
|
spec.metadata["homepage_uri"] = spec.homepage
|
16
16
|
spec.metadata["source_code_uri"] = spec.homepage
|
@@ -27,6 +27,6 @@ Gem::Specification.new do |spec|
|
|
27
27
|
spec.require_paths = ["lib"]
|
28
28
|
spec.extensions = ['ext/debug/extconf.rb']
|
29
29
|
|
30
|
-
spec.add_dependency "irb", "
|
31
|
-
spec.add_dependency "reline", ">= 0.3.
|
30
|
+
spec.add_dependency "irb", "~> 1.10" # for irb:debug integration
|
31
|
+
spec.add_dependency "reline", ">= 0.3.8"
|
32
32
|
end
|
data/exe/rdbg
CHANGED
@@ -10,13 +10,28 @@ when :start
|
|
10
10
|
require 'rbconfig'
|
11
11
|
|
12
12
|
libpath = File.join(File.expand_path(File.dirname(__dir__)), 'lib/debug')
|
13
|
-
start_mode = config[:
|
13
|
+
start_mode = config[:open] ? "open" : 'start'
|
14
14
|
cmd = config[:command] ? ARGV.shift : (ENV['RUBY'] || RbConfig.ruby)
|
15
15
|
|
16
|
+
if defined?($:.resolve_feature_path)
|
17
|
+
begin
|
18
|
+
_, sopath = $:.resolve_feature_path('debug/debug.so')
|
19
|
+
rescue LoadError
|
20
|
+
# raises LoadError before 3.1 (2.7 and 3.0)
|
21
|
+
else
|
22
|
+
sopath = File.dirname(File.dirname(sopath)) if sopath
|
23
|
+
end
|
24
|
+
else
|
25
|
+
# `$:.resolve_feature_path` is not defined in 2.6 or earlier.
|
26
|
+
so = "debug/debug.#{RbConfig::CONFIG['DLEXT']}"
|
27
|
+
sopath = $:.find {|dir| File.exist?(File.join(dir, so))}
|
28
|
+
end
|
29
|
+
added = "-r #{libpath}/#{start_mode}"
|
30
|
+
added = "-I #{sopath} #{added}" if sopath
|
31
|
+
rubyopt = ENV['RUBYOPT']
|
16
32
|
env = ::DEBUGGER__::Config.config_to_env_hash(config)
|
17
|
-
|
18
|
-
env['
|
19
|
-
env['RUBYOPT'] = "#{added} #{rubyopt}"
|
33
|
+
env['RUBY_DEBUG_ADDED_RUBYOPT'] = added
|
34
|
+
env['RUBYOPT'] = "#{rubyopt} #{added}"
|
20
35
|
|
21
36
|
exec(env, cmd, *ARGV)
|
22
37
|
|