debug 1.6.1 → 1.9.1
Sign up to get free protection for your applications and to get access to all the features.
- 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
|
|