debug 1.4.0 → 1.9.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (47) hide show
  1. checksums.yaml +4 -4
  2. data/CONTRIBUTING.md +210 -6
  3. data/Gemfile +2 -0
  4. data/LICENSE.txt +0 -0
  5. data/README.md +161 -85
  6. data/Rakefile +33 -10
  7. data/TODO.md +8 -8
  8. data/debug.gemspec +9 -7
  9. data/exe/rdbg +23 -4
  10. data/ext/debug/debug.c +111 -21
  11. data/ext/debug/extconf.rb +23 -0
  12. data/ext/debug/iseq_collector.c +2 -0
  13. data/lib/debug/abbrev_command.rb +77 -0
  14. data/lib/debug/breakpoint.rb +102 -74
  15. data/lib/debug/client.rb +46 -12
  16. data/lib/debug/color.rb +0 -0
  17. data/lib/debug/config.rb +129 -36
  18. data/lib/debug/console.rb +46 -40
  19. data/lib/debug/dap_custom/traceInspector.rb +336 -0
  20. data/lib/debug/frame_info.rb +40 -25
  21. data/lib/debug/irb_integration.rb +37 -0
  22. data/lib/debug/local.rb +17 -11
  23. data/lib/debug/open.rb +0 -0
  24. data/lib/debug/open_nonstop.rb +0 -0
  25. data/lib/debug/prelude.rb +3 -2
  26. data/lib/debug/server.rb +126 -56
  27. data/lib/debug/server_cdp.rb +673 -248
  28. data/lib/debug/server_dap.rb +497 -261
  29. data/lib/debug/session.rb +899 -441
  30. data/lib/debug/source_repository.rb +122 -49
  31. data/lib/debug/start.rb +1 -1
  32. data/lib/debug/thread_client.rb +460 -155
  33. data/lib/debug/tracer.rb +10 -16
  34. data/lib/debug/version.rb +1 -1
  35. data/lib/debug.rb +7 -2
  36. data/misc/README.md.erb +106 -56
  37. metadata +14 -24
  38. data/.github/ISSUE_TEMPLATE/bug_report.md +0 -24
  39. data/.github/ISSUE_TEMPLATE/custom.md +0 -10
  40. data/.github/ISSUE_TEMPLATE/feature_request.md +0 -14
  41. data/.github/pull_request_template.md +0 -9
  42. data/.github/workflows/ruby.yml +0 -34
  43. data/.gitignore +0 -12
  44. data/bin/console +0 -14
  45. data/bin/gentest +0 -30
  46. data/bin/setup +0 -8
  47. data/lib/debug/bp.vim +0 -68
