debug 1.3.4 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 58d7a886dc29b717d9f31ca7859a40a881a251a4c5e64705ac38de1cb94c0f32
4
- data.tar.gz: a58994d8d302dac0aedd63775b8d81769d326a6bb0746d9953182fa8b36894fd
3
+ metadata.gz: cb9c418ee481ed3b473973d522bb811949f6123501709d3385d9b2bf2a46d993
4
+ data.tar.gz: d0036bac1930ec7e920e9faeb66556a4a9132342ed604a909e15f9d02b4d6963
5
5
  SHA512:
6
- metadata.gz: 3988bc3fd10cab3592a9f6b3b816dd2f5cabf5e8e4bceaec646011a1663b037a7f9683008c77d1c91a0a8f984540c16ef5975fa14b93f84b6cca5915e98df440
7
- data.tar.gz: 4283c41adf172ae2d1e51bb34adfb65ab2b521862bae6be7bd08ba485bea178e0e2ec511db7b9f0297e2aea4e4d2ac249887bb9271f51d71d6beb76a0aee63d0
6
+ metadata.gz: e9cb09ddeee150eac35f5f3044106f482e54e16b41cee4ab6d0678fa92a2c1aefad350412bdc00997892733cf0a58312372d3f40c0f22d5262223de46f31cd9b
7
+ data.tar.gz: 68a846cc25aca6aab1429b3b36da57977c7c5671b21e9c6381f6d0b6d5fe7d28979fac53d1958da4de00c10445722a3fe1e386a871ee8b5638b3bf541cbf19ad
data/CONTRIBUTING.md CHANGED
@@ -14,23 +14,41 @@ If you spot any problem, please open an issue.
14
14
  ### Run all tests
15
15
 
16
16
  ```bash
17
- $ rake test
17
+ $ rake test_all
18
+ ```
19
+
20
+ ### Run all console tests
21
+
22
+ ```bash
23
+ $ rake test_console
24
+ ```
25
+
26
+ ### Run all protocol (DAP & CDP) tests
27
+
28
+ ```bash
29
+ $ rake test_protocol
18
30
  ```
19
31
 
20
32
  ### Run specific test(s)
21
33
 
22
34
 
23
35
  ```bash
24
- $ ruby test/debug/bp_test.rb # run all tests in the specified file
25
- $ ruby test/debug/bp_test.rb -h # to see all the test options
36
+ $ ruby test/console/break_test.rb # run all tests in the specified file
37
+ $ ruby test/console/break_test.rb -h # to see all the test options
26
38
  ```
27
39
 
28
40
  ## Generate Tests
41
+
29
42
  There is a test generator in `debug.rb` project to make it easier to write tests.
43
+
30
44
  ### Quickstart
