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/lib/debug/tracer.rb CHANGED
@@ -54,6 +54,10 @@ module DEBUGGER__
54
54
  @tracer.disable
55
55
  end
56
56
 
57
+ def enabled?
58
+ @tracer.enabled?
59
+ end
60
+
57
61
  def description
58
62
  nil
59
63
  end
@@ -66,15 +70,7 @@ module DEBUGGER__
66
70
  end
67
71
 
68
72
  def skip? tp
69
- if tp.path.start_with?(__dir__) ||
70
- tp.path.start_with?('<internal:') ||
71
- ThreadClient.current.management? ||
72
- skip_path?(tp.path) ||
73
- skip_with_pattern?(tp)
74
- true
75
- else
76
- false
77
- end
73
+ ThreadClient.current.management? || skip_path?(tp.path) || skip_with_pattern?(tp)
78
74
  end
79
75
 
80
76
  def skip_with_pattern?(tp)
@@ -82,20 +78,17 @@ module DEBUGGER__
82
78
  end
83
79
 
84
80
  def out tp, msg = nil, depth = caller.size - 1
85
- location_str = colorize("#{tp.path}:#{tp.lineno}", [:GREEN])
81
+ location_str = colorize("#{FrameInfo.pretty_path(tp.path)}:#{tp.lineno}", [:GREEN])
86
82
  buff = "#{header(depth)}#{msg} at #{location_str}"
87
83
 
88
84
  if false # TODO: Ractor.main?
89
85
  ThreadClient.current.on_trace self.object_id, buff
90
86
  else
91
87
  @output.puts buff
88
+ @output.flush
92
89
  end
93
90
  end
94
91
 
95
- def puts msg
96
- @output.puts msg
97
- end
98
-
99
92
  def minfo tp
100
93
  return "block{}" if tp.event == :b_call
101
94
 
@@ -125,7 +118,6 @@ module DEBUGGER__
125
118
  next if skip?(tp)
126
119
 
127
120
  depth = caller.size
128
- sp = ' ' * depth
129
121
 
130
122
  call_identifier_str =
131
123
  if tp.defined_class
@@ -139,9 +131,11 @@ module DEBUGGER__
139
131
  case tp.event
140
132
  when :call, :c_call, :b_call
141
133
  depth += 1 if tp.event == :c_call
134
+ sp = ' ' * depth
142
135
  out tp, ">#{sp}#{call_identifier_str}", depth
143
136
  when :return, :c_return, :b_return
144
137
  depth += 1 if tp.event == :c_return
138
+ sp = ' ' * depth
145
139
  return_str = colorize_magenta(DEBUGGER__.safe_inspect(tp.return_value, short: true))
146
140
  out tp, "<#{sp}#{call_identifier_str} #=> #{return_str}", depth
147
141
  end
@@ -191,7 +185,7 @@ module DEBUGGER__
191
185
  @tracer = TracePoint.new(:a_call){|tp|
192
186
  next if skip?(tp)
193
187
 
194
- if tp.self.object_id == @obj_id
188
+ if M_OBJECT_ID.bind_call(tp.self) == @obj_id
195
189
  klass = tp.defined_class
196
190
  method = tp.method_id
197
191
  method_info =
data/lib/debug/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module DEBUGGER__
4
- VERSION = "1.4.0"
4
+ VERSION = "1.9.2"
5
5
  end
data/lib/debug.rb CHANGED
@@ -1,4 +1,9 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require_relative 'debug/session'
4
- DEBUGGER__::start no_sigint_hook: true, nonstop: true
3
+ if ENV['RUBY_DEBUG_LAZY']
4
+ require_relative 'debug/prelude'
5
+ else
6
+ require_relative 'debug/session'
7
+ return unless defined?(DEBUGGER__)
8
+ DEBUGGER__::start no_sigint_hook: true, nonstop: true
9
+ end
data/misc/README.md.erb 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
@@ -452,10 +464,18 @@ config set log_level INFO
452
464
  config set no_color true
453
465
  ```
454
466
 
455
- <% cat = nil; DEBUGGER__::CONFIG_SET.each do |key, (env, desc)| %>
467
+ <% cat = nil; DEBUGGER__::CONFIG_SET.each do |key, (env, desc, _, default)| %>
456
468
  <% /\A(\w+): (.+)/ =~ desc; if cat != $1; cat = 1 %>
457
469
  * <%= $1 %>
458
- <% cat = $1; end %> * `<%= env %>` (`<%= key %>`): <%= $2 %><% end %>
470
+ <% cat = $1; end %> * `<%= env %>` (`<%= key %>`): <%= default ? "#{$2} (default: #{default})" : $2 %><% end %>
471
+
472
+ There are other environment variables:
473
+
474
+ * `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/)).
475
+ * `RUBY_DEBUG_ENABLE`: If the value is `0`, do not enable debug.gem feature.
476
+ * `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.
477
+ * `RUBY_DEBUG_EDITOR` or `EDITOR`: An editor used by `edit` debug command.
478
+ * `RUBY_DEBUG_BB`: Define `Kernel#bb` method which is alias of `Kernel#debugger`.
459
479
 