data/README.md CHANGED
@@ -1,20 +1,24 @@
1
- [![Ruby](https://github.com/ruby/debug/actions/workflows/ruby.yml/badge.svg?branch=master)](https://github.com/ruby/debug/actions/workflows/ruby.yml?query=branch%3Amaster)
1
+ [![Ruby](https://github.com/ruby/debug/actions/workflows/ruby.yml/badge.svg?branch=master)](https://github.com/ruby/debug/actions/workflows/ruby.yml?query=branch%3Amaster) [![Protocol](https://github.com/ruby/debug/actions/workflows/protocol.yml/badge.svg)](https://github.com/ruby/debug/actions/workflows/protocol.yml)
2
2
 
3
3
  # debug.rb
4
4
 
5
- This library provides debugging functionality to Ruby.
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.
11
11
  * [Remote debugging](#remote-debugging): Support remote debugging natively.
12
- * UNIX domain socket
12
+ * UNIX domain socket (UDS)
13
13
  * TCP/IP
14
- * Integration with rich debugger frontend
15
- * VSCode/DAP ([VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg))
16
- * Chrome DevTools
17
- * Extensible: application can introduce debugging support with several ways:
14
+ * Integration with rich debugger frontends
15
+
16
+ | Frontend | [Console](https://github.com/ruby/debug#invoke-as-a-remote-debuggee) | [VSCode](https://github.com/ruby/debug#vscode-integration) | [Chrome DevTool](#chrome-devtool-integration) |
17
+ | ----------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------- |
18
+ | Connection | UDS, TCP/IP | UDS, TCP/IP | TCP/IP |
19
+ | Requirement | No | [vscode-rdbg](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) | Chrome |
20
+
21
+ * Extensible: application can introduce debugging support in several ways:
18
22
  * By `rdbg` command
19
23
  * By loading libraries with `-r` command line option
20
24
  * By calling Ruby's method explicitly
@@ -22,7 +26,7 @@ New debug.rb has several advantages:
22
26
  * Support threads (almost done) and ractors (TODO).
23
27
  * Support suspending and entering to the console debugging with `Ctrl-C` at most of timing.
24
28
  * Show parameters on backtrace command.
25
- * Support recording & reply debugging.
29
+ * Support recording & replay debugging.
26
30
 
27
31
  # Installation
28
32
 
@@ -38,6 +42,9 @@ If you use Bundler, write the following line to your Gemfile.
38
42
  gem "debug", ">= 1.0.0"
39
43
  ```
40
44
 
45
+ (The version constraint is important; `debug < 1.0.0` is an older,
46
+ abandoned gem that is completely different from this product.)
47
+
41
48
  # HOW TO USE
42
49
 
43
50
  To use a debugger, roughly you will do the following steps:
@@ -48,7 +55,7 @@ To use a debugger, roughly you will do the following steps:
48
55
  4. Use debug commands.
49
56
  * [Evaluate Ruby expressions](#evaluate) (e.g. `p lvar` to see the local variable `lvar`).
50
57
  * [Query the program status](#information) (e.g. `info` to see information about the current frame).
51
- * [Control program flow](#control-flow) (e.g. move to the another line with `step`, to the next line with `next`).
58
+ * [Control program flow](#control-flow) (e.g. move to another line with `step`, to the next line with `next`).
52
59
  * [Set another breakpoint](#breakpoint) (e.g. `catch Exception` to set a breakpoint that'll be triggered when `Exception` is raised).
53
60
  * [Activate tracing in your program](#trace) (e.g. `trace call` to trace method calls).
54
61
  * [Change the configuration](#configuration-1) (e.g. `config set no_color true` to disable coloring).
@@ -113,7 +120,7 @@ d => nil
113
120
  5| binding.break
114
121
  6| c = 3
115
122
  7| d = 4
116
- => 8| binding.break # Again the program stops at here
123
+ => 8| binding.break # Again the program stops here
117
124
  9| p [a, b, c, d]
118
125
  10|
119
126
  11| __END__
@@ -134,7 +141,7 @@ d => 4
134
141
  ### Invoke the program from the debugger as a traditional debuggers
135
142
 
136
143
  If you don't want to modify the source code, you can set breakpoints with a debug command `break` (`b` for short).
137
- Using `rdbg` command to launch the program without any modifications, you can run the program with the debugger.
144
+ Using `rdbg` command (or `bundle exec rdbg`) to launch the program without any modifications, you can run the program with the debugger.
138
145
 
139
146
  ```shell
140
147
  $ cat target.rb # Sample program
@@ -173,7 +180,7 @@ DEBUGGER: Session start (pid: 7656)
173
180
  #1 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
174
181
  ```
175
182
 
176
- 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.
177
184
 
178
185
  ```shell
179
186
  (rdbg) continue
@@ -193,8 +200,8 @@ Stop by #0 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
193
200
  ```
194
201
 
195
202
  You can see that we can stop at line 3.
196
- Let's see the local variables with `info` command, and continue.
197
- 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.
198
205
 
199
206
  ```shell
200
207
  (rdbg) info
@@ -231,14 +238,14 @@ d => 4
231
238
  ```
232
239
 
233
240
  By the way, using `rdbg` command you can suspend your application with `C-c` (SIGINT) and enter the debug console.
234
- It will help that if you want to know what the program is doing.
241
+ It will help if you want to know what the program is doing.
235
242
 
236
243
  ### Use `rdbg` with commands written in Ruby
237
244
 
238
- If you want to run a command written in Ruby like like `rake`, `rails`, `bundle`, `rspec` and so on, you can use `rdbg -c` option.
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.
239
246
 
240
247
  * Without `-c` option, `rdbg <name>` means that `<name>` is Ruby script and invoke it like `ruby <name>` with the debugger.
241
- * With `-c` option, `rdbg -c <name>` means that `<name>` is command in `PATH` and simply invoke it with the debugger.
248
+ * With `-c` option, `rdbg -c <name>` means that `<name>` is a command in `PATH` and simply invokes it with the debugger.
242
249
 
243
250
  Examples:
244
251
  * `rdbg -c -- rails server`
@@ -256,31 +263,36 @@ Like other languages, you can use this debugger on the VSCode.
256
263
 
257
264
  1. Install [VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg)
258
265
  2. Open `.rb` file (e.g. `target.rb`)
259
- 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)
260
267
  4. Choose "Start debugging" in "Run" menu (or type F5 key)
261
- 5. You will see a dialog "Debug command line" and you can choose your favorite command line your want to run.
262
- 6. Chosen command line is invoked with `rdbg -c` and VSCode shows the details at breakpoints.
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.
263
270
 
264
- 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.
265
272
 
266
273
  You can configure the extension in `.vscode/launch.json`.
267
274
  Please see the extension page for more details.
268
275
 
269
276
  ## Remote debugging
270
277
 
271
- 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:
272
279
 
273
- * Your application does not run on TTY and it is hard to use `binding.pry` or `binding.irb`.
274
- * 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.
275
282
  * Your application is running as a daemon.
276
283
  * Your application uses pipe for STDIN or STDOUT.
277
284
  * Your application is running as a daemon and you want to query the running status (checking a backtrace and so on).
278
285
 
279
- 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.
280
287
 
281
288
  ### Invoke as a remote debuggee
282
289
 
283
- There are two ways to invoke a script as remote debuggee: Use `rdbg --open` and require `debug/open` (or `debug/open_nonstop`).
290
+ There are multiple ways to run your program as a debuggee:
291
+
292
+ | Stop at program start | [`rdbg` option](https://github.com/ruby/debug#rdbg---open-or-rdbg--o-for-short) | [require](https://github.com/ruby/debug#require-debugopen-in-a-program) | [debugger API](https://github.com/ruby/debug#start-by-method) |
293
+ | --------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
294
+ | Yes | `rdbg --open` | `require "debug/open"` | `DEBUGGER__.open` |
295
+ | No | `rdbg --open --nonstop` | `require "debug/open_nonstop"` | `DEBUGGER__.open(nonstop: true)` |
284
296
 
285
297
  #### `rdbg --open` (or `rdbg -O` for short)
286
298
 
@@ -293,7 +305,7 @@ DEBUGGER: Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock
293
305
  DEBUGGER: wait for debugger connection...
294
306
  ```
295
307
 
296
- 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).
297
309
 
298
310
  You can connect to the debuggee with `rdbg --attach` command (`rdbg -A` for short).
299
311
 
@@ -312,11 +324,11 @@ $ rdbg -A
312
324
  (rdbg:remote)
313
325
  ```
314
326
 
315
- If there is no other opening ports on the default directory, `rdbg --attach` command chooses the only one opening UNIX domain socket and connect to it. If there are more files, you need to specify the file.
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.
316
328
 
317
- 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 an debuggee program exits, the remote console will also terminate.
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.
318
330
 
319
- 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.
320
332
 
321
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`.
322
334
 
@@ -331,11 +343,11 @@ Note that all messages communicated between the debugger and the debuggee are *N
331
343
 
332
344
  #### `require 'debug/open'` in a program
333
345
 
334
- 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.
335
347
 
336
348
  If you don't want to stop the program at the beginning, you can also use `require 'debug/open_nonstop'`.
337
349
  Using `debug/open_nonstop` is useful if you want to open a backdoor to the application.
338
- However, it is also danger because it can become another vulnerability.
350
+ However, it is also dangerous because it can become another vulnerability.
339
351
  Please use it carefully.
340
352
 
341
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.
@@ -358,7 +370,9 @@ Also `open` command allows opening the debug port.
358
370
 
359
371
  #### VSCode integration
360
372
 
361
- If you don't run a debuggee Ruby process on VSCode, you can attach with VSCode later with the following steps.
373
+ ([vscode-rdbg v0.0.9](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) or later is required)
374
+
375
+ If you don't run a debuggee Ruby process on VSCode, you can attach it to VSCode later with the following steps.
362
376
 
363
377
  `rdbg --open=vscode` opens the debug port and tries to invoke the VSCode (`code` command).
364
378
 
@@ -411,32 +425,30 @@ If your application is running on a SSH remote host, please try:
411
425
 
412
426
  ```
413
427
 
414
- and try to use proposed commands.
428
+ and try to use the proposed commands.
415
429
 
416
430
  Note that you can attach with `rdbg --attach` and continue REPL debugging.
417
431
 
418
432
  #### Chrome DevTool integration
419
433
 
420
- With `rdbg --open=chrome` command will shows the following message.
434
+ With `rdbg --open=chrome` command will show the following message.
421
435
 
422
436
  ```
423
437
  $ rdbg target.rb --open=chrome
424
438
  DEBUGGER: Debugger can attach via TCP/IP (127.0.0.1:43633)
425
439
  DEBUGGER: With Chrome browser, type the following URL in the address-bar:
426
440
 
427
- devtools://devtools/bundled/inspector.html?ws=127.0.0.1:43633
441
+ devtools://devtools/bundled/inspector.html?v8only=true&panel=sources&ws=127.0.0.1:57231/b32a55cd-2eb5-4c5c-87d8-b3dfc59d80ef
428
442
 
429
443
  DEBUGGER: wait for debugger connection...
430
444
  ```
431
445
 
432
- 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.
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.
433
447
 
434
448
  Also `open chrome` command works like `open vscode`.
435
449
 
436
450
  For more information about how to use Chrome debugging, you might want to read [here](https://developer.chrome.com/docs/devtools/).
437
451
 
438
- Note: If you want to maximize Chrome DevTools, click [Toggle Device Toolbar](https://developer.chrome.com/docs/devtools/device-mode/#viewport).
439
-
440
452
  ## Configuration
441
453
 
442
454
  You can configure the debugger's behavior with debug commands and environment variables.
@@ -444,7 +456,7 @@ When the debug session is started, initial scripts are loaded so you can put you
444
456
 
445
457
  ### Configuration list
446
458
 
447
- You can configure debugger's behavior with environment variables and `config` command. Each configuration has environment variable and the name which can be specified by `config` command.
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.
448
460
 
449
461
  ```
450
462
  # configuration example
@@ -456,42 +468,57 @@ config set no_color true
456
468
 
457
469
  * UI
458
470
  * `RUBY_DEBUG_LOG_LEVEL` (`log_level`): Log level same as Logger (default: WARN)
459
- * `RUBY_DEBUG_SHOW_SRC_LINES` (`show_src_lines`): Show n lines source code on breakpoint (default: 10 lines)
460
- * `RUBY_DEBUG_SHOW_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2 frames)
461
- * `RUBY_DEBUG_USE_SHORT_PATH` (`use_short_path`): Show shorten PATH (like $(Gem)/foo.rb)
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)
473
+ * `RUBY_DEBUG_SHOW_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2)
474
+ * `RUBY_DEBUG_USE_SHORT_PATH` (`use_short_path`): Show shorten PATH (like $(Gem)/foo.rb) (default: false)
462
475
  * `RUBY_DEBUG_NO_COLOR` (`no_color`): Do not use colorize (default: false)
463
476
  * `RUBY_DEBUG_NO_SIGINT_HOOK` (`no_sigint_hook`): Do not suspend on SIGINT (default: false)
464
477
  * `RUBY_DEBUG_NO_RELINE` (`no_reline`): Do not use Reline library (default: false)
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)
465
481
 
466
482
  * CONTROL
467
- * `RUBY_DEBUG_SKIP_PATH` (`skip_path`): Skip showing/entering frames for given paths (default: [])
483
+ * `RUBY_DEBUG_SKIP_PATH` (`skip_path`): Skip showing/entering frames for given paths
468
484
  * `RUBY_DEBUG_SKIP_NOSRC` (`skip_nosrc`): Skip on no source code lines (default: false)
469
485
  * `RUBY_DEBUG_KEEP_ALLOC_SITE` (`keep_alloc_site`): Keep allocation site and p, pp shows it (default: false)
470
486
  * `RUBY_DEBUG_POSTMORTEM` (`postmortem`): Enable postmortem debug (default: false)
471
487
  * `RUBY_DEBUG_FORK_MODE` (`fork_mode`): Control which process activates a debugger after fork (both/parent/child) (default: both)
472
- * `RUBY_DEBUG_SIGDUMP_SIG` (`sigdump_sig`): Sigdump signal (default: disabled)
488
+ * `RUBY_DEBUG_SIGDUMP_SIG` (`sigdump_sig`): Sigdump signal (default: false)
473
489
 
474
490
  * BOOT
475
- * `RUBY_DEBUG_NONSTOP` (`nonstop`): Nonstop mode
476
- * `RUBY_DEBUG_STOP_AT_LOAD` (`stop_at_load`): Stop at just loading location
491
+ * `RUBY_DEBUG_NONSTOP` (`nonstop`): Nonstop mode (default: false)
492
+ * `RUBY_DEBUG_STOP_AT_LOAD` (`stop_at_load`): Stop at just loading location (default: false)
477
493
  * `RUBY_DEBUG_INIT_SCRIPT` (`init_script`): debug command script path loaded at first stop
478
- * `RUBY_DEBUG_COMMANDS` (`commands`): debug commands invoked at first stop. commands should be separated by ';;'
479
- * `RUBY_DEBUG_NO_RC` (`no_rc`): ignore loading ~/.rdbgrc(.rb)
494
+ * `RUBY_DEBUG_COMMANDS` (`commands`): debug commands invoked at first stop. Commands should be separated by `;;`
495
+ * `RUBY_DEBUG_NO_RC` (`no_rc`): ignore loading ~/.rdbgrc(.rb) (default: false)
480
496
  * `RUBY_DEBUG_HISTORY_FILE` (`history_file`): history file (default: ~/.rdbg_history)
481
- * `RUBY_DEBUG_SAVE_HISTORY` (`save_history`): maximum save history lines (default: 10,000)
497
+ * `RUBY_DEBUG_SAVE_HISTORY` (`save_history`): maximum save history lines (default: 10000)
482
498
 
483
499
  * REMOTE
500
+ * `RUBY_DEBUG_OPEN` (`open`): Open remote port (same as `rdbg --open` option)
484
501
  * `RUBY_DEBUG_PORT` (`port`): TCP/IP remote debugging: port
485
- * `RUBY_DEBUG_HOST` (`host`): TCP/IP remote debugging: host (localhost if not given)
502
+ * `RUBY_DEBUG_HOST` (`host`): TCP/IP remote debugging: host (default: 127.0.0.1)
486
503
  * `RUBY_DEBUG_SOCK_PATH` (`sock_path`): UNIX Domain Socket remote debugging: socket path
487
504
  * `RUBY_DEBUG_SOCK_DIR` (`sock_dir`): UNIX Domain Socket remote debugging: socket directory
505
+ * `RUBY_DEBUG_LOCAL_FS_MAP` (`local_fs_map`): Specify local fs map
506
+ * `RUBY_DEBUG_SKIP_BP` (`skip_bp`): Skip breakpoints if no clients are attached (default: false)
488
507
  * `RUBY_DEBUG_COOKIE` (`cookie`): Cookie for negotiation
489
- * `RUBY_DEBUG_OPEN_FRONTEND` (`open_frontend`): frontend used by open command (vscode, chrome, default: rdbg).
508
+ * `RUBY_DEBUG_SESSION_NAME` (`session_name`): Session name for differentiating multiple sessions
490
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))
491
510
 
492
511
  * OBSOLETE
493
512
  * `RUBY_DEBUG_PARENT_ON_FORK` (`parent_on_fork`): Keep debugging parent process on fork (default: false)
494
513
 
514
+ There are other environment variables:
515
+
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/)).
517
+ * `RUBY_DEBUG_ENABLE`: If the value is `0`, do not enable debug.gem feature.
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.
519
+ * `RUBY_DEBUG_EDITOR` or `EDITOR`: An editor used by `edit` debug command.
520
+ * `RUBY_DEBUG_BB`: Define `Kernel#bb` method which is alias of `Kernel#debugger`.
521
+
495
522
  ### Initial scripts
