debug 1.0.0.beta7 → 1.0.0.beta8
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/Gemfile +1 -0
- data/README.md +337 -237
- data/Rakefile +2 -1
- data/exe/rdbg +1 -1
- data/lib/debug/config.rb +3 -1
- data/lib/debug/console.rb +0 -3
- data/lib/debug/open.rb +1 -1
- data/lib/debug/open_nonstop.rb +15 -0
- data/lib/debug/server.rb +0 -4
- data/lib/debug/session.rb +0 -22
- data/lib/debug/{run.rb → start.rb} +1 -1
- data/lib/debug/version.rb +1 -1
- data/misc/README.md.erb +325 -223
- metadata +4 -3
data/Rakefile
CHANGED
@@ -17,7 +17,8 @@ end
|
|
17
17
|
|
18
18
|
task :default => [:clobber, :compile, :test, 'README.md']
|
19
19
|
|
20
|
-
file 'README.md' => ['lib/debug/session.rb', '
|
20
|
+
file 'README.md' => ['lib/debug/session.rb', 'lib/debug/config.rb',
|
21
|
+
'exe/rdbg', 'misc/README.md.erb'] do
|
21
22
|
require_relative 'lib/debug/session'
|
22
23
|
require 'erb'
|
23
24
|
File.write 'README.md', ERB.new(File.read('misc/README.md.erb')).result
|
data/exe/rdbg
CHANGED
@@ -8,7 +8,7 @@ when :start
|
|
8
8
|
require 'rbconfig'
|
9
9
|
|
10
10
|
libpath = File.join(File.expand_path(File.dirname(__dir__)), 'lib/debug')
|
11
|
-
start_mode = config[:remote] ? "open" : '
|
11
|
+
start_mode = config[:remote] ? "open" : 'start'
|
12
12
|
cmd = config[:command] ? ARGV.shift : RbConfig.ruby
|
13
13
|
|
14
14
|
env = ::DEBUGGER__.config_to_env_hash(config)
|
data/lib/debug/config.rb
CHANGED
@@ -47,7 +47,6 @@ module DEBUGGER__
|
|
47
47
|
init_script: ['RUBY_DEBUG_INIT_SCRIPT', "BOOT: debug command script path loaded at first stop"],
|
48
48
|
commands: ['RUBY_DEBUG_COMMANDS', "BOOT: debug commands invoked at first stop. commands should be separated by ';;'"],
|
49
49
|
no_rc: ['RUBY_DEBUG_NO_RC', "BOOT: ignore loading ~/.rdbgrc(.rb)", :bool],
|
50
|
-
history: ['RUBY_DEBUG_HISTORY', "BOOT: save and load history file (default: ~/.rdbg_history)"],
|
51
50
|
|
52
51
|
# remote setting
|
53
52
|
port: ['RUBY_DEBUG_PORT', "REMOTE: TCP/IP remote debugging: port"],
|
@@ -135,6 +134,9 @@ module DEBUGGER__
|
|
135
134
|
o.on('--no-color', 'Disable colorize') do
|
136
135
|
config[:no_color] = true
|
137
136
|
end
|
137
|
+
o.on('--no-sigint-hook', 'Disable to trap SIGINT') do
|
138
|
+
config[:no_sigint_hook] = true
|
139
|
+
end
|
138
140
|
|
139
141
|
o.on('-c', '--command', 'Enable command mode.',
|
140
142
|
'The first argument should be a command name in $PATH.',
|
data/lib/debug/console.rb
CHANGED
data/lib/debug/open.rb
CHANGED
@@ -0,0 +1,15 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
#
|
3
|
+
# Open the door for the debugger to connect.
|
4
|
+
# Unlike debug/open, it does not stop at the beginning of the program.
|
5
|
+
# Users can connect to debuggee program with "rdbg --attach" option or
|
6
|
+
# VSCode attach type.
|
7
|
+
#
|
8
|
+
# If RUBY_DEBUG_PORT envval is provided (digits), open TCP/IP port.
|
9
|
+
# Otherwise, UNIX domain socket is used.
|
10
|
+
#
|
11
|
+
|
12
|
+
require_relative 'session'
|
13
|
+
return unless defined?(DEBUGGER__)
|
14
|
+
|
15
|
+
DEBUGGER__.open(nonstop: true)
|
data/lib/debug/server.rb
CHANGED
data/lib/debug/session.rb
CHANGED
@@ -550,28 +550,6 @@ module DEBUGGER__
|
|
550
550
|
end
|
551
551
|
return :retry
|
552
552
|
|
553
|
-
# * `trace [on|off]`
|
554
|
-
# * enable or disable line tracer.
|
555
|
-
when 'trace'
|
556
|
-
case arg
|
557
|
-
when 'on'
|
558
|
-
dir = __dir__
|
559
|
-
@tracer ||= TracePoint.new(:call, :return, :b_call, :b_return, :line, :class, :end){|tp|
|
560
|
-
next if File.dirname(tp.path) == dir
|
561
|
-
next if tp.path == '<internal:trace_point>'
|
562
|
-
# Skip when `JSON.generate` is called during tests
|
563
|
-
next if tp.binding.eval('self').to_s == 'JSON' and ENV['RUBY_DEBUG_TEST_MODE']
|
564
|
-
# next if tp.event != :line
|
565
|
-
@ui.puts pretty_tp(tp)
|
566
|
-
}
|
567
|
-
@tracer.enable
|
568
|
-
when 'off'
|
569
|
-
@tracer && @tracer.disable
|
570
|
-
end
|
571
|
-
enabled = (@tracer && @tracer.enabled?) ? true : false
|
572
|
-
@ui.puts "Trace #{enabled ? 'on' : 'off'}"
|
573
|
-
return :retry
|
574
|
-
|
575
553
|
### Frame control
|
576
554
|
|
577
555
|
# * `f[rame]`
|
data/lib/debug/version.rb
CHANGED
data/misc/README.md.erb
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
|
@@ -29,331 +29,432 @@ $ gem install debug --pre
|
|
29
29
|
|
30
30
|
or specify `-Ipath/to/debug/lib` in `RUBYOPT` or each ruby command-line option, especially for debug this gem development.
|
31
31
|
|
32
|
-
If you use Bundler, write the following line to your Gemfile.
|
32
|
+
If you use Bundler, write the following line to your Gemfile.
|
33
33
|
|
34
34
|
```
|
35
35
|
gem "debug", ">= 1.0.0.beta"
|
36
36
|
```
|
37
37
|
|
38
|
+
# HOW TO USE
|
39
|
+
|
40
|
+
To use a debugger, roughly you will do the following steps:
|
41
|
+
|
42
|
+
1. Set breakpoints.
|
43
|
+
2. Run a program with the debugger.
|
44
|
+
3. At the breakpoint, enter the debugger console.
|
45
|
+
4. Use debug commands.
|
46
|
+
* Query the prgram status (e.g. `p lvar` to see the local variable `lvar`).
|
47
|
+
* Control program flow (e.g. move to the another line with `step`, to the next line with `next`).
|
48
|
+
* Set another breakpoints (e.g. `catch Exception` to set the breakpoints when `Exception` is raiesd).
|
49
|
+
* Change the configuration (e.g. `config set no_color true` to disable coloring).
|
50
|
+
* Continue the program (`c` or `continue`) and goto 3.
|
51
|
+
|
52
|
+
## Invoke with the debugger
|
53
|
+
|
54
|
+
There are several options for (1) and (2). Please choose your favorite way.
|
55
|
+
|
56
|
+
### Modify source code as `binding.pry` and `binding.irb`
|
57
|
+
|
58
|
+
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`.
|
59
|
+
After that, you run the program as usuall and you will enter the debug console at breakpoints you inserted.
|
60
|
+
|
61
|
+
The following example shows the demonstration of `binding.break`.
|
62
|
+
|
63
|
+
```shell
|
64
|
+
$ cat target.rb # Sample prgram
|
65
|
+
require 'debug'
|
66
|
+
|
67
|
+
a = 1
|
68
|
+
b = 2
|
69
|
+
binding.break # Program will stop here
|
70
|
+
c = 3
|
71
|
+
d = 4
|
72
|
+
binding.break # Program will stop here
|
73
|
+
p [a, b, c, d]
|
74
|
+
|
75
|
+
$ ruby target.rb # Run the program normally.
|
76
|
+
DEBUGGER: Session start (pid: 7604)
|
77
|
+
[1, 10] in target.rb
|
78
|
+
1| require 'debug'
|
79
|
+
2|
|
80
|
+
3| a = 1
|
81
|
+
4| b = 2
|
82
|
+
=> 5| binding.break # Now you can see it stops at this line
|
83
|
+
6| c = 3
|
84
|
+
7| d = 4
|
85
|
+
8| binding.break
|
86
|
+
9| p [a, b, c, d]
|
87
|
+
10|
|
88
|
+
=>#0 <main> at target.rb:5
|
89
|
+
|
90
|
+
(rdbg) info locals # You can show local variables
|
91
|
+
=>#0 <main> at target.rb:5
|
92
|
+
%self => main
|
93
|
+
a => 1
|
94
|
+
b => 2
|
95
|
+
c => nil
|
96
|
+
d => nil
|
97
|
+
|
98
|
+
(rdbg) continue # Continue the execution
|
99
|
+
[3, 11] in target.rb
|
100
|
+
3| a = 1
|
101
|
+
4| b = 2
|
102
|
+
5| binding.break
|
103
|
+
6| c = 3
|
104
|
+
7| d = 4
|
105
|
+
=> 8| binding.break # Again the program stops at here
|
106
|
+
9| p [a, b, c, d]
|
107
|
+
10|
|
108
|
+
11| __END__
|
109
|
+
=>#0 <main> at target.rb:8
|
110
|
+
|
111
|
+
(rdbg) info locals # And you can see the updated local variables
|
112
|
+
=>#0 <main> at target.rb:8
|
113
|
+
%self => main
|
114
|
+
a => 1
|
115
|
+
b => 2
|
116
|
+
c => 3
|
117
|
+
d => 4
|
118
|
+
|
119
|
+
(rdbg) continue
|
120
|
+
[1, 2, 3, 4]
|
121
|
+
```
|
122
|
+
|
123
|
+
### Invoke the prorgam from the debugger as a traditional debuggers
|
124
|
+
|
125
|
+
If you don't want to modify the source code, you can set breakpoints with a debug command `break` (`b` for short).
|
126
|
+
Using `rdbg` command to launch the program without any modifications, you can run the program with the debugger.
|
127
|
+
|
128
|
+
```shell
|
129
|
+
$ cat target.rb # Sample prgram
|
130
|
+
a = 1
|
131
|
+
b = 2
|
132
|
+
c = 3
|
133
|
+
d = 4
|
134
|
+
p [a, b, c, d]
|
135
|
+
|
136
|
+
$ rdbg target.rb # run like `ruby target.rb`
|
137
|
+
DEBUGGER: Session start (pid: 7656)
|
138
|
+
[1, 7] in target.rb
|
139
|
+
=> 1| a = 1
|
140
|
+
2| b = 2
|
141
|
+
3| c = 3
|
142
|
+
4| d = 4
|
143
|
+
5| p [a, b, c, d]
|
144
|
+
6|
|
145
|
+
7| __END__
|
146
|
+
=>#0 <main> at target.rb:1
|
147
|
+
|
148
|
+
(rdbg)
|
38
149
|
```
|
39
|
-
|
150
|
+
|
151
|
+
`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).
|
152
|
+
|
153
|
+
```shell
|
154
|
+
(rdbg) break 3 # set breakpoint at line 3
|
155
|
+
#0 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
|
156
|
+
|
157
|
+
(rdbg) b 5 # set breakpoint at line 5
|
158
|
+
#1 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
|
159
|
+
|
160
|
+
(rdbg) break # show all registered breakpoints
|
161
|
+
#0 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
|
162
|
+
#1 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
|
40
163
|
```
|
41
164
|
|
42
|
-
|
165
|
+
You can see that two breakpoints are registered. Let's continue the program by `continue` command.
|
43
166
|
|
44
|
-
|
167
|
+
```shell
|
168
|
+
(rdbg) continue
|
169
|
+
[1, 7] in target.rb
|
170
|
+
1| a = 1
|
171
|
+
2| b = 2
|
172
|
+
=> 3| c = 3
|
173
|
+
4| d = 4
|
174
|
+
5| p [a, b, c, d]
|
175
|
+
6|
|
176
|
+
7| __END__
|
177
|
+
=>#0 <main> at target.rb:3
|
45
178
|
|
46
|
-
|
179
|
+
Stop by #0 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
|
47
180
|
|
48
|
-
|
49
|
-
|
50
|
-
* (b-1) Open with UNIX domain socket
|
51
|
-
* (b-2) Open with TCP/IP port
|
181
|
+
(rdbg)
|
182
|
+
```
|
52
183
|
|
53
|
-
|
54
|
-
|
184
|
+
You can see that we can stop at line 3.
|
185
|
+
Let's see the local variables with `info` command, and continue.
|
186
|
+
You can also confirm that the program will suspend at line 5 and you can use `info` command again.
|
55
187
|
|
56
|
-
|
188
|
+
```shell
|
189
|
+
(rdbg) info
|
190
|
+
=>#0 <main> at target.rb:3
|
191
|
+
%self => main
|
192
|
+
a => 1
|
193
|
+
b => 2
|
194
|
+
c => nil
|
195
|
+
d => nil
|
57
196
|
|
58
|
-
|
59
|
-
|
60
|
-
|
197
|
+
(rdbg) continue
|
198
|
+
[1, 7] in target.rb
|
199
|
+
1| a = 1
|
200
|
+
2| b = 2
|
201
|
+
3| c = 3
|
202
|
+
4| d = 4
|
203
|
+
=> 5| p [a, b, c, d]
|
204
|
+
6|
|
205
|
+
7| __END__
|
206
|
+
=>#0 <main> at target.rb:5
|
61
207
|
|
62
|
-
|
208
|
+
Stop by #1 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
|
63
209
|
|
64
|
-
|
210
|
+
(rdbg) info
|
211
|
+
=>#0 <main> at target.rb:5
|
212
|
+
%self => main
|
213
|
+
a => 1
|
214
|
+
b => 2
|
215
|
+
c => 3
|
216
|
+
d => 4
|
65
217
|
|
66
|
-
|
67
|
-
|
68
|
-
$ rdbg -- -r foo -e expr # -- is required to make clear rdbg options and ruby's options
|
218
|
+
(rdbg) continue
|
219
|
+
[1, 2, 3, 4]
|
69
220
|
```
|
70
221
|
|
71
|
-
|
222
|
+
By the way, using `rdbg` command you can suspend your application with `C-c` (SIGINT) and enter the debug console.
|
223
|
+
It will help that if you want to know what the program is doing.
|
72
224
|
|
73
|
-
|
74
|
-
$ ruby -r debug/run target.rb
|
75
|
-
```
|
225
|
+
### Use `rdbg` with commands written in Ruby
|
76
226
|
|
77
|
-
|
227
|
+
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.
|
78
228
|
|
79
|
-
|
80
|
-
|
81
|
-
require 'debug/run' # start the debug console
|
229
|
+
* Without `-c` option, `rdbg <name>` means that `<name>` is Ruby script and invoke it like `ruby <name>` with the debugger.
|
230
|
+
* With `-c` option, `rdbg -c <name>` means that `<name>` is command in `PATH` and simply invoke it with the debugger.
|
82
231
|
|
83
|
-
|
84
|
-
|
232
|
+
Examples:
|
233
|
+
* `rdbg -c -- rails server`
|
234
|
+
* `rdbg -c -- bundle exec ruby foo.rb`
|
235
|
+
* `rdbg -c -- bundle exec rake test`
|
236
|
+
* `rdbg -c -- ruby target.rb` is same as `rdbg target.rb`
|
85
237
|
|
238
|
+
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`.
|
86
239
|
|
87
|
-
|
88
|
-
$ ruby target.rb
|
89
|
-
```
|
240
|
+
NOTE: If you want to use bundler (`bundle` command), you need to write `gem debug` line in your `Gemfile`.
|
90
241
|
|
91
|
-
|
92
|
-
The debuggee program (`target.rb`) is suspended at the beginning of `target.rb`.
|
242
|
+
### Using VSCode
|
93
243
|
|
244
|
+
Like other langauges, you can use this debugger on the VSCode.
|
94
245
|
|
95
|
-
|
246
|
+
1. Install [VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg)
|
247
|
+
2. Open `.rb` file (e.g. `target.rb`)
|
248
|
+
3. Register breakpoints with "Toggle breakpoint" in Run menu (or type F9 key)
|
249
|
+
4. Choose "Start debugging" in "Run" menu (or type F5 key)
|
250
|
+
5. You will see a dialog "Debug command line" and you can choose your favorite command line your want to run.
|
251
|
+
6. Chosed command line is invoked with `rdbg -c` and VSCode shows the details at breakponts.
|
96
252
|
|
97
|
-
|
98
|
-
# target.rb
|
99
|
-
require 'debug' # start the debugger
|
253
|
+
Plase refer [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) for operations on VSCode.
|
100
254
|
|
101
|
-
|
255
|
+
You can configure the extension in `.vscode/launch.json`.
|
256
|
+
Please see the extension page for more details.
|
102
257
|
|
103
|
-
|
258
|
+
## Remote debugging
|
104
259
|
|
105
|
-
|
106
|
-
```
|
260
|
+
You can use this debugger as a remote debugger. For example, it will help the following situations:
|
107
261
|
|
108
|
-
|
109
|
-
|
110
|
-
|
262
|
+
* Your application does not run on TTY and it is hard to use `binding.pry` or `binding.irb`.
|
263
|
+
* Your application is running on Docker container and there is no TTY.
|
264
|
+
* Your application is running as a daemon.
|
265
|
+
* Your application uses pipe for STDIN or STDOUT.
|
266
|
+
* Your application is running as a daemon and you want to query the running status (checking a backtrace and so on).
|
267
|
+
|
268
|
+
You can run your application as a remote debuggee and the remote debugger console can attach to the debugee anytime.
|
111
269
|
|
112
|
-
|
113
|
-
You can suspend the debuggee program and show the debug console with `Ctrl-C`.
|
270
|
+
### Invoke as a remote debuggee
|
114
271
|
|
115
|
-
|
272
|
+
There are two ways to invoke a script as remote debuggee: Use `rdbg --open` and require `debug/open` (or `debug/open_nonstop`).
|
116
273
|
|
274
|
+
#### `rdbg --open` (or `rdbg -O` for short)
|
275
|
+
|
276
|
+
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`.
|
277
|
+
|
278
|
+
```shell
|
279
|
+
$ exe/rdbg --open target.rb
|
280
|
+
DEBUGGER: Session start (pid: 7773)
|
281
|
+
DEBUGGER: Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773)
|
282
|
+
DEBUGGER: wait for debuger connection...
|
117
283
|
```
|
118
|
-
$ rdbg ~/src/rb/target.rb
|
119
284
|
|
120
|
-
|
285
|
+
By deafult, `rdbg --open` uses UNIX domain socket and generates path name automatically (`/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773` in this case).
|
286
|
+
|
287
|
+
You can connect to the debuggee with `rdbg --attach` command (`rdbg -A` for short).
|
288
|
+
|
289
|
+
```shell
|
290
|
+
$ rdbg -A
|
291
|
+
[1, 7] in target.rb
|
121
292
|
=> 1| a = 1
|
122
293
|
2| b = 2
|
123
294
|
3| c = 3
|
124
|
-
4|
|
125
|
-
5|
|
126
|
-
|
295
|
+
4| d = 4
|
296
|
+
5| p [a, b, c, d]
|
297
|
+
6|
|
298
|
+
7| __END__
|
299
|
+
=>#0 <main> at target.rb:1
|
127
300
|
|
128
|
-
(rdbg)
|
129
|
-
|
130
|
-
a => nil
|
131
|
-
b => nil
|
132
|
-
c => nil
|
301
|
+
(rdbg:remote)
|
302
|
+
```
|
133
303
|
|
134
|
-
|
135
|
-
=> nil
|
304
|
+
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.
|
136
305
|
|
137
|
-
|
306
|
+
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.
|
138
307
|
|
139
|
-
|
140
|
-
1| a = 1
|
141
|
-
=> 2| b = 2
|
142
|
-
3| c = 3
|
143
|
-
4| p [a + b + c]
|
144
|
-
5|
|
145
|
-
--> #0 /home/ko1/src/rb/target.rb:2:in `<main>'
|
308
|
+
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.
|
146
309
|
|
147
|
-
|
310
|
+
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`.
|
148
311
|
|
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>'
|
312
|
+
To connect to the debugeee, you need to specify the port.
|
156
313
|
|
157
|
-
|
158
|
-
|
159
|
-
[1, 5] in /home/ko1/src/rb/target.rb
|
160
|
-
1| a = 1
|
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]
|
314
|
+
```shell
|
315
|
+
$ rdbg --attach 12345
|
175
316
|
```
|
176
317
|
|
177
|
-
|
318
|
+
If you want to choose the host to bind, you can use `--host` option.
|
319
|
+
Note that all messages communicated between the debugger and the debuggee are *NOT* encrypted so please use remote debugging carefully.
|
178
320
|
|
179
|
-
####
|
321
|
+
#### `require 'debug/open'` in a program
|
180
322
|
|
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
|
-
```
|
323
|
+
If you can modify the program, you can open debugging port by adding `require 'debug/open'` line in the program.
|
185
324
|
|
186
|
-
|
325
|
+
If you don't want to stop the program at the beginning, you can also use `require 'debug/open_nonstop'`.
|
326
|
+
Using `debug/open_nonstop` is useful if you want to open a backdoor to the application.
|
327
|
+
However, it is also danger because it can become antoher vulnerability.
|
328
|
+
Please use it carefully.
|
187
329
|
|
188
|
-
|
189
|
-
|
190
|
-
|
330
|
+
By default, UNIX domain socket is used for the debugging port. To use TCP/IP, you can set the `RUBY_DEBUG_PORT` environment variable.
|
331
|
+
|
332
|
+
```shell
|
333
|
+
$ RUBY_DEBUG_PORT=12345 ruby target.rb
|
191
334
|
```
|
192
335
|
|
193
|
-
|
336
|
+
## Configuration
|
194
337
|
|
195
|
-
|
196
|
-
|
197
|
-
require 'debug/open' # open the debugger entry point by UNIX domain socket.
|
338
|
+
You can configure the debugger's behavior with debug commands and environment variables.
|
339
|
+
When the debug session is started, initial scripts are loaded so you can put your favorite configurations in the intial scripts.
|
198
340
|
|
199
|
-
|
341
|
+
### Configuration list
|
200
342
|
|
201
|
-
|
202
|
-
DEBUGGER__.open # open the debugger entry point by UNIX domain socket.
|
203
|
-
# or DEBUGGER__.open_unix to specify UNIX domain socket.
|
204
|
-
```
|
343
|
+
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.
|
205
344
|
|
206
345
|
```
|
207
|
-
|
208
|
-
|
346
|
+
# configulation example
|
347
|
+
config set log_level INFO
|
348
|
+
config set no_color true
|
209
349
|
```
|
210
350
|
|
211
|
-
|
212
|
-
|
351
|
+
<% cat = nil; DEBUGGER__::CONFIG_SET.each do |key, (env, desc)| %>
|
352
|
+
<% /\A(\w+): (.+)/ =~ desc; if cat != $1; cat = 1 %>
|
353
|
+
* <%= $1 %>
|
354
|
+
<% cat = $1; end %> * `<%= env %>` (`<%= key %>`): <%= $2 %><% end %>
|
213
355
|
|
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
|
-
```
|
356
|
+
### Initial scripts
|
219
357
|
|
220
|
-
|
358
|
+
If there is `~/.rdbgrc`, the file is loaded as an initial scripts which contains debug commands) when the debug session is started.
|
221
359
|
|
222
|
-
|
223
|
-
|
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
|
-
```
|
360
|
+
* `RUBY_DEBUG_INIT_SCRIPT` environment variable can specify the initial script file.
|
361
|
+
* You can specify the initial script with `rdbg -x initial_script` (like gdb's `-x` option).
|
237
362
|
|
238
|
-
|
363
|
+
Initial scripts are useful to write your favorite configurations.
|
364
|
+
For example, you can set break points with `break file:123` in `~/.rdbgrc`.
|
239
365
|
|
240
|
-
|
241
|
-
You can re-connect to the debuggee process by `rdbg -A` command again, and the debuggee process suspends the execution (and debugger can input any debug commands).
|
366
|
+
If there are `~/.rdbgrc.rb` is available, it is also loaded as a ruby script at same timing.
|
242
367
|
|
243
|
-
|
368
|
+
## Debug command on the debug console
|
244
369
|
|
245
|
-
|
246
|
-
* Set the environment variable `RUBY_DEBUG_NONSTOP=1`
|
370
|
+
On the debug console, you can use the following debug commands.
|
247
371
|
|
248
|
-
|
372
|
+
* `Enter` repeats the last command (useful when repeating `step`s).
|
373
|
+
* `Ctrl-D` is equal to `quit` command.
|
374
|
+
* [debug command compare sheet - Google Sheets](https://docs.google.com/spreadsheets/d/1TlmmUDsvwK4sSIyoMv-io52BUUz__R5wpu-ComXlsw0/edit?usp=sharing)
|
249
375
|
|
250
|
-
|
251
|
-
|
252
|
-
|
253
|
-
ruby-debug-ko1-19638
|
254
|
-
ruby-debug-ko1-19603
|
255
|
-
```
|
376
|
+
You can use the following debug commands. Each command should be written in 1 line.
|
377
|
+
The `[...]` notation means this part can be eliminate. For example, `s[tep]` means `s` or `step` are valid command. `ste` is not valid.
|
378
|
+
The `<...>` notation means the argument.
|
256
379
|
|
257
|
-
|
380
|
+
<%= DEBUGGER__.help %>
|
258
381
|
|
259
|
-
|
260
|
-
$ rdbg --attach ruby-debug-ko1-19638
|
261
|
-
```
|
382
|
+
## Debugger API
|
262
383
|
|
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.
|
384
|
+
### Start debugging
|
267
385
|
|
268
|
-
|
386
|
+
#### Start by requiring a library
|
269
387
|
|
270
|
-
You can
|
388
|
+
You can start debugging without `rdbg` command by requiring the following libraries:
|
271
389
|
|
272
|
-
|
390
|
+
* `require 'debug'`: Same as `rdbg --nonstop --no-sigint-hook`.
|
391
|
+
* `require 'debug/start'`: Same as `rdbg`.
|
392
|
+
* `require 'debug/open'`: Same as `rdbg --open`.
|
393
|
+
* `require 'debug/open_nonstop'`: Same as `rdbg --open --nonstop`.
|
273
394
|
|
274
|
-
|
275
|
-
|
276
|
-
# or
|
277
|
-
$ rdbg --open --port=12345 target.rb
|
278
|
-
Debugger can attach via TCP/IP (localhost:12345)
|
279
|
-
```
|
395
|
+
You need to require one of them at the very beginning of the application.
|
396
|
+
Using `ruby -r` (for example `ruby -r debug/start target.rb`) is another way to invoke with debugger.
|
280
397
|
|
281
|
-
|
398
|
+
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 `bunde exec` is used, you will see the following output:
|
282
399
|
|
400
|
+
```shell
|
401
|
+
$ ruby -r debug -e0
|
402
|
+
.../2.7.3/lib/ruby/2.7.0/x86_64-linux/continuation.so: warning: callcc is obsolete; use Fiber instead
|
403
|
+
Debug.rb
|
404
|
+
Emacs support available.
|
283
405
|
|
284
|
-
|
285
|
-
|
286
|
-
Debugger can attach via TCP/IP (localhost:12345)
|
406
|
+
.../2.7.3/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:162: if RUBYGEMS_ACTIVATION_MONITOR.respond_to?(:mon_owned?)
|
407
|
+
(rdb:1)
|
287
408
|
```
|
288
409
|
|
289
|
-
|
410
|
+
`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.
|
290
411
|
|
291
|
-
|
292
|
-
# target.rb
|
293
|
-
require 'debug/open' # open the debugger entry point.
|
294
|
-
```
|
412
|
+
#### Start by method
|
295
413
|
|
296
|
-
|
414
|
+
After loading `debug/session`, you can start debug session with the following methods. They are convinient if you want to specifies debug configrations in your program.
|
297
415
|
|
298
|
-
|
299
|
-
|
300
|
-
|
301
|
-
|
416
|
+
* `DEBUGGER__.start(**kw)`: start debug session with local console.
|
417
|
+
* `DEBUGGER__.open(**kw)`: open debug port with configuration (without configurations open with UNIX domain socket)
|
418
|
+
* `DEBUGGER__.open_unix(**kw)`: open debug port with UNIX domain socket
|
419
|
+
* `DEBUGGER__.open_tcp(**kw)`: open debug port with TCP/IP
|
302
420
|
|
303
|
-
|
421
|
+
For example:
|
304
422
|
|
305
423
|
```ruby
|
306
|
-
|
307
|
-
|
308
|
-
|
309
|
-
# or DEBUGGER__.open_tcp(port: 12345)
|
310
|
-
```
|
424
|
+
require 'debug/session'
|
425
|
+
DEBUGGER__.start(no_color: true, # disable colorize
|
426
|
+
log_level: 'INFO') # Change log_level to INFO
|
311
427
|
|
428
|
+
... # your application code
|
312
429
|
```
|
313
|
-
$ ruby target.rb
|
314
|
-
Debugger can attach via TCP/IP (localhost:12345)
|
315
|
-
```
|
316
430
|
|
317
|
-
|
431
|
+
### `binding.break` method
|
432
|
+
|
433
|
+
`binding.break` (or `binding.b`) set breakpoints at written line. It also has several keywords.
|
318
434
|
|
319
|
-
|
435
|
+
If `do: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command and continue the program.
|
436
|
+
It is useful if you only want to call a debug command and don't want to stop there.
|
320
437
|
|
321
438
|
```
|
322
|
-
|
323
|
-
|
439
|
+
def initialzie
|
440
|
+
@a = 1
|
441
|
+
binding.b do: 'watch @a'
|
442
|
+
end
|
324
443
|
```
|
325
444
|
|
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`.
|
445
|
+
On this case, register a watch breakpont for `@a` and continue to run.
|
329
446
|
|
330
|
-
If
|
331
|
-
|
332
|
-
### Configurations
|
333
|
-
|
334
|
-
You can configure debugger's setting with environment variables and `config` command.
|
335
|
-
You can write any configuration into `~/.rdbgrc` like:
|
447
|
+
If `pre: 'command'` is specified, the debuger suspends the program and run the `command` as a debug command, and keep suspend.
|
448
|
+
It is useful if you have operations before suspend.
|
336
449
|
|
337
450
|
```
|
338
|
-
|
339
|
-
|
451
|
+
def foo
|
452
|
+
binding.b pre: 'p bar()'
|
453
|
+
...
|
454
|
+
end
|
340
455
|
```
|
341
|
-
<% cat = nil; DEBUGGER__::CONFIG_SET.each do |key, (env, desc)| %>
|
342
|
-
<% /\A(\w+): (.+)/ =~ desc; if cat != $1; cat = 1 %>
|
343
|
-
* <%= $1 %>
|
344
|
-
<% cat = $1; end %> * `<%= env %>` (`<%= key %>`): <%= $2 %><% end %>
|
345
|
-
|
346
|
-
## Debug command on the debug console
|
347
456
|
|
348
|
-
|
349
|
-
* `Ctrl-D` is equal to `quit` command.
|
350
|
-
* [debug command compare sheet - Google Sheets](https://docs.google.com/spreadsheets/d/1TlmmUDsvwK4sSIyoMv-io52BUUz__R5wpu-ComXlsw0/edit?usp=sharing)
|
351
|
-
|
352
|
-
You can use the following debug commands. Each command should be written in 1 line.
|
353
|
-
The `[...]` notation means this part can be eliminate. For example, `s[tep]` means `s` or `step` are valid command. `ste` is not valid.
|
354
|
-
The `<...>` notation means the argument.
|
355
|
-
|
356
|
-
<%= DEBUGGER__.help %>
|
457
|
+
On this case, you can see the result of `bar()` everytime when you stops there.
|
357
458
|
|
358
459
|
## rdbg command help
|
359
460
|
|
@@ -364,6 +465,7 @@ The `<...>` notation means the argument.
|
|
364
465
|
# Contributing
|
365
466
|
|
366
467
|
Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/debug.
|
468
|
+
This debugger is not mature so your feedback will help us.
|
367
469
|
|
368
470
|
Please also check the [contributing guideline](/CONTRIBUTING.md).
|
369
471
|
|