460
480
  ### Initial scripts
461
481
 
@@ -465,7 +485,7 @@ If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains
465
485
  * You can specify the initial script with `rdbg -x initial_script` (like gdb's `-x` option).
466
486
 
467
487
  Initial scripts are useful to write your favorite configurations.
468
- For example, you can set break points with `break file:123` in `~/.rdbgrc`.
488
+ For example, you can set breakpoints with `break file:123` in `~/.rdbgrc`.
469
489
 
470
490
  If there are `~/.rdbgrc.rb` is available, it is also loaded as a ruby script at same timing.
471
491
 
@@ -475,19 +495,44 @@ On the debug console, you can use the following debug commands.
475
495
 
476
496
  There are additional features:
477
497
 
478
- * `<expr>` without debug command is almost same as `pp <expr>`.
479
- * 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`.
480
- * 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.
481
- * `Enter` without any input repeats the last command (useful when repeating `step`s).
498
+ * `<expr>` without debug command is almost the same as `pp <expr>`.
499
+ * 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`.
500
+ * 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.
501
+ * So the author (Koichi Sasada) recommends using `p`, `pp` or `eval` command to evaluate the Ruby expression every time.
502
+ * `Enter` without any input repeats the last command (useful when repeating `step`s) for some commands.
482
503
  * `Ctrl-D` is equal to `quit` command.
483
504
  * [debug command compare sheet - Google Sheets](https://docs.google.com/spreadsheets/d/1TlmmUDsvwK4sSIyoMv-io52BUUz__R5wpu-ComXlsw0/edit?usp=sharing)
484
505
 
485
506
  You can use the following debug commands. Each command should be written in 1 line.
486
- The `[...]` notation means this part can be eliminate. For example, `s[tep]` means `s` or `step` are valid command. `ste` is not valid.
507
+ The `[...]` notation means this part can be eliminated. For example, `s[tep]` means `s` or `step` is a valid command. `ste` is not valid.
487
508
  The `<...>` notation means the argument.
488
509
 
489
510
  <%= DEBUGGER__.help %>
490
511
 
512
+ ### Using IRB as the Debug Console
513
+
514
+ Starting from version `v1.9`, you can now use IRB as the debug console. This integration brings additional features such as:
515
+
516
+ * Autocompletion
517
+ * Support for multi-line input
518
+ * Access to commands not available in `debug`, like `show_source` or `show_doc`
519
+ * [Configurable command aliases](https://docs.ruby-lang.org/en/master/IRB.html#module-IRB-label-Command+Aliases)
520
+
521
+ To switch to the IRB console, simply use the `irb` command in the debug console.
522
+
523
+ Once activated, you'll notice the prompt changes to:
524
+
525
+ ```txt
526
+ irb:rdbg(main):001>
527
+ ```
528
+
529
+ If you want to make IRB the default console for all sessions, configure the `irb_console` setting by either:
530
+
531
+ * Setting the `RUBY_DEBUG_IRB_CONSOLE=true` environment variable
532
+ * Or adding `config set irb_console 1` to your `~/.rdbgrc`
533
+
534
+ To disable the IRB console in the current session, execute `config set irb_console 0` in the console.
535
+
491
536
  ## Debugger API
492
537
 
493
538
  ### Start debugging
@@ -520,7 +565,7 @@ Emacs support available.
520
565
 
521
566
  #### Start by method
522
567
 
523
- 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.
568
+ 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.
524
569
 
525
570
  * `DEBUGGER__.start(**kw)`: start debug session with local console.
526
571
  * `DEBUGGER__.open(**kw)`: open debug port with configuration (without configurations open with UNIX domain socket)
@@ -539,21 +584,21 @@ DEBUGGER__.start(no_color: true, # disable colorize
539
584
 
540
585
  ### `binding.break` method
541
586
 
542
- `binding.break` (or `binding.b`) set breakpoints at written line. It also has several keywords.
587
+ `binding.break` (or `binding.b`) set breakpoints at the written line. It also has several keywords.
543
588
 
544
- If `do: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command and continue the program.
589
+ If `do: 'command'` is specified, the debugger suspends the program, runs the `command` as a debug command, and continues the program.
545
590
  It is useful if you only want to call a debug command and don't want to stop there.
546
591
 
547
592
  ```
548
593
  def initialize
549
594
  @a = 1
550
- binding.b do: 'watch @a'
595
+ binding.b do: 'info \n watch @a'
551
596
  end
552
597
  ```
553
598
 
554
- On this case, register a watch breakpoint for `@a` and continue to run.
599
+ 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.
555
600
 
556
- If `pre: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command, and keep suspend.
601
+ If `pre: 'command'` is specified, the debugger suspends the program and runs the `command` as a debug command, and keeps suspended.
557
602
  It is useful if you have operations before suspend.
558
603
 
559
604
  ```
@@ -563,7 +608,7 @@ def foo
563
608
  end
564
609
  ```
565
610
 
566
- On this case, you can see the result of `bar()` every time you stop there.
611
+ In this case, you can see the result of `bar()` every time you stop there.
567
612
 
568
613
  ## rdbg command help
569
614
 
@@ -571,6 +616,11 @@ On this case, you can see the result of `bar()` every time you stop there.
571
616
  <%= `exe/rdbg --help` %>
572
617
  ```
573
618
 
619
+ # Additional Resources
620
+
621
+ - [From byebug to ruby/debug](https://st0012.dev/from-byebug-to-ruby-debug) by Stan Lo - A migration guide for `byebug` users.
622
+ - [ruby/debug cheatsheet](https://st0012.dev/ruby-debug-cheatsheet) by Stan Lo
623
+
574
624
  # Contributing
575
625
 
576
626
  Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/debug.
metadata CHANGED
@@ -1,45 +1,44 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: debug
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.4.0
4
+ version: 1.9.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Koichi Sasada
8
- autorequire:
9
8
  bindir: exe
10
9
  cert_chain: []
11
- date: 2021-12-17 00:00:00.000000000 Z
10
+ date: 2024-03-29 00:00:00.000000000 Z
12
11
  dependencies:
13
12
  - !ruby/object:Gem::Dependency
14
13
  name: irb
15
14
  requirement: !ruby/object:Gem::Requirement
16
15
  requirements:
17
- - - ">="
16
+ - - "~>"
18
17
  - !ruby/object:Gem::Version
19
- version: 1.3.6
18
+ version: '1.10'
20
19
  type: :runtime
21
20
  prerelease: false
22
21
  version_requirements: !ruby/object:Gem::Requirement
23
22
  requirements:
24
- - - ">="
23
+ - - "~>"
25
24
  - !ruby/object:Gem::Version
26
- version: 1.3.6
25
+ version: '1.10'
27
26
  - !ruby/object:Gem::Dependency
28
27
  name: reline
29
28
  requirement: !ruby/object:Gem::Requirement
30
29
  requirements:
31
30
  - - ">="
32
31
  - !ruby/object:Gem::Version
33
- version: 0.2.7
32
+ version: 0.3.8
34
33
  type: :runtime
35
34
  prerelease: false
36
35
  version_requirements: !ruby/object:Gem::Requirement
37
36
  requirements:
38
37
  - - ">="
39
38
  - !ruby/object:Gem::Version
40
- version: 0.2.7
39
+ version: 0.3.8
41
40
  description: Debugging functionality for Ruby. This is completely rewritten debug.rb
42
- which was contained by the encient Ruby versions.
41
+ which was contained by the ancient Ruby versions.
43
42
  email:
44
43
  - ko1@atdot.net
45
44
  executables:
@@ -48,34 +47,27 @@ extensions:
48
47
  - ext/debug/extconf.rb
49
48
  extra_rdoc_files: []
50
49
  files:
51
- - ".github/ISSUE_TEMPLATE/bug_report.md"
52
- - ".github/ISSUE_TEMPLATE/custom.md"
53
- - ".github/ISSUE_TEMPLATE/feature_request.md"
54
- - ".github/pull_request_template.md"
55
- - ".github/workflows/ruby.yml"
56
- - ".gitignore"
57
50
  - CONTRIBUTING.md
58
51
  - Gemfile
59
52
  - LICENSE.txt
60
53
  - README.md
61
54
  - Rakefile
62
55
  - TODO.md
63
- - bin/console
64
- - bin/gentest
65
- - bin/setup
66
56
  - debug.gemspec
67
57
  - exe/rdbg
68
58
  - ext/debug/debug.c
69
59
  - ext/debug/extconf.rb
70
60
  - ext/debug/iseq_collector.c
71
61
  - lib/debug.rb
72
- - lib/debug/bp.vim
62
+ - lib/debug/abbrev_command.rb
73
63
  - lib/debug/breakpoint.rb
74
64
  - lib/debug/client.rb
75
65
  - lib/debug/color.rb
76
66
  - lib/debug/config.rb
77
67
  - lib/debug/console.rb
68
+ - lib/debug/dap_custom/traceInspector.rb
78
69
  - lib/debug/frame_info.rb
70
+ - lib/debug/irb_integration.rb
79
71
  - lib/debug/local.rb
80
72
  - lib/debug/open.rb
81
73
  - lib/debug/open_nonstop.rb
@@ -97,7 +89,6 @@ licenses:
97
89
  metadata:
98
90
  homepage_uri: https://github.com/ruby/debug
99
91
  source_code_uri: https://github.com/ruby/debug
100
- post_install_message:
101
92
  rdoc_options: []
102
93
  require_paths:
103
94
  - lib
@@ -105,15 +96,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
105
96
  requirements:
106
97
  - - ">="
107
98
  - !ruby/object:Gem::Version
108
- version: 2.6.0
99
+ version: 2.7.0
109
100
  required_rubygems_version: !ruby/object:Gem::Requirement
110
101
  requirements:
111
102
  - - ">="
112
103
  - !ruby/object:Gem::Version
113
104
  version: '0'
114
105
  requirements: []
115
- rubygems_version: 3.1.6
116
- signing_key:
106
+ rubygems_version: 3.6.0.dev
117
107
  specification_version: 4
118
108
  summary: Debugging functionality for Ruby
119
109
  test_files: []
@@ -1,24 +0,0 @@
1
- ---
2
- name: Bug report
3
- about: Create a report to help us improve
4
- title: ''
5
- labels: ''
6
- assignees: ''
7
-
8
- ---
9
-
10
- **Your environment**
11
-
12
- * `ruby -v`:
13
- * `rdbg -v`:
14
-
15
- **Describe the bug**
16
- A clear and concise description of what the bug is.
17
-
18
- **To Reproduce**
19
-
20
- **Expected behavior**
21
- A clear and concise description of what you expected to happen.
22
-
23
- **Additional context**
24
- Add any other context about the problem here.
@@ -1,10 +0,0 @@
1
- ---
2
- name: Custom issue template
3
- about: Blank issue
4
- title: ''
5
- labels: ''
6
- assignees: ''
7
-
8
- ---
9
-
10
-
@@ -1,14 +0,0 @@
1
- ---
2
- name: Feature request
3
- about: Suggest an idea for this project
4
- title: ''
5
- labels: ''
6
- assignees: ''
7
-
8
- ---
9
-
10
- **Your proposal**
11
- What is your idea?
12
-
13
- **Additional context**
14
- Add any other context or screenshots about the feature request here.