496
523
 
497
524
  If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains debug commands) when the debug session is started.
@@ -500,7 +527,7 @@ If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains
500
527
  * You can specify the initial script with `rdbg -x initial_script` (like gdb's `-x` option).
501
528
 
502
529
  Initial scripts are useful to write your favorite configurations.
503
- For example, you can set break points with `break file:123` in `~/.rdbgrc`.
530
+ For example, you can set breakpoints with `break file:123` in `~/.rdbgrc`.
504
531
 
505
532
  If there are `~/.rdbgrc.rb` is available, it is also loaded as a ruby script at same timing.
506
533
 
@@ -510,15 +537,16 @@ On the debug console, you can use the following debug commands.
510
537
 
511
538
  There are additional features:
512
539
 
513
- * `<expr>` without debug command is almost same as `pp <expr>`.
514
- * 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`.
515
- * 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.
516
- * `Enter` without any input repeats the last command (useful when repeating `step`s).
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.
517
545
  * `Ctrl-D` is equal to `quit` command.
518
546
  * [debug command compare sheet - Google Sheets](https://docs.google.com/spreadsheets/d/1TlmmUDsvwK4sSIyoMv-io52BUUz__R5wpu-ComXlsw0/edit?usp=sharing)
519
547
 
520
548
  You can use the following debug commands. Each command should be written in 1 line.
521
- The `[...]` notation means this part can be eliminate. For example, `s[tep]` means `s` or `step` are valid command. `ste` is not valid.
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.
522
550
  The `<...>` notation means the argument.
523
551
 
524
552
  ### Control flow
@@ -535,7 +563,14 @@ The `<...>` notation means the argument.
535
563
  * Finish this frame. Resume the program until the current frame is finished.
536
564
  * `fin[ish] <n>`
537
565
  * Finish `<n>`th frames.
538
- * `c[ontinue]`
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`
539
574
  * Resume the program.
540
575
  * `q[uit]` or `Ctrl-D`
541
576
  * Finish debugger (with the debuggee process on non-remote debugging).
@@ -567,8 +602,8 @@ The `<...>` notation means the argument.
567
602
  * break and run `<command>` before stopping.
568
603
  * `b[reak] ... do: <command>`
569
604
  * break and run `<command>`, and continue.
570
- * `b[reak] ... path: <path_regexp>`
571
- * break if the triggering event's path matches <path_regexp>.
605
+ * `b[reak] ... path: <path>`
606
+ * break if the path matches to `<path>`. `<path>` can be a regexp with `/regexp/`.
572
607
  * `b[reak] if: <expr>`
573
608
  * break if: `<expr>` is true at any lines.
574
609
  * Note that this feature is super slow.
@@ -580,8 +615,8 @@ The `<...>` notation means the argument.
580
615
  * runs `<command>` before stopping.
581
616
  * `catch ... do: <command>`
582
617
  * stops and run `<command>`, and continue.
583
- * `catch ... path: <path_regexp>`
584
- * stops if the exception is raised from a path that matches <path_regexp>.
618
+ * `catch ... path: <path>`
619
+ * stops if the exception is raised from a `<path>`. `<path>` can be a regexp with `/regexp/`.
585
620
  * `watch @ivar`
586
621
  * Stop the execution when the result of current scope's `@ivar` is changed.
587
622
  * Note that this feature is super slow.
@@ -591,8 +626,8 @@ The `<...>` notation means the argument.
591
626
  * runs `<command>` before stopping.
592
627
  * `watch ... do: <command>`
593
628
  * stops and run `<command>`, and continue.
594
- * `watch ... path: <path_regexp>`
595
- * stops if the triggering event's path matches <path_regexp>.
629
+ * `watch ... path: <path>`
630
+ * stops if the path matches `<path>`. `<path>` can be a regexp with `/regexp/`.
596
631
  * `del[ete]`
597
632
  * delete all breakpoints.
598
633
  * `del[ete] <bpnum>`
@@ -615,26 +650,35 @@ The `<...>` notation means the argument.
615
650
  * Show predecessor lines as opposed to the `list` command.
616
651
  * `l[ist] <start>` or `l[ist] <start>-<end>`
617
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.
618
655
  * `edit`
619
656
  * Open the current file on the editor (use `EDITOR` environment variable).
620
657
  * Note that edited file will not be reloaded.
621
658
  * `edit <file>`
622
659
  * Open <file> on the editor.
623
660
  * `i[nfo]`
624
- * Show information about current frame (local/instance variables and defined constants).
625
- * `i[nfo] l[ocal[s]]`
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`
626
666
  * Show information about the current frame (local variables)
627
- * It includes `self` as `%self` and a return value as `%return`.
628
- * `i[nfo] i[var[s]]` or `i[nfo] instance`
667
+ * It includes `self` as `%self` and a return value as `_return`.
668
+ * `i[nfo] i or ivars or instance_variables`
629
669
  * Show information about instance variables about `self`.
630
- * `i[nfo] c[onst[s]]` or `i[nfo] constant[s]`
670
+ * `info ivars <expr>` shows the instance variables of the result of `<expr>`.
671
+ * `i[nfo] c or consts or constants`
631
672
  * Show information about accessible constants except toplevel constants.
632
- * `i[nfo] g[lobal[s]]`
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`
633
675
  * Show information about global variables
634
- * `i[nfo] ... </pattern/>`
635
- * Filter the output with `</pattern/>`.
636
- * `i[nfo] th[read[s]]`
676
+ * `i[nfo] th or threads`
637
677
  * Show all threads (same as `th[read]`).
678
+ * `i[nfo] b or breakpoints or w or watchpoints`
679
+ * Show all breakpoints and watchpoints.
680
+ * `i[nfo] ... /regexp/`
681
+ * Filter the output with `/regexp/`.
638
682
  * `o[utline]` or `ls`
639
683
  * Show you available methods, constants, local variables, and instance variables in the current scope.
640
684
  * `o[utline] <expr>` or `ls <expr>`
@@ -669,7 +713,7 @@ The `<...>` notation means the argument.
669
713
  * `eval <expr>`
670
714
  * Evaluate `<expr>` on the current frame.
671
715
  * `irb`
672
- * Invoke `irb` on the current frame.
716
+ * Activate and switch to `irb:rdbg` console
673
717
 
674
718
  ### Trace
675
719
 
@@ -683,8 +727,8 @@ The `<...>` notation means the argument.
683
727
  * Add an exception tracer. It indicates raising exceptions.
684
728
  * `trace object <expr>`
685
729
  * Add an object tracer. It indicates that an object by `<expr>` is passed as a parameter or a receiver on method call.
686
- * `trace ... </pattern/>`
687
- * Indicates only matched events to `</pattern/>` (RegExp).
730
+ * `trace ... /regexp/`
731
+ * Indicates only matched events to `/regexp/`.
688
732
  * `trace ... into: <file>`
689
733
  * Save trace information into: `<file>`.
690
734
  * `trace off <num>`
@@ -740,6 +784,30 @@ The `<...>` notation means the argument.
740
784
  * Show help for the given command.
741
785
 
742
786
 
787
+ ### Using IRB as the Debug Console
788
+
789
+ Starting from version `v1.9`, you can now use IRB as the debug console. This integration brings additional features such as:
790
+
791
+ * Autocompletion
792
+ * Support for multi-line input
793
+ * Access to commands not available in `debug`, like `show_source` or `show_doc`
794
+ * [Configurable command aliases](https://docs.ruby-lang.org/en/master/IRB.html#module-IRB-label-Command+Aliases)
795
+
796
+ To switch to the IRB console, simply use the `irb` command in the debug console.
797
+
798
+ Once activated, you'll notice the prompt changes to:
799
+
800
+ ```txt
801
+ irb:rdbg(main):001>
802
+ ```
803
+
804
+ If you want to make IRB the default console for all sessions, configure the `irb_console` setting by either:
805
+
806
+ * Setting the `RUBY_DEBUG_IRB_CONSOLE=true` environment variable
807
+ * Or adding `config set irb_console 1` to your `~/.rdbgrc`
808
+
809
+ To disable the IRB console in the current session, execute `config set irb_console 0` in the console.
810
+
743
811
  ## Debugger API
744
812
 
745
813
  ### Start debugging
@@ -772,7 +840,7 @@ Emacs support available.
772
840
 
773
841
  #### Start by method
774
842
 
775
- 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.
843
+ 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.
776
844
 
777
845
  * `DEBUGGER__.start(**kw)`: start debug session with local console.
778
846
  * `DEBUGGER__.open(**kw)`: open debug port with configuration (without configurations open with UNIX domain socket)
@@ -791,21 +859,21 @@ DEBUGGER__.start(no_color: true, # disable colorize
791
859
 
792
860
  ### `binding.break` method
793
861
 
794
- `binding.break` (or `binding.b`) set breakpoints at written line. It also has several keywords.
862
+ `binding.break` (or `binding.b`) set breakpoints at the written line. It also has several keywords.
795
863
 
796
- If `do: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command and continue the program.
864
+ If `do: 'command'` is specified, the debugger suspends the program, runs the `command` as a debug command, and continues the program.
797
865
  It is useful if you only want to call a debug command and don't want to stop there.
798
866
 
799
867
  ```
800
868
  def initialize
801
869
  @a = 1
802
- binding.b do: 'watch @a'
870
+ binding.b do: 'info \n watch @a'
803
871
  end
804
872
  ```
805
873
 
806
- On this case, register a watch breakpoint for `@a` and continue to run.
874
+ 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.
807
875
 
808
- If `pre: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command, and keep suspend.
876
+ If `pre: 'command'` is specified, the debugger suspends the program and runs the `command` as a debug command, and keeps suspended.
809
877
  It is useful if you have operations before suspend.
810
878
 
811
879
  ```
@@ -815,7 +883,7 @@ def foo
815
883
  end
816
884
  ```
817
885
 
818
- On this case, you can see the result of `bar()` every time you stop there.
886
+ In this case, you can see the result of `bar()` every time you stop there.
819
887
 
820
888
  ## rdbg command help
821
889
 
@@ -841,6 +909,7 @@ Debug console mode:
841
909
  --port=PORT Listening TCP/IP port
842
910
  --host=HOST Listening TCP/IP host
843
911
  --cookie=COOKIE Set a cookie for connection
912
+ --session-name=NAME Session name
844
913
 
845
914
  Debug console mode runs Ruby program with the debug console.
846
915
 
@@ -867,6 +936,8 @@ Attach mode:
867
936
  'rdbg -A host port' tries to connect to host:port via TCP/IP.
868
937
 
869
938
  Other options:
939
+ -v Show version number
940
+ --version Show version number and exit
870
941
  -h, --help Print help
871
942
  --util=NAME Utility mode (used by tools)
872
943
  --stop-at-load Stop immediately when the debugging feature is loaded.
@@ -877,6 +948,11 @@ NOTE
877
948
 
878
949
  ```
879
950
 
951
+ # Additional Resources
952
+
953
+ - [From byebug to ruby/debug](https://st0012.dev/from-byebug-to-ruby-debug) by Stan Lo - A migration guide for `byebug` users.
954
+ - [ruby/debug cheatsheet](https://st0012.dev/ruby-debug-cheatsheet) by Stan Lo
955
+
880
956
  # Contributing
881
957
 
882
958
  Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/debug.
data/Rakefile CHANGED
@@ -1,12 +1,6 @@
1
1
  require "bundler/gem_tasks"
2
2
  require "rake/testtask"
3
3
 
4
- Rake::TestTask.new(:test) do |t|
5
- t.libs << "test"
6
- t.libs << "lib"
7
- t.test_files = FileList["test/**/*_test.rb"]
8
- end
9
-
10
4
  begin
11
5
  require "rake/extensiontask"
12
6
  task :build => :compile
@@ -17,8 +11,7 @@ begin
17
11
  rescue LoadError
18
12
  end
19
13
 
20
-
21
- task :default => [:clobber, :compile, 'README.md', :test]
14
+ task :default => [:clobber, :compile, 'README.md', :check_readme, :test_console]
22
15
 
23
16
  file 'README.md' => ['lib/debug/session.rb', 'lib/debug/config.rb',
24
17
  'exe/rdbg', 'misc/README.md.erb'] do
@@ -28,7 +21,37 @@ file 'README.md' => ['lib/debug/session.rb', 'lib/debug/config.rb',
28
21
  puts 'README.md is updated.'
29
22
  end
30
23
 
31
- task :run => :compile do
32
- system(RbConfig.ruby, *%w(-I ./lib test.rb))
24
+ task :check_readme do
25
+ require_relative 'lib/debug/session'
26
+ require 'erb'
27
+ current_readme = File.read("README.md")
28
+ generated_readme = ERB.new(File.read('misc/README.md.erb')).result
29
+
30
+ if current_readme != generated_readme
31
+ fail <<~MSG
32
+ The content of README.md doesn't match its template and/or source.
33
+ Please apply the changes to info source (e.g. command comments) or the template and run 'rake README.md' to update README.md.
34
+ MSG
35
+ end
36
+ end
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
+
43
+ desc "Run all debugger console related tests"
44
+ Rake::TestTask.new(:test_console) do |t|
45
+ t.test_files = FileList["test/console/*_test.rb"]
46
+ end
47
+
48
+ desc "Run all debugger protocols (CAP & DAP) related tests"
49
+ Rake::TestTask.new(:test_protocol) do |t|
50
+ t.test_files = FileList["test/protocol/*_test.rb"]
51
+ end
52
+
53
+ task test: 'test_console' do
54
+ warn '`rake test` doesn\'t run protocol tests. Use `rake test_all` to test all.'
33
55
  end
34
56
 
57
+ task test_all: [:test_test, :test_console, :test_protocol]