31
- This section shows you how to create test file by test generator. For more advanced informations on creating tests, please take a look at [gentest options](#gentest-options). (You can also check by `$bin/gentest -h`)
45
+
46
+ This section shows you how to create test file by test generator. For more advanced information on creating tests, please take a look at [gentest options](#gentest-options). (You can also check by `$bin/gentest -h`)
47
+
32
48
  #### 1. Create a target file for debuggee.
49
+
33
50
  Let's say, we created `target.rb` which is located in top level directory of debugger.
51
+
34
52
  ```ruby
35
53
  module Foo
36
54
  class Bar
@@ -42,11 +60,15 @@ module Foo
42
60
  bar = Bar.new
43
61
  end
44
62
  ```
63
+
45
64
  #### 2. Run `gentest` as shown in the example below.
65
+
46
66
  ```shell
47
67
  $ bin/gentest target.rb
48
68
  ```
69
+
49
70
  #### 3. Debugger will be executed. You can type any debug commands.
71
+
50
72
  ```shell
51
73
  $ bin/gentest target.rb
52
74
  DEBUGGER: Session start (pid: 11139)
@@ -119,8 +141,11 @@ created: /Users/naotto/workspace/debug/test/tool/../debug/foo_test.rb
119
141
  class: FooTest
120
142
  method: test_1629720194
121
143
  ```
144
+
122
145
  #### 4. The test file will be created as `test/debug/foo_test.rb`.
146
+
123
147
  If the file already exists, **only method** will be added to it.
148
+
124
149
  ```ruby
125
150
  # frozen_string_literal: true
126
151
 
@@ -204,17 +229,217 @@ end
204
229
  ```
205
230
 
206
231
  #### gentest options
232
+
207
233
  You can get more information about `gentest` here.
208
234
 
209
- The default method name is `test_#{some integer numbers}`, the class name is `FooTest`, and the file name will be `foo_test.rb`.
235
+ The default method name is `test_#{some integer numbers}`, the class name is `FooTest#{some integer numbers}`, and the file name will be `foo_test.rb`.
210
236
  The following table shows examples of the gentest options.
211
237
 
212
238
  | Command | Description | File | Class | Method |
213
239
  | --- | --- | --- | --- | --- |
214
- | `$ bin/gentest target.rb` | Run without any options | `foo_test.rb` | `FooTest` | `test_#{some integer numbers}` |
215
- | `$ bin/gentest target.rb -c step` | Specify the class name | `step_test.rb` | `StepTest` | `test_#{some integer numbers}` |
216
- | `$ bin/gentest target.rb -m test_step` | Specify the method name | `foo_test.rb` | `FooTest` | `test_step` |
217
- | `$ bin/gentest target.rb -c step -m test_step` | Specify the class name and the method name | `step_test.rb` | `StepTest` | `test_step` |
240
+ | `$ bin/gentest target.rb` | Run without any options | `foo_test.rb` | `FooTest...` | `test_...` |
241
+ | `$ bin/gentest target.rb --open=vscode` | Run the debugger with VScode | `foo_test.rb` | `FooTest...` | `test_...` |
242
+ | `$ bin/gentest target.rb -c step` | Specify the class name | `step_test.rb` | `StepTest...` | `test_...` |
243
+ | `$ bin/gentest target.rb -m test_step` | Specify the method name | `foo_test.rb` | `FooTest...` | `test_step` |
244
+ | `$ bin/gentest target.rb -c step -m test_step` | Specify the class name and the method name | `step_test.rb` | `StepTest...` | `test_step` |
245
+
246
+ ### Assertions
247
+
248
+ - assert_line_num(expected)
249
+
250
+ Passes if `expected` is equal to the location where debugger stops.
251
+
252
+ - assert_line_text(text)
253
+
254
+ Passes if `text` is included in the last debugger log.
255
+
256
+ - assert_no_line_text(text)
257
+
258
+ Passes if `text` is not included in the last debugger log.
259
+
260
+ - assert_debuggee_line_text(text)
261
+
262
+ Passes if `text` is included in the debuggee log.
263
+
264
+ ### Tests for DAP and CDP
265
+
266
+ Currently, there are 2 kinds of test frameworks for DAP and CDP.
267
+
268
+ 1. Protocol-based tests
269
+
270
+ If you want to write protocol-based tests, you should use the test generator.
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 ``$ bin/gentest target.rb --open=chrome` there, Chrome will be executed.
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
+ 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 [Procol viewer for "Chrome DevTools Protocol"](https://chromedevtools.github.io/devtools-protocol/) to learn more about CDP formats.
276
+
277
+ 2. High-level tests
278
+
279
+ High-level tests are designed to test both DAP and CDP for a single method.
280
+ You can write tests as follows:
281
+ **NOTE:** Use `req_terminate_debuggee` to finish debugging. You can't use any methods such as `req_continue`, `req_next` and so on.
282
+
283
+ ```ruby
284
+ require_relative '../support/test_case'
285
+ module DEBUGGER__
286
+ class BreakTest < TestCase
287
+ # PROGRAM is the target script.
288
+ PROGRAM = <<~RUBY
289
+ 1| module Foo
290
+ 2| class Bar
291
+ 3| def self.a
292
+ 4| "hello"
293
+ 5| end
294
+ 6| end
295
+ 7| Bar.a
296
+ 8| bar = Bar.new
297
+ 9| end
298
+ RUBY
299
+
300
+ def test_break1
301
+ run_protocol_scenario PROGRAM do # Start debugging with DAP and CDP
302
+ req_add_breakpoint 5 # Set a breakpoint on line 5.
303
+ req_add_breakpoint 8 # Set a breakpoint on line 8.
304
+ req_continue # Resume the program.
305
+ assert_line_num 5 # Check if debugger stops at line 5.
306
+ req_continue # Resume the program.
307
+ assert_line_num 8 # Check if debugger stops at line 8.
308
+ req_terminate_debuggee # Terminate debugging.
309
+ end
310
+ end
311
+ end
312
+ end
313
+ ```
314
+
315
+ #### API
316
+
317
+ - run_protocol_scenario program, dap: true, cdp: true, &scenario
318
+
319
+ Execute debugging `program` with `&scenario`. If you want to test it only for DAP, you can write as follows:
320
+
321
+ `run_protocol_scenario program, cdp: false ...`
322
+
323
+ - req_add_breakpoint(lineno, path: temp_file_path, cond: nil)
324
+
325
+ Sends request to rdbg to add a breakpoint.
326
+
327
+ - req_delete_breakpoint bpnum
328
+
329
+ Sends request to rdbg to delete a breakpoint.
330
+
331
+ - req_set_exception_breakpoints(breakpoints)
332
+
333
+ Sends request to rdbg to set exception breakpoints. e.g.
334
+
335
+ ```rb
336
+ req_set_exception_breakpoints([{ name: "RuntimeError", condition: "a == 1" }])
337
+ ```
338
+
339
+ Please note that `setExceptionBreakpoints` resets all exception breakpoints in every request.
340
+
341
+ So the following code will only set breakpoint for `Exception`.
342
+
343
+ ```rb
344
+ req_set_exception_breakpoints([{ name: "RuntimeError" }])
345
+ req_set_exception_breakpoints([{ name: "Exception" }])
346
+ ```
347
+
348
+ This means you can also use
349
+
350
+ ```rb
351
+ req_set_exception_breakpoints([])
352
+ ```
353
+
354
+ to clear all exception breakpoints.
355
+
356
+ - req_continue
357
+
358
+ Sends request to rdbg to resume the program.
359
+
360
+ - req_step
361
+
362
+ Sends request to rdbg to step into next method.
363
+
364
+ - req_next
365
+
366
+ Sends request to rdbg to step over next method.
367
+
368
+ - req_finish
369
+
370
+ Sends request to rdbg to step out of current method.
371
+
372
+ - req_step_back
373
+
374
+ Sends request to rdbg to step back from current method.
375
+
376
+ - req_terminate_debuggee
377
+
378
+ Sends request to rdbg to terminate the debuggee.
379
+
380
+ - assert_reattach
381
+
382
+ Passes if reattaching to rdbg is successful.
383
+
384
+ - assert_hover_result(expected, expression)
385
+
386
+ Passes if result of `expression` matches `expected`.
387
+
388
+ `expected` need to be a Hash object as follows:
389
+
390
+ `assert_hover_result({value: '2', type: 'Integer'}, 'a')`
391
+
392
+ NOTE: `value` and `type` need to be strings.
393
+
394
+ - assert_repl_result(expected, expression)
395
+
396
+ Passes if result of `expression` matches `expected`.
397
+
398
+ `expected` need to be a Hash object as follows:
399
+
400
+ `assert_repl_result({value: '2', type: 'Integer'}, 'a')`
401
+
402
+ NOTE: `value` and `type` need to be strings.
403
+
404
+ - assert_watch_result(expected, expression)
405
+
406
+ Passes if result of `expression` matches `expected`.
407
+
408
+ `expected` need to be a Hash object as follows:
409
+
410
+ `assert_watch_result({value: '2', type: 'Integer'}, 'a')`
411
+
412
+ NOTE: `value` and `type` need to be strings.
413
+
414
+ - assert_line_num(expected)
415
+
416
+ Passes if `expected` is equal to the location where debugger stops.
417
+
418
+ - assert_locals_result(expected)
419
+
420
+ Passes if all of `expected` local variable entries match the ones returned by debugger.
421
+
422
+ An variable entry looks like this: `{ name: "bar", value: "nil", type: "NilClass" }`.
423
+
424
+ Please note that both `value` and `type` need to be strings.
425
+
426
+ - assert_threads_result(expected)
427
+
428
+ Passes if both conditions are true:
429
+
430
+ 1. The number of expected patterns matches the number of threads.
431
+ 2. Every pattern matches a thread name. Notice that the order of threads info is not guaranteed.
432
+
433
+ Example:
434
+
435
+ ```
436
+ assert_threads_result(
437
+ [
438
+ /\.rb:\d:in `<main>'/,
439
+ /\.rb:\d:in `block in foo'/
440
+ ]
441
+ )
442
+ ```
218
443
 
219
444
  ## To Update README
220
445
 
data/Gemfile CHANGED
@@ -6,3 +6,4 @@ gem "rake"
6
6
  gem "rake-compiler"
7
7
  gem "test-unit", "~> 3.0"
8
8
  gem "test-unit-rr"
9
+ gem "json-schema"
data/README.md CHANGED
@@ -1,19 +1,23 @@
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.6 and later.
6
6
 
7
7
  This debug.rb is 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
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
+
17
21
  * Extensible: application can introduce debugging support with several ways:
18
22
  * By `rdbg` command
19
23
  * By loading libraries with `-r` command line option
@@ -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:
@@ -60,8 +67,14 @@ There are several options for (1) and (2). Please choose your favorite way.
60
67
 
61
68
  ### Modify source code with [`binding.break`](#bindingbreak-method) (similar to `binding.pry` or `binding.irb`)
62
69
 
63
- If you can modify the source code, you can use the debugger by adding `require 'debug'` line at the top of your program and putting [`binding.break`](#bindingbreak-method) method (`binding.b` for short) into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`.
64
- After that, you run the program as usual and you will enter the debug console at breakpoints you inserted.
70
+ If you can modify the source code, you can use the debugger by adding `require 'debug'` at the top of your program and putting [`binding.break`](#bindingbreak-method) method into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`.
71
+
72
+ You can also use its 2 aliases in the same way:
73
+
74
+ - `binding.b`
75
+ - `debugger`
76
+
77
+ After that, run the program as usual and you will enter the debug console at breakpoints you inserted.
65
78
 
66
79
  The following example shows the demonstration of [`binding.break`](#bindingbreak-method).
67
80
 
@@ -107,7 +120,7 @@ d => nil
107
120
  5| binding.break
108
121
  6| c = 3
109
122
  7| d = 4
110
- => 8| binding.break # Again the program stops at here
123
+ => 8| binding.break # Again the program stops here
111
124
  9| p [a, b, c, d]
112
125
  10|
113
126
  11| __END__
@@ -128,7 +141,7 @@ d => 4
128
141
  ### Invoke the program from the debugger as a traditional debuggers
129
142
 
130
143
  If you don't want to modify the source code, you can set breakpoints with a debug command `break` (`b` for short).
131
- 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.
132
145
 
133
146
  ```shell
134
147
  $ cat target.rb # Sample program
@@ -274,7 +287,12 @@ You can run your application as a remote debuggee and the remote debugger consol
274
287
 
275
288
  ### Invoke as a remote debuggee
276
289
 
277
- 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)`
278
296
 
279
297
  #### `rdbg --open` (or `rdbg -O` for short)
280
298
 
@@ -346,12 +364,14 @@ You can attach with external debugger frontend with VSCode and Chrome.
346
364
  $ rdbg --open=[frontend] target.rb
347
365
  ```
348
366
 
349
- will open a debug port and `[frontned]` can attache to the port.
367
+ will open a debug port and `[frontend]` can attach to the port.
350
368
 
351
369
  Also `open` command allows opening the debug port.
352
370
 
353
371
  #### VSCode integration
354
372
 
373
+ ([vscode-rdbg v0.0.9](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) or later is required)
374
+
355
375
  If you don't run a debuggee Ruby process on VSCode, you can attach with VSCode later with the following steps.
356
376
 
357
377
  `rdbg --open=vscode` opens the debug port and tries to invoke the VSCode (`code` command).
@@ -411,7 +431,7 @@ Note that you can attach with `rdbg --attach` and continue REPL debugging.
411
431
 
412
432
  #### Chrome DevTool integration
413
433
 
414
- With `rdbg --open=chrome` command will shows the following message.
434
+ With `rdbg --open=chrome` command will show the following message.
415
435
 
416
436
  ```
417
437
  $ rdbg target.rb --open=chrome
@@ -427,7 +447,7 @@ Type `devtools://devtools/bundled/inspector.html?ws=127.0.0.1:43633` in the addr
427
447
 
428
448
  Also `open chrome` command works like `open vscode`.
429
449
 
430
- For more information about how to use Chrome debugging, you might want to read [here](https://developer.chrome.com/docs/devtools/)
450
+ For more information about how to use Chrome debugging, you might want to read [here](https://developer.chrome.com/docs/devtools/).
431
451
 
432
452
  ## Configuration
433
453
 
@@ -448,41 +468,53 @@ config set no_color true
448
468
 
449
469
  * UI
450
470
  * `RUBY_DEBUG_LOG_LEVEL` (`log_level`): Log level same as Logger (default: WARN)
451
- * `RUBY_DEBUG_SHOW_SRC_LINES` (`show_src_lines`): Show n lines source code on breakpoint (default: 10 lines)
452
- * `RUBY_DEBUG_SHOW_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2 frames)
453
- * `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_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2)
473
+ * `RUBY_DEBUG_USE_SHORT_PATH` (`use_short_path`): Show shorten PATH (like $(Gem)/foo.rb) (default: false)
454
474
  * `RUBY_DEBUG_NO_COLOR` (`no_color`): Do not use colorize (default: false)
455
475
  * `RUBY_DEBUG_NO_SIGINT_HOOK` (`no_sigint_hook`): Do not suspend on SIGINT (default: false)
456
476
  * `RUBY_DEBUG_NO_RELINE` (`no_reline`): Do not use Reline library (default: false)
477
+ * `RUBY_DEBUG_NO_HINT` (`no_hint`): Do not show the hint on the REPL (default: false)
457
478
 
458
479
  * CONTROL
459
- * `RUBY_DEBUG_SKIP_PATH` (`skip_path`): Skip showing/entering frames for given paths (default: [])
480
+ * `RUBY_DEBUG_SKIP_PATH` (`skip_path`): Skip showing/entering frames for given paths
460
481
  * `RUBY_DEBUG_SKIP_NOSRC` (`skip_nosrc`): Skip on no source code lines (default: false)
461
482
  * `RUBY_DEBUG_KEEP_ALLOC_SITE` (`keep_alloc_site`): Keep allocation site and p, pp shows it (default: false)
462
483
  * `RUBY_DEBUG_POSTMORTEM` (`postmortem`): Enable postmortem debug (default: false)
463
484
  * `RUBY_DEBUG_FORK_MODE` (`fork_mode`): Control which process activates a debugger after fork (both/parent/child) (default: both)
464
- * `RUBY_DEBUG_SIGDUMP_SIG` (`sigdump_sig`): Sigdump signal (default: disabled)
485
+ * `RUBY_DEBUG_SIGDUMP_SIG` (`sigdump_sig`): Sigdump signal (default: false)
465
486
 
466
487
  * BOOT
467
- * `RUBY_DEBUG_NONSTOP` (`nonstop`): Nonstop mode
468
- * `RUBY_DEBUG_STOP_AT_LOAD` (`stop_at_load`): Stop at just loading location
488
+ * `RUBY_DEBUG_NONSTOP` (`nonstop`): Nonstop mode (default: false)
489
+ * `RUBY_DEBUG_STOP_AT_LOAD` (`stop_at_load`): Stop at just loading location (default: false)
469
490
  * `RUBY_DEBUG_INIT_SCRIPT` (`init_script`): debug command script path loaded at first stop
470
491
  * `RUBY_DEBUG_COMMANDS` (`commands`): debug commands invoked at first stop. commands should be separated by ';;'
471
- * `RUBY_DEBUG_NO_RC` (`no_rc`): ignore loading ~/.rdbgrc(.rb)
492
+ * `RUBY_DEBUG_NO_RC` (`no_rc`): ignore loading ~/.rdbgrc(.rb) (default: false)
472
493
  * `RUBY_DEBUG_HISTORY_FILE` (`history_file`): history file (default: ~/.rdbg_history)
473
- * `RUBY_DEBUG_SAVE_HISTORY` (`save_history`): maximum save history lines (default: 10,000)
494
+ * `RUBY_DEBUG_SAVE_HISTORY` (`save_history`): maximum save history lines (default: 10000)
474
495
 
475
496
  * REMOTE
476
497
  * `RUBY_DEBUG_PORT` (`port`): TCP/IP remote debugging: port
477
- * `RUBY_DEBUG_HOST` (`host`): TCP/IP remote debugging: host (localhost if not given)
498
+ * `RUBY_DEBUG_HOST` (`host`): TCP/IP remote debugging: host (default: 127.0.0.1)
478
499
  * `RUBY_DEBUG_SOCK_PATH` (`sock_path`): UNIX Domain Socket remote debugging: socket path
479
500
  * `RUBY_DEBUG_SOCK_DIR` (`sock_dir`): UNIX Domain Socket remote debugging: socket directory
501
+ * `RUBY_DEBUG_LOCAL_FS_MAP` (`local_fs_map`): Specify local fs map
502
+ * `RUBY_DEBUG_SKIP_BP` (`skip_bp`): Skip breakpoints if no clients are attached (default: false)
480
503
  * `RUBY_DEBUG_COOKIE` (`cookie`): Cookie for negotiation
481
504
  * `RUBY_DEBUG_OPEN_FRONTEND` (`open_frontend`): frontend used by open command (vscode, chrome, default: rdbg).
505
+ * `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))
482
506
 
483
507
  * OBSOLETE
484
508
  * `RUBY_DEBUG_PARENT_ON_FORK` (`parent_on_fork`): Keep debugging parent process on fork (default: false)
485
509
 
510
+ There are other environment variables:
511
+
512
+ * `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
+ * `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/...'` 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
+ * `RUBY_DEBUG_EDITOR` or `EDITOR`: An editor used by `edit` debug command.
516
+ * `RUBY_DEBUG_BB`: Define `Kernel#bb` method which is alias of `Kernel#debugger`.
517
+
486
518
  ### Initial scripts
487
519
 
488
520
  If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains debug commands) when the debug session is started.
@@ -525,7 +557,7 @@ The `<...>` notation means the argument.
525
557
  * `fin[ish]`
526
558
  * Finish this frame. Resume the program until the current frame is finished.
527
559
  * `fin[ish] <n>`
528
- * Finish frames, same as `step <n>`.
560
+ * Finish `<n>`th frames.
529
561
  * `c[ontinue]`
530
562
  * Resume the program.
531
563
  * `q[uit]` or `Ctrl-D`
@@ -533,11 +565,11 @@ The `<...>` notation means the argument.
533
565
  * `q[uit]!`
534
566
  * Same as q[uit] but without the confirmation prompt.
535
567
  * `kill`
536
- * Stop the debuggee process with `Kernal#exit!`.
568
+ * Stop the debuggee process with `Kernel#exit!`.
537
569
  * `kill!`
538
570
  * Same as kill but without the confirmation prompt.
539
571
  * `sigint`
540
- * Execute SIGINT handler registerred by the debuggee.
572
+ * Execute SIGINT handler registered by the debuggee.
541
573
  * Note that this command should be used just after stop by `SIGINT`.
542
574
 
543
575
  ### Breakpoint
@@ -558,14 +590,32 @@ The `<...>` notation means the argument.
558
590
  * break and run `<command>` before stopping.
559
591
  * `b[reak] ... do: <command>`
560
592
  * break and run `<command>`, and continue.
593
+ * `b[reak] ... path: <path>`
594
+ * break if the path matches to `<path>`. `<path>` can be a regexp with `/regexp/`.
561
595
  * `b[reak] if: <expr>`
562
596
  * break if: `<expr>` is true at any lines.
563
597
  * Note that this feature is super slow.
564
598
  * `catch <Error>`
565
599
  * Set breakpoint on raising `<Error>`.
600
+ * `catch ... if: <expr>`
601
+ * stops only if `<expr>` is true as well.
602
+ * `catch ... pre: <command>`
603
+ * runs `<command>` before stopping.
604
+ * `catch ... do: <command>`
605
+ * stops and run `<command>`, and continue.
606
+ * `catch ... path: <path>`
607
+ * stops if the exception is raised from a `<path>`. `<path>` can be a regexp with `/regexp/`.
566
608
  * `watch @ivar`
567
609
  * Stop the execution when the result of current scope's `@ivar` is changed.
568
610
  * Note that this feature is super slow.
611
+ * `watch ... if: <expr>`
612
+ * stops only if `<expr>` is true as well.
613
+ * `watch ... pre: <command>`
614
+ * runs `<command>` before stopping.
615
+ * `watch ... do: <command>`
616
+ * stops and run `<command>`, and continue.
617
+ * `watch ... path: <path>`
618
+ * stops if the path matches `<path>`. `<path>` can be a regexp with `/regexp/`.
569
619
  * `del[ete]`
570
620
  * delete all breakpoints.
571
621
  * `del[ete] <bpnum>`
@@ -604,8 +654,8 @@ The `<...>` notation means the argument.
604
654
  * Show information about accessible constants except toplevel constants.
605
655
  * `i[nfo] g[lobal[s]]`
606
656
  * Show information about global variables
607
- * `i[nfo] ... </pattern/>`
608
- * Filter the output with `</pattern/>`.
657
+ * `i[nfo] ... /regexp/`
658
+ * Filter the output with `/regexp/`.
609
659
  * `i[nfo] th[read[s]]`
610
660
  * Show all threads (same as `th[read]`).
611
661
  * `o[utline]` or `ls`
@@ -656,8 +706,8 @@ The `<...>` notation means the argument.
656
706
  * Add an exception tracer. It indicates raising exceptions.
657
707
  * `trace object <expr>`
658
708
  * Add an object tracer. It indicates that an object by `<expr>` is passed as a parameter or a receiver on method call.
659
- * `trace ... </pattern/>`
660
- * Indicates only matched events to `</pattern/>` (RegExp).
709
+ * `trace ... /regexp/`
710
+ * Indicates only matched events to `/regexp/`.
661
711
  * `trace ... into: <file>`
662
712
  * Save trace information into: `<file>`.
663
713
  * `trace off <num>`
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,32 @@ 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 all debugger console related tests"
39
+ Rake::TestTask.new(:test_console) do |t|
40
+ t.test_files = FileList["test/console/*_test.rb", "test/support/*_test.rb"]
41
+ end
42
+
43
+ desc "Run all debugger protocols (CAP & DAP) related tests"
44
+ Rake::TestTask.new(:test_protocol) do |t|
45
+ t.test_files = FileList["test/protocol/*_test.rb"]
46
+ end
47
+
48
+ task test: 'test_console' do
49
+ warn '`rake test` doesn\'t run protocol tests. Use `rake test-all` to test all.'
33
50
  end
34
51
 
52
+ task test_all: [:test_console, :test_protocol]
data/debug.gemspec CHANGED
@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
7
7
  spec.email = ["ko1@atdot.net"]
8
8
 
9
9
  spec.summary = %q{Debugging functionality for Ruby}
10
- spec.description = %q{Debugging functionality for Ruby. This is completely rewritten debug.rb which was contained by the encient Ruby versions.}
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
13
  spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
@@ -17,14 +17,16 @@ Gem::Specification.new do |spec|
17
17
 
18
18
  # Specify which files should be added to the gem when it is released.
19
19
  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
20
- spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
21
- `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
20
+ spec.files = Dir.chdir(File.expand_path(__dir__)) do
21
+ `git ls-files -z`.split("\x0").reject do |f|
22
+ (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
23
+ end
22
24
  end
23
25
  spec.bindir = "exe"
24
- spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
26
+ spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
25
27
  spec.require_paths = ["lib"]
26
28
  spec.extensions = ['ext/debug/extconf.rb']
27
29
 
28
30
  spec.add_dependency "irb", ">= 1.3.6" # for its color_printer class, which was added after 1.3
29
- spec.add_dependency "reline", ">= 0.2.7"
31
+ spec.add_dependency "reline", ">= 0.3.1"
30
32
  end