debug 1.0.0.beta7 → 1.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CONTRIBUTING.md +108 -106
- data/Gemfile +1 -0
- data/README.md +415 -250
- data/Rakefile +2 -1
- data/TODO.md +3 -8
- data/debug.gemspec +1 -0
- data/exe/rdbg +5 -8
- data/ext/debug/debug.c +11 -1
- data/lib/debug/breakpoint.rb +55 -22
- data/lib/debug/client.rb +7 -12
- data/lib/debug/color.rb +19 -4
- data/lib/debug/config.rb +354 -175
- data/lib/debug/console.rb +75 -70
- data/lib/debug/frame_info.rb +40 -7
- data/lib/debug/local.rb +91 -0
- data/lib/debug/open.rb +1 -1
- data/lib/debug/open_nonstop.rb +15 -0
- data/lib/debug/server.rb +74 -30
- data/lib/debug/server_dap.rb +32 -7
- data/lib/debug/session.rb +584 -299
- data/lib/debug/{run.rb → start.rb} +1 -1
- data/lib/debug/thread_client.rb +620 -162
- data/lib/debug/tracer.rb +242 -0
- data/lib/debug/version.rb +1 -1
- data/misc/README.md.erb +335 -227
- metadata +22 -5
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: a3e49208dc5aafac57624c1bfb06a1f1d4975bc1a3ea1739b170cd97b4805f80
|
4
|
+
data.tar.gz: 631bb42bb4bb78cb6bda141e062e317edfb49fc01bbf6e4ca65036efc5175c12
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 03d36a4f2ba792570d77206897e112e74947cf951f36dbd62b94f6faefbc431735b92da833682b1e768368e9393051cc7efea784daf853ab6d927b57780ca780
|
7
|
+
data.tar.gz: 837963016cb3d8cb932796706323761ecbcdda55d9c8da0cc68d1d324ad92018e06959489273edbb7a3f0fadc817d699dd744266a3e48ce6ce1647370a77cd1d
|
data/CONTRIBUTING.md
CHANGED
@@ -49,75 +49,75 @@ $ bin/gentest target.rb
|
|
49
49
|
#### 3. Debugger will be executed. You can type any debug commands.
|
50
50
|
```shell
|
51
51
|
$ bin/gentest target.rb
|
52
|
+
DEBUGGER: Session start (pid: 11139)
|
52
53
|
[1, 9] in ~/workspace/debug/target.rb
|
53
|
-
=>
|
54
|
-
|
55
|
-
|
56
|
-
|
57
|
-
|
58
|
-
|
59
|
-
|
60
|
-
|
61
|
-
|
54
|
+
=> 1| module Foo
|
55
|
+
2| class Bar
|
56
|
+
3| def self.a
|
57
|
+
4| "hello"
|
58
|
+
5| end
|
59
|
+
6| end
|
60
|
+
7| Bar.a
|
61
|
+
8| bar = Bar.new
|
62
|
+
9| end
|
62
63
|
=>#0 <main> at ~/workspace/debug/target.rb:1
|
63
64
|
INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:1","line":1}
|
64
|
-
|
65
65
|
(rdbg)s
|
66
66
|
s
|
67
67
|
[1, 9] in ~/workspace/debug/target.rb
|
68
|
-
|
69
|
-
=>
|
70
|
-
|
71
|
-
|
72
|
-
|
73
|
-
|
74
|
-
|
75
|
-
|
76
|
-
|
68
|
+
1| module Foo
|
69
|
+
=> 2| class Bar
|
70
|
+
3| def self.a
|
71
|
+
4| "hello"
|
72
|
+
5| end
|
73
|
+
6| end
|
74
|
+
7| Bar.a
|
75
|
+
8| bar = Bar.new
|
76
|
+
9| end
|
77
77
|
=>#0 <module:Foo> at ~/workspace/debug/target.rb:2
|
78
78
|
#1 <main> at ~/workspace/debug/target.rb:1
|
79
79
|
INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:2","line":2}
|
80
|
-
|
81
80
|
(rdbg)n
|
82
81
|
n
|
83
82
|
[1, 9] in ~/workspace/debug/target.rb
|
84
|
-
|
85
|
-
|
86
|
-
=>
|
87
|
-
|
88
|
-
|
89
|
-
|
90
|
-
|
91
|
-
|
92
|
-
|
83
|
+
1| module Foo
|
84
|
+
2| class Bar
|
85
|
+
=> 3| def self.a
|
86
|
+
4| "hello"
|
87
|
+
5| end
|
88
|
+
6| end
|
89
|
+
7| Bar.a
|
90
|
+
8| bar = Bar.new
|
91
|
+
9| end
|
93
92
|
=>#0 <class:Bar> at ~/workspace/debug/target.rb:3
|
94
93
|
#1 <module:Foo> at ~/workspace/debug/target.rb:2
|
95
|
-
#
|
94
|
+
# and 1 frames (use `bt' command for all frames)
|
96
95
|
INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:3","line":3}
|
97
|
-
|
98
96
|
(rdbg)b 7
|
99
97
|
b 7
|
98
|
+
#0 BP - Line /Users/naotto/workspace/debug/target.rb:7 (line)
|
100
99
|
INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:3","line":3}
|
101
|
-
|
102
100
|
(rdbg)c
|
103
101
|
c
|
104
102
|
[2, 9] in ~/workspace/debug/target.rb
|
105
|
-
|
106
|
-
|
107
|
-
|
108
|
-
|
109
|
-
|
110
|
-
=>
|
111
|
-
|
112
|
-
|
103
|
+
2| class Bar
|
104
|
+
3| def self.a
|
105
|
+
4| "hello"
|
106
|
+
5| end
|
107
|
+
6| end
|
108
|
+
=> 7| Bar.a
|
109
|
+
8| bar = Bar.new
|
110
|
+
9| end
|
113
111
|
=>#0 <module:Foo> at ~/workspace/debug/target.rb:7
|
114
112
|
#1 <main> at ~/workspace/debug/target.rb:1
|
115
113
|
|
116
114
|
Stop by #0 BP - Line /Users/naotto/workspace/debug/target.rb:7 (line)
|
117
115
|
INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:7","line":7}
|
118
|
-
|
119
116
|
(rdbg)q!
|
120
117
|
q!
|
118
|
+
created: /Users/naotto/workspace/debug/test/tool/../debug/foo_test.rb
|
119
|
+
class: FooTest
|
120
|
+
method: test_1629720194
|
121
121
|
```
|
122
122
|
#### 4. The test file will be created as `test/debug/foo_test.rb`.
|
123
123
|
If the file already exists, **only method** will be added to it.
|
@@ -131,70 +131,70 @@ module DEBUGGER__
|
|
131
131
|
def program
|
132
132
|
<<~RUBY
|
133
133
|
1| module Foo
|
134
|
-
|
135
|
-
|
136
|
-
|
137
|
-
|
138
|
-
|
139
|
-
|
140
|
-
|
141
|
-
|
134
|
+
2| class Bar
|
135
|
+
3| def self.a
|
136
|
+
4| "hello"
|
137
|
+
5| end
|
138
|
+
6| end
|
139
|
+
7| Bar.a
|
140
|
+
8| bar = Bar.new
|
141
|
+
9| end
|
142
142
|
RUBY
|
143
143
|
end
|
144
144
|
|
145
|
-
def
|
145
|
+
def test_1629720194
|
146
146
|
debug_code(program) do
|
147
147
|
type 's'
|
148
148
|
assert_line_num 2
|
149
149
|
assert_line_text([
|
150
|
-
|
151
|
-
/
|
152
|
-
/=>
|
153
|
-
/
|
154
|
-
/
|
155
|
-
/
|
156
|
-
/
|
157
|
-
/
|
158
|
-
/
|
159
|
-
/
|
160
|
-
|
161
|
-
/
|
150
|
+
/\[1, 9\] in .*/,
|
151
|
+
/ 1\| module Foo/,
|
152
|
+
/=> 2\| class Bar/,
|
153
|
+
/ 3\| def self\.a/,
|
154
|
+
/ 4\| "hello"/,
|
155
|
+
/ 5\| end/,
|
156
|
+
/ 6\| end/,
|
157
|
+
/ 7\| Bar\.a/,
|
158
|
+
/ 8\| bar = Bar\.new/,
|
159
|
+
/ 9\| end/,
|
160
|
+
/=>\#0\t<module:Foo> at .*/,
|
161
|
+
/ \#1\t<main> at .*/
|
162
162
|
])
|
163
163
|
type 'n'
|
164
164
|
assert_line_num 3
|
165
165
|
assert_line_text([
|
166
|
-
|
167
|
-
/
|
168
|
-
/
|
169
|
-
/=>
|
170
|
-
/
|
171
|
-
/
|
172
|
-
/
|
173
|
-
/
|
174
|
-
/
|
175
|
-
/
|
176
|
-
|
177
|
-
/
|
178
|
-
/
|
166
|
+
/\[1, 9\] in .*/,
|
167
|
+
/ 1\| module Foo/,
|
168
|
+
/ 2\| class Bar/,
|
169
|
+
/=> 3\| def self\.a/,
|
170
|
+
/ 4\| "hello"/,
|
171
|
+
/ 5\| end/,
|
172
|
+
/ 6\| end/,
|
173
|
+
/ 7\| Bar\.a/,
|
174
|
+
/ 8\| bar = Bar\.new/,
|
175
|
+
/ 9\| end/,
|
176
|
+
/=>\#0\t<class:Bar> at .*/,
|
177
|
+
/ \#1\t<module:Foo> at .*/,
|
178
|
+
/ \# and 1 frames \(use `bt' command for all frames\)/
|
179
179
|
])
|
180
180
|
type 'b 7'
|
181
|
-
assert_line_text(
|
181
|
+
assert_line_text(/\#0 BP \- Line .*/)
|
182
182
|
type 'c'
|
183
183
|
assert_line_num 7
|
184
184
|
assert_line_text([
|
185
|
-
|
186
|
-
/
|
187
|
-
/
|
188
|
-
/
|
189
|
-
/
|
190
|
-
/
|
191
|
-
/=>
|
192
|
-
/
|
193
|
-
/
|
194
|
-
|
195
|
-
/
|
185
|
+
/\[2, 9\] in .*/,
|
186
|
+
/ 2\| class Bar/,
|
187
|
+
/ 3\| def self\.a/,
|
188
|
+
/ 4\| "hello"/,
|
189
|
+
/ 5\| end/,
|
190
|
+
/ 6\| end/,
|
191
|
+
/=> 7\| Bar\.a/,
|
192
|
+
/ 8\| bar = Bar\.new/,
|
193
|
+
/ 9\| end/,
|
194
|
+
/=>\#0\t<module:Foo> at .*/,
|
195
|
+
/ \#1\t<main> at .*/,
|
196
196
|
//,
|
197
|
-
/Stop by
|
197
|
+
/Stop by \#0 BP \- Line .*/
|
198
198
|
])
|
199
199
|
type 'q!'
|
200
200
|
end
|
@@ -287,6 +287,7 @@ $ exe/rdbg -e 'b 20;; c ;; bt ;; info ;; q!' -e c target.rb
|
|
287
287
|
|
288
288
|
```
|
289
289
|
❯ exe/rdbg -e 'b 20;; c ;; bt ;; info ;; q!' -e c target.rb
|
290
|
+
DEBUGGER: Session start (pid: 9815)
|
290
291
|
[1, 10] in target.rb
|
291
292
|
=> 1| class Foo
|
292
293
|
2| def first_call
|
@@ -299,10 +300,10 @@ $ exe/rdbg -e 'b 20;; c ;; bt ;; info ;; q!' -e c target.rb
|
|
299
300
|
9| end
|
300
301
|
10| end
|
301
302
|
=>#0 <main> at target.rb:1
|
302
|
-
(rdbg:
|
303
|
-
#
|
304
|
-
(rdbg:
|
305
|
-
[15,
|
303
|
+
(rdbg:commands) b 20
|
304
|
+
#0 BP - Line /PATH_TO_PROJECT/target.rb:20 (return)
|
305
|
+
(rdbg:commands) c
|
306
|
+
[15, 24] in target.rb
|
306
307
|
15| yield(10)
|
307
308
|
16| end
|
308
309
|
17|
|
@@ -312,25 +313,26 @@ $ exe/rdbg -e 'b 20;; c ;; bt ;; info ;; q!' -e c target.rb
|
|
312
313
|
21| end
|
313
314
|
22|
|
314
315
|
23| Foo.new.first_call
|
316
|
+
24|
|
315
317
|
=>#0 Foo#forth_call(num1=20, num2=10) at target.rb:20 #=> 30
|
316
|
-
#1 block{|ten=10|} in second_call at target.rb:8
|
318
|
+
#1 block {|ten=10|} in second_call at target.rb:8
|
317
319
|
# and 4 frames (use `bt' command for all frames)
|
318
320
|
|
319
|
-
Stop by #
|
320
|
-
(rdbg:
|
321
|
+
Stop by #0 BP - Line /PATH_TO_PROJECT/target.rb:20 (return)
|
322
|
+
(rdbg:commands) bt
|
321
323
|
=>#0 Foo#forth_call(num1=20, num2=10) at target.rb:20 #=> 30
|
322
|
-
#1 block{|ten=10|} in second_call at target.rb:8
|
323
|
-
#2 Foo#third_call_with_block(block=#<Proc:
|
324
|
+
#1 block {|ten=10|} in second_call at target.rb:8
|
325
|
+
#2 Foo#third_call_with_block(block=#<Proc:0x00007f9283101568 target.rb:7>) at target.rb:15
|
324
326
|
#3 Foo#second_call(num=20) at target.rb:7
|
325
|
-
#4 first_call at target.rb:3
|
327
|
+
#4 Foo#first_call at target.rb:3
|
326
328
|
#5 <main> at target.rb:23
|
327
|
-
(rdbg:
|
329
|
+
(rdbg:commands) info
|
328
330
|
=>#0 Foo#forth_call(num1=20, num2=10) at target.rb:20 #=> 30
|
329
|
-
|
330
|
-
|
331
|
-
|
332
|
-
|
333
|
-
|
334
|
-
|
335
|
-
(rdbg:
|
331
|
+
%self => #<Foo:0x00007f92831016d0 @ivar1=10, @ivar2=20>
|
332
|
+
%return => 30
|
333
|
+
num1 => 20
|
334
|
+
num2 => 10
|
335
|
+
@ivar1 => 10
|
336
|
+
@ivar2 => 20
|
337
|
+
(rdbg:commands) q!
|
336
338
|
```
|
data/Gemfile
CHANGED
data/README.md
CHANGED
@@ -12,7 +12,7 @@ New debug.rb has several advantages:
|
|
12
12
|
* UNIX domain socket
|
13
13
|
* TCP/IP
|
14
14
|
* VSCode/DAP integration ([VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg))
|
15
|
-
* Extensible: application can introduce debugging support with several
|
15
|
+
* Extensible: application can introduce debugging support with several ways:
|
16
16
|
* By `rdbg` command
|
17
17
|
* By loading libraries with `-r` command line option
|
18
18
|
* By calling Ruby's method explicitly
|
@@ -20,343 +20,359 @@ New debug.rb has several advantages:
|
|
20
20
|
* Support threads (almost done) and ractors (TODO).
|
21
21
|
* Support suspending and entering to the console debugging with `Ctrl-C` at most of timing.
|
22
22
|
* Show parameters on backtrace command.
|
23
|
+
* Support recording & reply debugging.
|
23
24
|
|
24
25
|
# Installation
|
25
26
|
|
26
27
|
```
|
27
|
-
$ gem install debug
|
28
|
+
$ gem install debug
|
28
29
|
```
|
29
30
|
|
30
31
|
or specify `-Ipath/to/debug/lib` in `RUBYOPT` or each ruby command-line option, especially for debug this gem development.
|
31
32
|
|
32
|
-
If you use Bundler, write the following line to your Gemfile.
|
33
|
-
|
34
|
-
```
|
35
|
-
gem "debug", ">= 1.0.0
|
36
|
-
```
|
37
|
-
|
38
|
-
|
39
|
-
|
40
|
-
|
41
|
-
|
42
|
-
|
43
|
-
|
44
|
-
|
45
|
-
|
46
|
-
|
47
|
-
|
48
|
-
* (
|
49
|
-
*
|
50
|
-
|
51
|
-
|
52
|
-
|
53
|
-
|
54
|
-
|
55
|
-
|
56
|
-
|
57
|
-
|
58
|
-
|
59
|
-
|
60
|
-
|
61
|
-
|
62
|
-
|
63
|
-
|
64
|
-
|
65
|
-
|
66
|
-
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
|
71
|
-
|
33
|
+
If you use Bundler, write the following line to your Gemfile.
|
34
|
+
|
35
|
+
```
|
36
|
+
gem "debug", ">= 1.0.0"
|
37
|
+
```
|
38
|
+
|
39
|
+
# HOW TO USE
|
40
|
+
|
41
|
+
To use a debugger, roughly you will do the following steps:
|
42
|
+
|
43
|
+
1. Set breakpoints.
|
44
|
+
2. Run a program with the debugger.
|
45
|
+
3. At the breakpoint, enter the debugger console.
|
46
|
+
4. Use debug commands.
|
47
|
+
* Query the program status (e.g. `p lvar` to see the local variable `lvar`).
|
48
|
+
* Control program flow (e.g. move to the another line with `step`, to the next line with `next`).
|
49
|
+
* Set another breakpoint (e.g. `catch Exception` to set a breakpoint when `Exception` is raised).
|
50
|
+
* Change the configuration (e.g. `config set no_color true` to disable coloring).
|
51
|
+
* Continue the program (`c` or `continue`) and goto 3.
|
52
|
+
|
53
|
+
## Invoke with the debugger
|
54
|
+
|
55
|
+
There are several options for (1) and (2). Please choose your favorite way.
|
56
|
+
|
57
|
+
### Modify source code as `binding.pry` and `binding.irb`
|
58
|
+
|
59
|
+
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` method (`binding.b` for short) into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`.
|
60
|
+
After that, you run the program as usual and you will enter the debug console at breakpoints you inserted.
|
61
|
+
|
62
|
+
The following example shows the demonstration of `binding.break`.
|
63
|
+
|
64
|
+
```shell
|
65
|
+
$ cat target.rb # Sample program
|
66
|
+
require 'debug'
|
67
|
+
|
68
|
+
a = 1
|
69
|
+
b = 2
|
70
|
+
binding.break # Program will stop here
|
71
|
+
c = 3
|
72
|
+
d = 4
|
73
|
+
binding.break # Program will stop here
|
74
|
+
p [a, b, c, d]
|
75
|
+
|
76
|
+
$ ruby target.rb # Run the program normally.
|
77
|
+
DEBUGGER: Session start (pid: 7604)
|
78
|
+
[1, 10] in target.rb
|
79
|
+
1| require 'debug'
|
80
|
+
2|
|
81
|
+
3| a = 1
|
82
|
+
4| b = 2
|
83
|
+
=> 5| binding.break # Now you can see it stops at this line
|
84
|
+
6| c = 3
|
85
|
+
7| d = 4
|
86
|
+
8| binding.break
|
87
|
+
9| p [a, b, c, d]
|
88
|
+
10|
|
89
|
+
=>#0 <main> at target.rb:5
|
90
|
+
|
91
|
+
(rdbg) info locals # You can show local variables
|
92
|
+
=>#0 <main> at target.rb:5
|
93
|
+
%self => main
|
94
|
+
a => 1
|
95
|
+
b => 2
|
96
|
+
c => nil
|
97
|
+
d => nil
|
98
|
+
|
99
|
+
(rdbg) continue # Continue the execution
|
100
|
+
[3, 11] in target.rb
|
101
|
+
3| a = 1
|
102
|
+
4| b = 2
|
103
|
+
5| binding.break
|
104
|
+
6| c = 3
|
105
|
+
7| d = 4
|
106
|
+
=> 8| binding.break # Again the program stops at here
|
107
|
+
9| p [a, b, c, d]
|
108
|
+
10|
|
109
|
+
11| __END__
|
110
|
+
=>#0 <main> at target.rb:8
|
111
|
+
|
112
|
+
(rdbg) info locals # And you can see the updated local variables
|
113
|
+
=>#0 <main> at target.rb:8
|
114
|
+
%self => main
|
115
|
+
a => 1
|
116
|
+
b => 2
|
117
|
+
c => 3
|
118
|
+
d => 4
|
119
|
+
|
120
|
+
(rdbg) continue
|
121
|
+
[1, 2, 3, 4]
|
122
|
+
```
|
123
|
+
|
124
|
+
### Invoke the program from the debugger as a traditional debuggers
|
125
|
+
|
126
|
+
If you don't want to modify the source code, you can set breakpoints with a debug command `break` (`b` for short).
|
127
|
+
Using `rdbg` command to launch the program without any modifications, you can run the program with the debugger.
|
128
|
+
|
129
|
+
```shell
|
130
|
+
$ cat target.rb # Sample program
|
131
|
+
a = 1
|
132
|
+
b = 2
|
133
|
+
c = 3
|
134
|
+
d = 4
|
135
|
+
p [a, b, c, d]
|
136
|
+
|
137
|
+
$ rdbg target.rb # run like `ruby target.rb`
|
138
|
+
DEBUGGER: Session start (pid: 7656)
|
139
|
+
[1, 7] in target.rb
|
140
|
+
=> 1| a = 1
|
141
|
+
2| b = 2
|
142
|
+
3| c = 3
|
143
|
+
4| d = 4
|
144
|
+
5| p [a, b, c, d]
|
145
|
+
6|
|
146
|
+
7| __END__
|
147
|
+
=>#0 <main> at target.rb:1
|
72
148
|
|
73
|
-
|
74
|
-
$ ruby -r debug/run target.rb
|
149
|
+
(rdbg)
|
75
150
|
```
|
76
151
|
|
77
|
-
|
152
|
+
`rdbg` command suspends the program at the beginning of the given script (`target.rb` in this case) and you can use debug commands. `(rdbg)` is prompt. Let's set breakpoints on line 3 and line 5 with `break` command (`b` for short).
|
78
153
|
|
79
|
-
```
|
80
|
-
#
|
81
|
-
|
82
|
-
|
83
|
-
# ... rest of program ...
|
84
|
-
```
|
154
|
+
```shell
|
155
|
+
(rdbg) break 3 # set breakpoint at line 3
|
156
|
+
#0 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
|
85
157
|
|
158
|
+
(rdbg) b 5 # set breakpoint at line 5
|
159
|
+
#1 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
|
86
160
|
|
87
|
-
|
88
|
-
|
161
|
+
(rdbg) break # show all registered breakpoints
|
162
|
+
#0 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
|
163
|
+
#1 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
|
89
164
|
```
|
90
165
|
|
91
|
-
|
92
|
-
The debuggee program (`target.rb`) is suspended at the beginning of `target.rb`.
|
93
|
-
|
94
|
-
|
95
|
-
Alternatively, start the debugger at a specific location in your program using `binding.break` (`binding.b` for short).
|
96
|
-
|
97
|
-
```ruby
|
98
|
-
# target.rb
|
99
|
-
require 'debug' # start the debugger
|
100
|
-
|
101
|
-
# ... program ...
|
102
|
-
|
103
|
-
binding.break # setup a breakpoint at this line
|
104
|
-
|
105
|
-
# ... rest of program ...
|
106
|
-
```
|
166
|
+
You can see that two breakpoints are registered. Let's continue the program by `continue` command.
|
107
167
|
|
108
|
-
```
|
109
|
-
|
110
|
-
|
111
|
-
|
112
|
-
|
113
|
-
|
168
|
+
```shell
|
169
|
+
(rdbg) continue
|
170
|
+
[1, 7] in target.rb
|
171
|
+
1| a = 1
|
172
|
+
2| b = 2
|
173
|
+
=> 3| c = 3
|
174
|
+
4| d = 4
|
175
|
+
5| p [a, b, c, d]
|
176
|
+
6|
|
177
|
+
7| __END__
|
178
|
+
=>#0 <main> at target.rb:3
|
114
179
|
|
115
|
-
|
180
|
+
Stop by #0 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
|
116
181
|
|
182
|
+
(rdbg)
|
117
183
|
```
|
118
|
-
$ rdbg ~/src/rb/target.rb
|
119
184
|
|
120
|
-
|
121
|
-
|
122
|
-
|
123
|
-
3| c = 3
|
124
|
-
4| p [a + b + c]
|
125
|
-
5|
|
126
|
-
--> #0 /home/ko1/src/rb/target.rb:1:in `<main>'
|
185
|
+
You can see that we can stop at line 3.
|
186
|
+
Let's see the local variables with `info` command, and continue.
|
187
|
+
You can also confirm that the program will suspend at line 5 and you can use `info` command again.
|
127
188
|
|
128
|
-
|
129
|
-
|
130
|
-
|
131
|
-
|
132
|
-
|
189
|
+
```shell
|
190
|
+
(rdbg) info
|
191
|
+
=>#0 <main> at target.rb:3
|
192
|
+
%self => main
|
193
|
+
a => 1
|
194
|
+
b => 2
|
195
|
+
c => nil
|
196
|
+
d => nil
|
133
197
|
|
134
|
-
(rdbg)
|
135
|
-
|
136
|
-
|
137
|
-
(rdbg) s # Step in ("s" is a short name of "step")
|
138
|
-
|
139
|
-
[1, 5] in /home/ko1/src/rb/target.rb
|
198
|
+
(rdbg) continue
|
199
|
+
[1, 7] in target.rb
|
140
200
|
1| a = 1
|
141
|
-
|
201
|
+
2| b = 2
|
142
202
|
3| c = 3
|
143
|
-
4|
|
144
|
-
|
145
|
-
|
146
|
-
|
147
|
-
|
203
|
+
4| d = 4
|
204
|
+
=> 5| p [a, b, c, d]
|
205
|
+
6|
|
206
|
+
7| __END__
|
207
|
+
=>#0 <main> at target.rb:5
|
148
208
|
|
149
|
-
|
150
|
-
1| a = 1
|
151
|
-
2| b = 2
|
152
|
-
=> 3| c = 3
|
153
|
-
4| p [a + b + c]
|
154
|
-
5|
|
155
|
-
--> #0 /home/ko1/src/rb/target.rb:3:in `<main>'
|
209
|
+
Stop by #1 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
|
156
210
|
|
157
|
-
(rdbg)
|
211
|
+
(rdbg) info
|
212
|
+
=>#0 <main> at target.rb:5
|
213
|
+
%self => main
|
214
|
+
a => 1
|
215
|
+
b => 2
|
216
|
+
c => 3
|
217
|
+
d => 4
|
158
218
|
|
159
|
-
|
160
|
-
|
161
|
-
2| b = 2
|
162
|
-
3| c = 3
|
163
|
-
=> 4| p [a + b + c]
|
164
|
-
5|
|
165
|
-
--> #0 /home/ko1/src/rb/target.rb:4:in `<main>'
|
166
|
-
|
167
|
-
(rdbg) info # Show all local variables
|
168
|
-
%self => main
|
169
|
-
a => 1
|
170
|
-
b => 2
|
171
|
-
c => 3
|
172
|
-
|
173
|
-
(rdbg) c # Continue the program ("c" is a short name of "continue")
|
174
|
-
[6]
|
219
|
+
(rdbg) continue
|
220
|
+
[1, 2, 3, 4]
|
175
221
|
```
|
176
222
|
|
177
|
-
|
223
|
+
By the way, using `rdbg` command you can suspend your application with `C-c` (SIGINT) and enter the debug console.
|
224
|
+
It will help that if you want to know what the program is doing.
|
178
225
|
|
179
|
-
|
226
|
+
### Use `rdbg` with commands written in Ruby
|
180
227
|
|
181
|
-
|
182
|
-
$ rdbg --open target.rb # or rdbg -O target.rb for shorthand
|
183
|
-
Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-5042)
|
184
|
-
```
|
228
|
+
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.
|
185
229
|
|
186
|
-
|
230
|
+
* Without `-c` option, `rdbg <name>` means that `<name>` is Ruby script and invoke it like `ruby <name>` with the debugger.
|
231
|
+
* With `-c` option, `rdbg -c <name>` means that `<name>` is command in `PATH` and simply invoke it with the debugger.
|
187
232
|
|
188
|
-
|
189
|
-
|
190
|
-
|
191
|
-
|
233
|
+
Examples:
|
234
|
+
* `rdbg -c -- rails server`
|
235
|
+
* `rdbg -c -- bundle exec ruby foo.rb`
|
236
|
+
* `rdbg -c -- bundle exec rake test`
|
237
|
+
* `rdbg -c -- ruby target.rb` is same as `rdbg target.rb`
|
192
238
|
|
193
|
-
|
239
|
+
NOTE: `--` is needed to separate the command line options for `rdbg` and invoking command. For example, `rdbg -c rake -T` is recognized like `rdbg -c -T -- rake`. It should be `rdbg -c -- rake -T`.
|
194
240
|
|
195
|
-
|
196
|
-
# target.rb
|
197
|
-
require 'debug/open' # open the debugger entry point by UNIX domain socket.
|
241
|
+
NOTE: If you want to use bundler (`bundle` command), you need to write `gem debug` line in your `Gemfile`.
|
198
242
|
|
199
|
-
|
243
|
+
### Using VSCode
|
200
244
|
|
201
|
-
|
202
|
-
DEBUGGER__.open # open the debugger entry point by UNIX domain socket.
|
203
|
-
# or DEBUGGER__.open_unix to specify UNIX domain socket.
|
204
|
-
```
|
245
|
+
Like other languages, you can use this debugger on the VSCode.
|
205
246
|
|
206
|
-
|
207
|
-
|
208
|
-
|
209
|
-
|
210
|
-
|
211
|
-
|
212
|
-
The debuggee process waits for debugger connection at the beginning of `target.rb` like that:
|
247
|
+
1. Install [VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg)
|
248
|
+
2. Open `.rb` file (e.g. `target.rb`)
|
249
|
+
3. Register breakpoints with "Toggle breakpoint" in Run menu (or type F9 key)
|
250
|
+
4. Choose "Start debugging" in "Run" menu (or type F5 key)
|
251
|
+
5. You will see a dialog "Debug command line" and you can choose your favorite command line your want to run.
|
252
|
+
6. Chosen command line is invoked with `rdbg -c` and VSCode shows the details at breakpoints.
|
213
253
|
|
214
|
-
|
215
|
-
$ rdbg -O ~/src/rb/target.rb
|
216
|
-
DEBUGGER: Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-29828)
|
217
|
-
DEBUGGER: wait for debugger connection...
|
218
|
-
```
|
254
|
+
Please refer [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) for operations on VSCode.
|
219
255
|
|
220
|
-
You can
|
256
|
+
You can configure the extension in `.vscode/launch.json`.
|
257
|
+
Please see the extension page for more details.
|
221
258
|
|
222
|
-
|
223
|
-
$ rdbg --attach # or rdbg -A for shorthand
|
224
|
-
|
225
|
-
[1, 4] in /home/ko1/src/rb/target.rb
|
226
|
-
1| (1..).each do |i|
|
227
|
-
=> 2| sleep 0.5
|
228
|
-
3| p i
|
229
|
-
4| end
|
230
|
-
--> #0 [C] /home/ko1/src/rb/target.rb:2:in `sleep'
|
231
|
-
#1 /home/ko1/src/rb/target.rb:2:in `block in <main>' {|i=17|}
|
232
|
-
#2 [C] /home/ko1/src/rb/target.rb:1:in `each'
|
233
|
-
# and 1 frames (use `bt' command for all frames)
|
234
|
-
|
235
|
-
(rdb)
|
236
|
-
```
|
259
|
+
## Remote debugging
|
237
260
|
|
238
|
-
|
261
|
+
You can use this debugger as a remote debugger. For example, it will help the following situations:
|
239
262
|
|
240
|
-
|
241
|
-
|
263
|
+
* Your application does not run on TTY and it is hard to use `binding.pry` or `binding.irb`.
|
264
|
+
* Your application is running on Docker container and there is no TTY.
|
265
|
+
* Your application is running as a daemon.
|
266
|
+
* Your application uses pipe for STDIN or STDOUT.
|
267
|
+
* Your application is running as a daemon and you want to query the running status (checking a backtrace and so on).
|
242
268
|
|
243
|
-
|
269
|
+
You can run your application as a remote debuggee and the remote debugger console can attach to the debuggee anytime.
|
244
270
|
|
245
|
-
|
246
|
-
* Set the environment variable `RUBY_DEBUG_NONSTOP=1`
|
271
|
+
### Invoke as a remote debuggee
|
247
272
|
|
248
|
-
|
273
|
+
There are two ways to invoke a script as remote debuggee: Use `rdbg --open` and require `debug/open` (or `debug/open_nonstop`).
|
249
274
|
|
250
|
-
|
251
|
-
$ rdbg --attach
|
252
|
-
Please select a debug session:
|
253
|
-
ruby-debug-ko1-19638
|
254
|
-
ruby-debug-ko1-19603
|
255
|
-
```
|
275
|
+
#### `rdbg --open` (or `rdbg -O` for short)
|
256
276
|
|
257
|
-
and
|
277
|
+
You can run a script with `rdbg --open target.rb` command and run a `target.rb` as a debuggee program. It also opens the network port and suspends at the beginning of `target.rb`.
|
258
278
|
|
259
|
-
```
|
260
|
-
$ rdbg --
|
279
|
+
```shell
|
280
|
+
$ exe/rdbg --open target.rb
|
281
|
+
DEBUGGER: Session start (pid: 7773)
|
282
|
+
DEBUGGER: Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773)
|
283
|
+
DEBUGGER: wait for debugger connection...
|
261
284
|
```
|
262
285
|
|
263
|
-
|
264
|
-
* `RUBY_DEBUG_SOCK_DIR` environment variable if available.
|
265
|
-
* `XDG_RUNTIME_DIR` environment variable if available.
|
266
|
-
* `$HOME/.ruby-debug-sock` if `$HOME` is available.
|
286
|
+
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).
|
267
287
|
|
268
|
-
|
288
|
+
You can connect to the debuggee with `rdbg --attach` command (`rdbg -A` for short).
|
269
289
|
|
270
|
-
|
271
|
-
|
272
|
-
|
290
|
+
```shell
|
291
|
+
$ rdbg -A
|
292
|
+
[1, 7] in target.rb
|
293
|
+
=> 1| a = 1
|
294
|
+
2| b = 2
|
295
|
+
3| c = 3
|
296
|
+
4| d = 4
|
297
|
+
5| p [a, b, c, d]
|
298
|
+
6|
|
299
|
+
7| __END__
|
300
|
+
=>#0 <main> at target.rb:1
|
273
301
|
|
302
|
+
(rdbg:remote)
|
274
303
|
```
|
275
|
-
$ rdbg -O --port=12345 target.rb
|
276
|
-
# or
|
277
|
-
$ rdbg --open --port=12345 target.rb
|
278
|
-
Debugger can attach via TCP/IP (localhost:12345)
|
279
|
-
```
|
280
|
-
|
281
|
-
#### (2) Use `-r debug/open` command line option
|
282
304
|
|
305
|
+
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.
|
283
306
|
|
284
|
-
|
285
|
-
$ RUBY_DEBUG_PORT=12345 ruby -r debug/open target.rb
|
286
|
-
Debugger can attach via TCP/IP (localhost:12345)
|
287
|
-
```
|
307
|
+
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.
|
288
308
|
|
289
|
-
|
309
|
+
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.
|
290
310
|
|
291
|
-
|
292
|
-
# target.rb
|
293
|
-
require 'debug/open' # open the debugger entry point.
|
294
|
-
```
|
311
|
+
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`.
|
295
312
|
|
296
|
-
|
313
|
+
To connect to the debuggee, you need to specify the port.
|
297
314
|
|
298
|
-
```
|
299
|
-
$
|
300
|
-
Debugger can attach via TCP/IP (localhost:12345)
|
315
|
+
```shell
|
316
|
+
$ rdbg --attach 12345
|
301
317
|
```
|
302
318
|
|
303
|
-
|
319
|
+
If you want to choose the host to bind, you can use `--host` option.
|
320
|
+
Note that all messages communicated between the debugger and the debuggee are *NOT* encrypted so please use remote debugging carefully.
|
304
321
|
|
305
|
-
|
306
|
-
# target.rb
|
307
|
-
require 'debug/server' # introduce remote debugging feature
|
308
|
-
DEBUGGER__.open(port: 12345)
|
309
|
-
# or DEBUGGER__.open_tcp(port: 12345)
|
310
|
-
```
|
322
|
+
#### `require 'debug/open'` in a program
|
311
323
|
|
312
|
-
|
313
|
-
$ ruby target.rb
|
314
|
-
Debugger can attach via TCP/IP (localhost:12345)
|
315
|
-
```
|
324
|
+
If you can modify the program, you can open debugging port by adding `require 'debug/open'` line in the program.
|
316
325
|
|
317
|
-
|
326
|
+
If you don't want to stop the program at the beginning, you can also use `require 'debug/open_nonstop'`.
|
327
|
+
Using `debug/open_nonstop` is useful if you want to open a backdoor to the application.
|
328
|
+
However, it is also danger because it can become another vulnerability.
|
329
|
+
Please use it carefully.
|
318
330
|
|
319
|
-
|
331
|
+
By default, UNIX domain socket is used for the debugging port. To use TCP/IP, you can set the `RUBY_DEBUG_PORT` environment variable.
|
320
332
|
|
321
|
-
```
|
322
|
-
$
|
323
|
-
$ rdbg --attach hostname 12345
|
333
|
+
```shell
|
334
|
+
$ RUBY_DEBUG_PORT=12345 ruby target.rb
|
324
335
|
```
|
325
336
|
|
326
|
-
|
327
|
-
|
328
|
-
If there are `~/.rdbgrc`, the file is loaded as initial scripts which contains debugger commands at the beginning of debug session. `RUBY_DEBUG_INIT_SCRIPT` environment variable can specify the initial script file. You can write configurations in a file. For example, you can set break points with `break file:123` in `~/.rdbgrc`.
|
337
|
+
## Configuration
|
329
338
|
|
330
|
-
|
339
|
+
You can configure the debugger's behavior with debug commands and environment variables.
|
340
|
+
When the debug session is started, initial scripts are loaded so you can put your favorite configurations in the initial scripts.
|
331
341
|
|
332
|
-
###
|
342
|
+
### Configuration list
|
333
343
|
|
334
|
-
You can configure debugger's
|
335
|
-
You can write any configuration into `~/.rdbgrc` like:
|
344
|
+
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.
|
336
345
|
|
337
346
|
```
|
347
|
+
# configuration example
|
338
348
|
config set log_level INFO
|
339
349
|
config set no_color true
|
340
350
|
```
|
341
351
|
|
342
352
|
|
353
|
+
|
343
354
|
* UI
|
344
355
|
* `RUBY_DEBUG_LOG_LEVEL` (`log_level`): Log level same as Logger (default: WARN)
|
345
356
|
* `RUBY_DEBUG_SHOW_SRC_LINES` (`show_src_lines`): Show n lines source code on breakpoint (default: 10 lines)
|
346
357
|
* `RUBY_DEBUG_SHOW_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2 frames)
|
347
|
-
* `RUBY_DEBUG_SHOW_INFO_LINES` (`show_info_lines`): Show n lines on info command (default: 10 lines, 0 for unlimited)
|
348
358
|
* `RUBY_DEBUG_USE_SHORT_PATH` (`use_short_path`): Show shoten PATH (like $(Gem)/foo.rb)
|
349
|
-
* `RUBY_DEBUG_SKIP_NOSRC` (`skip_nosrc`): Skip on no source code lines (default: false)
|
350
|
-
* `RUBY_DEBUG_SKIP_PATH` (`skip_path`): Skip showing frames for given paths (default: [])
|
351
359
|
* `RUBY_DEBUG_NO_COLOR` (`no_color`): Do not use colorize (default: false)
|
352
360
|
* `RUBY_DEBUG_NO_SIGINT_HOOK` (`no_sigint_hook`): Do not suspend on SIGINT (default: false)
|
361
|
+
* `RUBY_DEBUG_NO_RELINE` (`no_reline`): Do not use Reline library (default: false)
|
362
|
+
|
363
|
+
* CONTROL
|
364
|
+
* `RUBY_DEBUG_SKIP_PATH` (`skip_path`): Skip showing/entering frames for given paths (default: [])
|
365
|
+
* `RUBY_DEBUG_SKIP_NOSRC` (`skip_nosrc`): Skip on no source code lines (default: false)
|
366
|
+
* `RUBY_DEBUG_KEEP_ALLOC_SITE` (`keep_alloc_site`): Keep allocation site and p, pp shows it (default: false)
|
367
|
+
* `RUBY_DEBUG_POSTMORTEM` (`postmortem`): Enable postmortem debug (default: false)
|
368
|
+
* `RUBY_DEBUG_PARENT_ON_FORK` (`parent_on_fork`): Keep debugging parent process on fork (default: false)
|
369
|
+
* `RUBY_DEBUG_SIGDUMP_SIG` (`sigdump_sig`): Sigdump signal (default: disabled)
|
353
370
|
|
354
371
|
* BOOT
|
355
372
|
* `RUBY_DEBUG_NONSTOP` (`nonstop`): Nonstop mode
|
356
373
|
* `RUBY_DEBUG_INIT_SCRIPT` (`init_script`): debug command script path loaded at first stop
|
357
374
|
* `RUBY_DEBUG_COMMANDS` (`commands`): debug commands invoked at first stop. commands should be separated by ';;'
|
358
375
|
* `RUBY_DEBUG_NO_RC` (`no_rc`): ignore loading ~/.rdbgrc(.rb)
|
359
|
-
* `RUBY_DEBUG_HISTORY` (`history`): save and load history file (default: ~/.rdbg_history)
|
360
376
|
|
361
377
|
* REMOTE
|
362
378
|
* `RUBY_DEBUG_PORT` (`port`): TCP/IP remote debugging: port
|
@@ -365,9 +381,28 @@ config set no_color true
|
|
365
381
|
* `RUBY_DEBUG_SOCK_DIR` (`sock_dir`): UNIX Domain Socket remote debugging: socket directory
|
366
382
|
* `RUBY_DEBUG_COOKIE` (`cookie`): Cookie for negotiation
|
367
383
|
|
384
|
+
### Initial scripts
|
385
|
+
|
386
|
+
If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains debug commands) when the debug session is started.
|
387
|
+
|
388
|
+
* `RUBY_DEBUG_INIT_SCRIPT` environment variable can specify the initial script file.
|
389
|
+
* You can specify the initial script with `rdbg -x initial_script` (like gdb's `-x` option).
|
390
|
+
|
391
|
+
Initial scripts are useful to write your favorite configurations.
|
392
|
+
For example, you can set break points with `break file:123` in `~/.rdbgrc`.
|
393
|
+
|
394
|
+
If there are `~/.rdbgrc.rb` is available, it is also loaded as a ruby script at same timing.
|
395
|
+
|
368
396
|
## Debug command on the debug console
|
369
397
|
|
370
|
-
|
398
|
+
On the debug console, you can use the following debug commands.
|
399
|
+
|
400
|
+
There are additional features:
|
401
|
+
|
402
|
+
* `<expr>` without debug command is almost same as `pp <expr>`.
|
403
|
+
* 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`.
|
404
|
+
* 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.
|
405
|
+
* `Enter` without any input repeats the last command (useful when repeating `step`s).
|
371
406
|
* `Ctrl-D` is equal to `quit` command.
|
372
407
|
* [debug command compare sheet - Google Sheets](https://docs.google.com/spreadsheets/d/1TlmmUDsvwK4sSIyoMv-io52BUUz__R5wpu-ComXlsw0/edit?usp=sharing)
|
373
408
|
|
@@ -379,10 +414,16 @@ The `<...>` notation means the argument.
|
|
379
414
|
|
380
415
|
* `s[tep]`
|
381
416
|
* Step in. Resume the program until next breakable point.
|
417
|
+
* `s[tep] <n>`
|
418
|
+
* Step in, resume the program at `<n>`th breakable point.
|
382
419
|
* `n[ext]`
|
383
420
|
* Step over. Resume the program until next line.
|
421
|
+
* `n[ext] <n>`
|
422
|
+
* Step over, same as `step <n>`.
|
384
423
|
* `fin[ish]`
|
385
424
|
* Finish this frame. Resume the program until the current frame is finished.
|
425
|
+
* `fin[ish] <n>`
|
426
|
+
* Finish frames, same as `step <n>`.
|
386
427
|
* `c[ontinue]`
|
387
428
|
* Resume the program.
|
388
429
|
* `q[uit]` or `Ctrl-D`
|
@@ -447,11 +488,26 @@ The `<...>` notation means the argument.
|
|
447
488
|
* Note that edited file will not be reloaded.
|
448
489
|
* `edit <file>`
|
449
490
|
* Open <file> on the editor.
|
450
|
-
* `i[nfo]
|
491
|
+
* `i[nfo]`
|
492
|
+
* Show information about current frame (local/instance variables and defined constants).
|
493
|
+
* `i[nfo] l[ocal[s]]`
|
451
494
|
* Show information about the current frame (local variables)
|
452
495
|
* It includes `self` as `%self` and a return value as `%return`.
|
496
|
+
* `i[nfo] i[var[s]]` or `i[nfo] instance`
|
497
|
+
* Show information about insttance variables about `self`.
|
498
|
+
* `i[nfo] c[onst[s]]` or `i[nfo] constant[s]`
|
499
|
+
* Show information about accessible constants except toplevel constants.
|
500
|
+
* `i[nfo] g[lobal[s]]`
|
501
|
+
* Show information about global variables
|
502
|
+
* `i[nfo] ... </pattern/>`
|
503
|
+
* Filter the output with `</pattern/>`.
|
453
504
|
* `i[nfo] th[read[s]]`
|
454
505
|
* Show all threads (same as `th[read]`).
|
506
|
+
* `o[utline]` or `ls`
|
507
|
+
* Show you available methods, constants, local variables, and instance variables in the current scope.
|
508
|
+
* `o[utline] <expr>` or `ls <expr>`
|
509
|
+
* Show you available methods and instance variables of the given object.
|
510
|
+
* If the object is a class/module, it also lists its constants.
|
455
511
|
* `display`
|
456
512
|
* Show display setting.
|
457
513
|
* `display <expr>`
|
@@ -460,8 +516,6 @@ The `<...>` notation means the argument.
|
|
460
516
|
* Remove all display settings.
|
461
517
|
* `undisplay <displaynum>`
|
462
518
|
* Remove a specified display setting.
|
463
|
-
* `trace [on|off]`
|
464
|
-
* enable or disable line tracer.
|
465
519
|
|
466
520
|
### Frame control
|
467
521
|
|
@@ -480,11 +534,41 @@ The `<...>` notation means the argument.
|
|
480
534
|
* Evaluate like `p <expr>` on the current frame.
|
481
535
|
* `pp <expr>`
|
482
536
|
* Evaluate like `pp <expr>` on the current frame.
|
483
|
-
* `
|
537
|
+
* `eval <expr>`
|
484
538
|
* Evaluate `<expr>` on the current frame.
|
485
539
|
* `irb`
|
486
540
|
* Invoke `irb` on the current frame.
|
487
541
|
|
542
|
+
### Trace
|
543
|
+
|
544
|
+
* `trace`
|
545
|
+
* Show available tracers list.
|
546
|
+
* `trace line`
|
547
|
+
* Add a line tracer. It indicates line events.
|
548
|
+
* `trace call`
|
549
|
+
* Add a call tracer. It indicate call/return events.
|
550
|
+
* `trace exception`
|
551
|
+
* Add an exception tracer. It indicates raising exceptions.
|
552
|
+
* `trace object <expr>`
|
553
|
+
* Add an object tracer. It indicates that an object by `<expr>` is passed as a parameter or a receiver on method call.
|
554
|
+
* `trace ... </pattern/>`
|
555
|
+
* Indicates only matched events to `</pattern/>` (RegExp).
|
556
|
+
* `trace ... into: <file>`
|
557
|
+
* Save trace information into: `<file>`.
|
558
|
+
* `trace off <num>`
|
559
|
+
* Disable tracer specified by `<num>` (use `trace` command to check the numbers).
|
560
|
+
* `trace off [line|call|pass]`
|
561
|
+
* Disable all tracers. If `<type>` is provided, disable specified type tracers.
|
562
|
+
* `record`
|
563
|
+
* Show recording status.
|
564
|
+
* `record [on|off]`
|
565
|
+
* Start/Stop recording.
|
566
|
+
* `step back`
|
567
|
+
* Start replay. Step back with the last execution log.
|
568
|
+
* `s[tep]` does stepping forward with the last log.
|
569
|
+
* `step reset`
|
570
|
+
* Stop replay .
|
571
|
+
|
488
572
|
### Thread control
|
489
573
|
|
490
574
|
* `th[read]`
|
@@ -504,6 +588,8 @@ The `<...>` notation means the argument.
|
|
504
588
|
* Append `<val>` to `<name>` if it is an array.
|
505
589
|
* `config unset <name>`
|
506
590
|
* Set <name> to default.
|
591
|
+
* `source <file>`
|
592
|
+
* Evaluate lines in `<file>` as debug commands.
|
507
593
|
|
508
594
|
### Help
|
509
595
|
|
@@ -513,6 +599,83 @@ The `<...>` notation means the argument.
|
|
513
599
|
* Show help for the given command.
|
514
600
|
|
515
601
|
|
602
|
+
## Debugger API
|
603
|
+
|
604
|
+
### Start debugging
|
605
|
+
|
606
|
+
#### Start by requiring a library
|
607
|
+
|
608
|
+
You can start debugging without `rdbg` command by requiring the following libraries:
|
609
|
+
|
610
|
+
* `require 'debug'`: Same as `rdbg --nonstop --no-sigint-hook`.
|
611
|
+
* `require 'debug/start'`: Same as `rdbg`.
|
612
|
+
* `require 'debug/open'`: Same as `rdbg --open`.
|
613
|
+
* `require 'debug/open_nonstop'`: Same as `rdbg --open --nonstop`.
|
614
|
+
|
615
|
+
You need to require one of them at the very beginning of the application.
|
616
|
+
Using `ruby -r` (for example `ruby -r debug/start target.rb`) is another way to invoke with debugger.
|
617
|
+
|
618
|
+
NOTE: Until Ruby 3.0, there is old `lib/debug.rb` standard library. So that if this gem is not installed, or if `Gemfile` missed to list this gem and `bundle exec` is used, you will see the following output:
|
619
|
+
|
620
|
+
```shell
|
621
|
+
$ ruby -r debug -e0
|
622
|
+
.../2.7.3/lib/ruby/2.7.0/x86_64-linux/continuation.so: warning: callcc is obsolete; use Fiber instead
|
623
|
+
Debug.rb
|
624
|
+
Emacs support available.
|
625
|
+
|
626
|
+
.../2.7.3/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:162: if RUBYGEMS_ACTIVATION_MONITOR.respond_to?(:mon_owned?)
|
627
|
+
(rdb:1)
|
628
|
+
```
|
629
|
+
|
630
|
+
`lib/debug.rb` was not maintained well in recent years, and the purpose of this library is to rewrite old `lib/debug.rb` with recent techniques.
|
631
|
+
|
632
|
+
#### Start by method
|
633
|
+
|
634
|
+
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.
|
635
|
+
|
636
|
+
* `DEBUGGER__.start(**kw)`: start debug session with local console.
|
637
|
+
* `DEBUGGER__.open(**kw)`: open debug port with configuration (without configurations open with UNIX domain socket)
|
638
|
+
* `DEBUGGER__.open_unix(**kw)`: open debug port with UNIX domain socket
|
639
|
+
* `DEBUGGER__.open_tcp(**kw)`: open debug port with TCP/IP
|
640
|
+
|
641
|
+
For example:
|
642
|
+
|
643
|
+
```ruby
|
644
|
+
require 'debug/session'
|
645
|
+
DEBUGGER__.start(no_color: true, # disable colorize
|
646
|
+
log_level: 'INFO') # Change log_level to INFO
|
647
|
+
|
648
|
+
... # your application code
|
649
|
+
```
|
650
|
+
|
651
|
+
### `binding.break` method
|
652
|
+
|
653
|
+
`binding.break` (or `binding.b`) set breakpoints at written line. It also has several keywords.
|
654
|
+
|
655
|
+
If `do: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command and continue the program.
|
656
|
+
It is useful if you only want to call a debug command and don't want to stop there.
|
657
|
+
|
658
|
+
```
|
659
|
+
def initialize
|
660
|
+
@a = 1
|
661
|
+
binding.b do: 'watch @a'
|
662
|
+
end
|
663
|
+
```
|
664
|
+
|
665
|
+
On this case, register a watch breakpoint for `@a` and continue to run.
|
666
|
+
|
667
|
+
If `pre: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command, and keep suspend.
|
668
|
+
It is useful if you have operations before suspend.
|
669
|
+
|
670
|
+
```
|
671
|
+
def foo
|
672
|
+
binding.b pre: 'p bar()'
|
673
|
+
...
|
674
|
+
end
|
675
|
+
```
|
676
|
+
|
677
|
+
On this case, you can see the result of `bar()` every time you stop there.
|
678
|
+
|
516
679
|
## rdbg command help
|
517
680
|
|
518
681
|
```
|
@@ -524,6 +687,7 @@ Debug console mode:
|
|
524
687
|
-x, --init-script=FILE Execute debug command in the FILE.
|
525
688
|
--no-rc Ignore ~/.rdbgrc
|
526
689
|
--no-color Disable colorize
|
690
|
+
--no-sigint-hook Disable to trap SIGINT
|
527
691
|
-c, --command Enable command mode.
|
528
692
|
The first argument should be a command name in $PATH.
|
529
693
|
Example: 'rdbg -c bundle exec rake test'
|
@@ -531,7 +695,7 @@ Debug console mode:
|
|
531
695
|
-O, --open Start remote debugging with opening the network port.
|
532
696
|
If TCP/IP options are not given,
|
533
697
|
a UNIX domain socket will be used.
|
534
|
-
--sock-path=SOCK_PATH UNIX
|
698
|
+
--sock-path=SOCK_PATH UNIX Domain socket path
|
535
699
|
--port=PORT Listening TCP/IP port
|
536
700
|
--host=HOST Listening TCP/IP host
|
537
701
|
--cookie=COOKIE Set a cookie for connection
|
@@ -572,6 +736,7 @@ NOTE
|
|
572
736
|
# Contributing
|
573
737
|
|
574
738
|
Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/debug.
|
739
|
+
This debugger is not mature so your feedback will help us.
|
575
740
|
|
576
741
|
Please also check the [contributing guideline](/CONTRIBUTING.md).
|
577
742
|
|