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 +4 -4
- data/CONTRIBUTING.md +234 -9
- data/Gemfile +1 -0
- data/README.md +81 -31
- data/Rakefile +28 -10
- data/debug.gemspec +7 -5
- data/exe/rdbg +7 -3
- data/ext/debug/debug.c +80 -15
- data/ext/debug/extconf.rb +22 -0
- data/lib/debug/breakpoint.rb +141 -67
- data/lib/debug/client.rb +77 -20
- data/lib/debug/color.rb +29 -19
- data/lib/debug/config.rb +61 -27
- data/lib/debug/console.rb +59 -18
- data/lib/debug/frame_info.rb +41 -40
- data/lib/debug/local.rb +1 -1
- data/lib/debug/prelude.rb +2 -2
- data/lib/debug/server.rb +136 -103
- data/lib/debug/server_cdp.rb +880 -162
- data/lib/debug/server_dap.rb +445 -164
- data/lib/debug/session.rb +540 -269
- data/lib/debug/source_repository.rb +103 -52
- data/lib/debug/thread_client.rb +306 -138
- data/lib/debug/tracer.rb +8 -13
- data/lib/debug/version.rb +1 -1
- data/misc/README.md.erb +44 -16
- metadata +6 -15
- data/.github/ISSUE_TEMPLATE/bug_report.md +0 -24
- data/.github/ISSUE_TEMPLATE/custom.md +0 -10
- data/.github/ISSUE_TEMPLATE/feature_request.md +0 -14
- data/.github/workflows/ruby.yml +0 -34
- data/.gitignore +0 -12
- data/bin/console +0 -14
- data/bin/gentest +0 -22
- data/bin/setup +0 -8
- data/lib/debug/bp.vim +0 -68
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: cb9c418ee481ed3b473973d522bb811949f6123501709d3385d9b2bf2a46d993
|
4
|
+
data.tar.gz: d0036bac1930ec7e920e9faeb66556a4a9132342ed604a909e15f9d02b4d6963
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
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
|
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/
|
25
|
-
$ ruby test/
|
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
|
-
|
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
|
215
|
-
| `$ bin/gentest target.rb
|
216
|
-
| `$ bin/gentest target.rb -
|
217
|
-
| `$ bin/gentest target.rb -
|
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
data/README.md
CHANGED
@@ -1,19 +1,23 @@
|
|
1
|
-
[](https://github.com/ruby/debug/actions/workflows/ruby.yml?query=branch%3Amaster)
|
1
|
+
[](https://github.com/ruby/debug/actions/workflows/ruby.yml?query=branch%3Amaster) [](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
|
15
|
-
|
16
|
-
|
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'`
|
64
|
-
|
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
|
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
|
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 `[
|
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
|
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
|
452
|
-
* `RUBY_DEBUG_SHOW_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2
|
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
|
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:
|
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:
|
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 (
|
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
|
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 `
|
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
|
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] ...
|
608
|
-
* Filter the output with
|
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 ...
|
660
|
-
* Indicates only matched events to
|
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 :
|
32
|
-
|
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
|
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
|
21
|
-
`git ls-files -z`.split("\x0").reject
|
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{
|
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.
|
31
|
+
spec.add_dependency "reline", ">= 0.3.1"
|
30
32
|
end
|