debug 1.0.0.beta4 → 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/.github/workflows/ruby.yml +34 -0
- data/.gitignore +1 -0
- data/CONTRIBUTING.md +239 -0
- data/Gemfile +2 -1
- data/README.md +424 -215
- data/Rakefile +2 -1
- data/TODO.md +0 -6
- data/bin/gentest +22 -0
- data/debug.gemspec +2 -0
- data/exe/rdbg +14 -11
- data/ext/debug/debug.c +9 -8
- data/lib/debug.rb +3 -0
- data/lib/debug/breakpoint.rb +101 -43
- data/lib/debug/client.rb +55 -13
- data/lib/debug/color.rb +76 -0
- data/lib/debug/config.rb +130 -39
- data/lib/debug/console.rb +24 -3
- data/lib/debug/frame_info.rb +63 -31
- data/lib/debug/open.rb +4 -1
- data/lib/debug/open_nonstop.rb +15 -0
- data/lib/debug/server.rb +90 -32
- data/lib/debug/server_dap.rb +607 -0
- data/lib/debug/session.rb +461 -174
- data/lib/debug/source_repository.rb +55 -33
- data/lib/debug/start.rb +5 -0
- data/lib/debug/thread_client.rb +176 -59
- data/lib/debug/version.rb +3 -1
- data/misc/README.md.erb +351 -204
- metadata +23 -4
- data/lib/debug/run.rb +0 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: df98b8b5fd353be1aad11534d3180e9ae4b753de6e7ca95c3568d79e952e4770
|
4
|
+
data.tar.gz: 600580327ace5a5feb37df85e3d0569d17ee55a118dab0d05513452745211b2a
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 3a8b1ba471ca0169bc243e7a97600160317d041c022452b00fc0c2729939bc5ea907f52293cfa62dcf5d3be95cbd3c89ed9ebe2d49221e228f5588834378abdd
|
7
|
+
data.tar.gz: ee7524b1fb4040472ca7e7d9c760f92200dfe0f94d034877c3d23ea0f940f2a8f9d67310a756fa287ecf6b80c60e7d221215d1b150798f49a3fc627c7b9635d7
|
@@ -0,0 +1,34 @@
|
|
1
|
+
# This workflow uses actions that are not certified by GitHub.
|
2
|
+
# They are provided by a third-party and are governed by
|
3
|
+
# separate terms of service, privacy policy, and support
|
4
|
+
# documentation.
|
5
|
+
# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
|
6
|
+
# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
|
7
|
+
|
8
|
+
name: Ruby
|
9
|
+
|
10
|
+
on:
|
11
|
+
push:
|
12
|
+
branches: [ master ]
|
13
|
+
pull_request:
|
14
|
+
branches: [ master ]
|
15
|
+
|
16
|
+
jobs:
|
17
|
+
test:
|
18
|
+
|
19
|
+
runs-on: ubuntu-latest
|
20
|
+
strategy:
|
21
|
+
matrix:
|
22
|
+
ruby-version: ['2.6', '2.7', '3.0', 'head', 'debug']
|
23
|
+
|
24
|
+
steps:
|
25
|
+
- uses: actions/checkout@v2
|
26
|
+
- name: Set up Ruby
|
27
|
+
# To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
|
28
|
+
# change this to (see https://github.com/ruby/setup-ruby#versioning):
|
29
|
+
uses: ruby/setup-ruby@v1
|
30
|
+
with:
|
31
|
+
ruby-version: ${{ matrix.ruby-version }}
|
32
|
+
bundler-cache: true # runs 'bundle install' and caches installed gems automatically
|
33
|
+
- name: Run tests
|
34
|
+
run: bundle exec rake
|
data/.gitignore
CHANGED
data/CONTRIBUTING.md
CHANGED
@@ -1,3 +1,242 @@
|
|
1
|
+
## Set Up a Development Environment
|
2
|
+
|
3
|
+
1. `$ git clone git@github.com:ruby/debug.git`
|
4
|
+
2. `$ bundle install`
|
5
|
+
3. `$ rake` - this will
|
6
|
+
- Compile the C extension locally (which can also be done solely with `rake compile`).
|
7
|
+
- Run tests.
|
8
|
+
- Re-generate `README.md`.
|
9
|
+
|
10
|
+
If you spot any problem, please open an issue.
|
11
|
+
|
12
|
+
## Run Tests
|
13
|
+
|
14
|
+
### Run all tests
|
15
|
+
|
16
|
+
```bash
|
17
|
+
$ rake test
|
18
|
+
```
|
19
|
+
|
20
|
+
### Run specific test(s)
|
21
|
+
|
22
|
+
|
23
|
+
```bash
|
24
|
+
$ ruby test/debug/bp_test.rb # run all tests in the specified file
|
25
|
+
$ ruby test/debug/bp_test.rb -h # to see all the test options
|
26
|
+
```
|
27
|
+
|
28
|
+
## Generate Tests
|
29
|
+
There is a test generator in `debug.rb` project to make it easier to write tests.
|
30
|
+
### Quickstart
|
31
|
+
This section shows you how to create test file by test generator. For more advanced informations on creating tests, please take a look at [gentest options](#gentest-options). (You can also check by `$bin/gentest -h`)
|
32
|
+
#### 1. Create a target file for debuggee.
|
33
|
+
Let's say, we created `target.rb` which is located in top level directory of debugger.
|
34
|
+
```ruby
|
35
|
+
module Foo
|
36
|
+
class Bar
|
37
|
+
def self.a
|
38
|
+
"hello"
|
39
|
+
end
|
40
|
+
end
|
41
|
+
Bar.a
|
42
|
+
bar = Bar.new
|
43
|
+
end
|
44
|
+
```
|
45
|
+
#### 2. Run `gentest` as shown in the example below.
|
46
|
+
```shell
|
47
|
+
$ bin/gentest target.rb
|
48
|
+
```
|
49
|
+
#### 3. Debugger will be executed. You can type any debug commands.
|
50
|
+
```shell
|
51
|
+
$ bin/gentest target.rb
|
52
|
+
[1, 9] in ~/workspace/debug/target.rb
|
53
|
+
=> 1| module Foo
|
54
|
+
2| class Bar
|
55
|
+
3| def self.a
|
56
|
+
4| "hello"
|
57
|
+
5| end
|
58
|
+
6| end
|
59
|
+
7| Bar.a
|
60
|
+
8| bar = Bar.new
|
61
|
+
9| end
|
62
|
+
=>#0 <main> at ~/workspace/debug/target.rb:1
|
63
|
+
INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:1","line":1}
|
64
|
+
|
65
|
+
(rdbg)s
|
66
|
+
s
|
67
|
+
[1, 9] in ~/workspace/debug/target.rb
|
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
|
+
=>#0 <module:Foo> at ~/workspace/debug/target.rb:2
|
78
|
+
#1 <main> at ~/workspace/debug/target.rb:1
|
79
|
+
INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:2","line":2}
|
80
|
+
|
81
|
+
(rdbg)n
|
82
|
+
n
|
83
|
+
[1, 9] in ~/workspace/debug/target.rb
|
84
|
+
1| module Foo
|
85
|
+
2| class Bar
|
86
|
+
=> 3| def self.a
|
87
|
+
4| "hello"
|
88
|
+
5| end
|
89
|
+
6| end
|
90
|
+
7| Bar.a
|
91
|
+
8| bar = Bar.new
|
92
|
+
9| end
|
93
|
+
=>#0 <class:Bar> at ~/workspace/debug/target.rb:3
|
94
|
+
#1 <module:Foo> at ~/workspace/debug/target.rb:2
|
95
|
+
#2 <main> at ~/workspace/debug/target.rb:1
|
96
|
+
INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:3","line":3}
|
97
|
+
|
98
|
+
(rdbg)b 7
|
99
|
+
b 7
|
100
|
+
INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:3","line":3}
|
101
|
+
|
102
|
+
(rdbg)c
|
103
|
+
c
|
104
|
+
[2, 9] in ~/workspace/debug/target.rb
|
105
|
+
2| class Bar
|
106
|
+
3| def self.a
|
107
|
+
4| "hello"
|
108
|
+
5| end
|
109
|
+
6| end
|
110
|
+
=> 7| Bar.a
|
111
|
+
8| bar = Bar.new
|
112
|
+
9| end
|
113
|
+
=>#0 <module:Foo> at ~/workspace/debug/target.rb:7
|
114
|
+
#1 <main> at ~/workspace/debug/target.rb:1
|
115
|
+
|
116
|
+
Stop by #0 BP - Line /Users/naotto/workspace/debug/target.rb:7 (line)
|
117
|
+
INTERNAL_INFO: {"location":"~/workspace/debug/target.rb:7","line":7}
|
118
|
+
|
119
|
+
(rdbg)q!
|
120
|
+
q!
|
121
|
+
```
|
122
|
+
#### 4. The test file will be created as `test/debug/foo_test.rb`.
|
123
|
+
If the file already exists, **only method** will be added to it.
|
124
|
+
```ruby
|
125
|
+
# frozen_string_literal: true
|
126
|
+
|
127
|
+
require_relative '../support/test_case'
|
128
|
+
|
129
|
+
module DEBUGGER__
|
130
|
+
class FooTest < TestCase
|
131
|
+
def program
|
132
|
+
<<~RUBY
|
133
|
+
1| module Foo
|
134
|
+
1| class Bar
|
135
|
+
2| def self.a
|
136
|
+
3| "hello"
|
137
|
+
4| end
|
138
|
+
5| end
|
139
|
+
6| Bar.a
|
140
|
+
7| bar = Bar.new
|
141
|
+
8| end
|
142
|
+
RUBY
|
143
|
+
end
|
144
|
+
|
145
|
+
def test_foo
|
146
|
+
debug_code(program) do
|
147
|
+
type 's'
|
148
|
+
assert_line_num 2
|
149
|
+
assert_line_text([
|
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 <module:Foo> at .*/,
|
161
|
+
/ #1 <main> at .*/
|
162
|
+
])
|
163
|
+
type 'n'
|
164
|
+
assert_line_num 3
|
165
|
+
assert_line_text([
|
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 <class:Bar> at .*/,
|
177
|
+
/ #1 <module:Foo> at .*/,
|
178
|
+
/ #2 <main> at .*/
|
179
|
+
])
|
180
|
+
type 'b 7'
|
181
|
+
assert_line_text(//)
|
182
|
+
type 'c'
|
183
|
+
assert_line_num 7
|
184
|
+
assert_line_text([
|
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 <module:Foo> at .*/,
|
195
|
+
/ #1 <main> at .*/,
|
196
|
+
//,
|
197
|
+
/Stop by #0 BP - Line .*/
|
198
|
+
])
|
199
|
+
type 'q!'
|
200
|
+
end
|
201
|
+
end
|
202
|
+
end
|
203
|
+
end
|
204
|
+
```
|
205
|
+
|
206
|
+
#### gentest options
|
207
|
+
You can get more information about `gentest` here.
|
208
|
+
|
209
|
+
The default method name is `test_foo` and the class name is `FooTest`. The file name will be `[Lowercase letters with "Test" removed from the class name]_test.rb`.
|
210
|
+
```shell
|
211
|
+
# run without any options(test method name will be `test_foo`, class name will be `FooTest`, file name will be `foo_test.rb`)
|
212
|
+
$ bin/gentest target.rb
|
213
|
+
# specify the class name(test method name will be `test_foo`, class name will be `StepTest`, file name will be `step_test.rb`)
|
214
|
+
$ bin/gentest target.rb -c StepTest
|
215
|
+
# specify the method name(test method name will be `test_step`, class name will be `FooTest`, file name will be `foo_test.rb`)
|
216
|
+
$ bin/gentest target.rb -m test_step
|
217
|
+
# specify class name and method name(test method name will be `test_step`, class name will be `StepTest`, file name will be `step_test.rb`.)
|
218
|
+
$ bin/gentest target.rb -c StepTest -m test_step
|
219
|
+
```
|
220
|
+
|
221
|
+
## To Update README
|
222
|
+
|
223
|
+
This project generates `README.md` from the template `misc/README.md.erb`
|
224
|
+
|
225
|
+
So **do not** directly update `README.md`. Instead, you should update the template's source and run
|
226
|
+
|
227
|
+
```bash
|
228
|
+
$ rake
|
229
|
+
```
|
230
|
+
|
231
|
+
to reflect the changes on `README.md`.
|
232
|
+
|
233
|
+
|
234
|
+
### When to re-generate `README.md`
|
235
|
+
|
236
|
+
- After updating `misc/README.md.erb`.
|
237
|
+
- After updating `rdbg` executable's options.
|
238
|
+
- After updating comments of debugger's commands.
|
239
|
+
|
1
240
|
## Manually Test Your Changes
|
2
241
|
|
3
242
|
You can manually test your changes with a simple Ruby script + a line of command. The following example will help you check:
|
data/Gemfile
CHANGED
data/README.md
CHANGED
@@ -1,3 +1,5 @@
|
|
1
|
+
[![Ruby](https://github.com/ruby/debug/actions/workflows/ruby.yml/badge.svg?branch=master)](https://github.com/ruby/debug/actions/workflows/ruby.yml?query=branch%3Amaster)
|
2
|
+
|
1
3
|
# debug.rb
|
2
4
|
|
3
5
|
This library provides debugging functionality to Ruby.
|
@@ -9,8 +11,8 @@ New debug.rb has several advantages:
|
|
9
11
|
* Remote debugging: Support remote debugging natively.
|
10
12
|
* UNIX domain socket
|
11
13
|
* TCP/IP
|
12
|
-
* VSCode/DAP integration (
|
13
|
-
* Extensible: application can introduce debugging support with several
|
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 ways:
|
14
16
|
* By `rdbg` command
|
15
17
|
* By loading libraries with `-r` command line option
|
16
18
|
* By calling Ruby's method explicitly
|
@@ -27,283 +29,367 @@ $ gem install debug --pre
|
|
27
29
|
|
28
30
|
or specify `-Ipath/to/debug/lib` in `RUBYOPT` or each ruby command-line option, especially for debug this gem development.
|
29
31
|
|
30
|
-
|
31
|
-
|
32
|
-
## Invoke with debugger
|
32
|
+
If you use Bundler, write the following line to your Gemfile.
|
33
33
|
|
34
|
-
|
34
|
+
```
|
35
|
+
gem "debug", ">= 1.0.0.beta"
|
36
|
+
```
|
35
37
|
|
36
|
-
|
37
|
-
|
38
|
-
|
39
|
-
|
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
|
+
```
|
40
122
|
|
41
|
-
|
42
|
-
(b-2) is also useful when you don't have a ssh access for the Ruby process.
|
123
|
+
### Invoke the prorgam from the debugger as a traditional debuggers
|
43
124
|
|
44
|
-
|
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.
|
45
127
|
|
46
|
-
|
47
|
-
|
48
|
-
|
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]
|
49
135
|
|
50
|
-
|
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
|
51
147
|
|
148
|
+
(rdbg)
|
52
149
|
```
|
53
|
-
# (1) Use `rdbg` command
|
54
|
-
$ rdbg target.rb
|
55
|
-
$ rdbg -- -r foo -e expr # -- is required to make clear rdbg options and ruby's options
|
56
|
-
|
57
|
-
# (2) Use `-r debug/run` command line option
|
58
|
-
|
59
|
-
$ ruby -r debug/run target.rb
|
60
|
-
|
61
|
-
# (3) Write `require 'debug...' in .rb files
|
62
150
|
|
63
|
-
|
64
|
-
require 'debug/run' # start the debug console
|
65
|
-
... rest of program ...
|
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).
|
66
152
|
|
67
|
-
|
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)
|
68
156
|
|
69
|
-
|
70
|
-
|
71
|
-
DEBUGGER__.console # and start the debug console
|
72
|
-
... rest of program ...
|
157
|
+
(rdbg) b 5 # set breakpoint at line 5
|
158
|
+
#1 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
|
73
159
|
|
74
|
-
|
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)
|
75
163
|
```
|
76
164
|
|
77
|
-
|
78
|
-
The debuggee program (`target.rb`) is suspended at the beginning of `target.rb`.
|
165
|
+
You can see that two breakpoints are registered. Let's continue the program by `continue` command.
|
79
166
|
|
80
|
-
|
81
|
-
|
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
|
82
178
|
|
83
|
-
|
179
|
+
Stop by #0 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
|
84
180
|
|
181
|
+
(rdbg)
|
85
182
|
```
|
86
|
-
$ rdbg ~/src/rb/target.rb
|
87
183
|
|
88
|
-
|
89
|
-
|
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.
|
187
|
+
|
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
|
196
|
+
|
197
|
+
(rdbg) continue
|
198
|
+
[1, 7] in target.rb
|
199
|
+
1| a = 1
|
90
200
|
2| b = 2
|
91
201
|
3| c = 3
|
92
|
-
4|
|
93
|
-
|
94
|
-
|
95
|
-
|
96
|
-
|
97
|
-
|
98
|
-
|
99
|
-
|
100
|
-
|
202
|
+
4| d = 4
|
203
|
+
=> 5| p [a, b, c, d]
|
204
|
+
6|
|
205
|
+
7| __END__
|
206
|
+
=>#0 <main> at target.rb:5
|
207
|
+
|
208
|
+
Stop by #1 BP - Line /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
|
209
|
+
|
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
|
217
|
+
|
218
|
+
(rdbg) continue
|
219
|
+
[1, 2, 3, 4]
|
220
|
+
```
|
101
221
|
|
102
|
-
|
103
|
-
|
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.
|
104
224
|
|
105
|
-
|
225
|
+
### Use `rdbg` with commands written in Ruby
|
106
226
|
|
107
|
-
|
108
|
-
1| a = 1
|
109
|
-
=> 2| b = 2
|
110
|
-
3| c = 3
|
111
|
-
4| p [a + b + c]
|
112
|
-
5|
|
113
|
-
--> #0 /home/ko1/src/rb/target.rb:2:in `<main>'
|
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.
|
114
228
|
|
115
|
-
|
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.
|
116
231
|
|
117
|
-
|
118
|
-
|
119
|
-
|
120
|
-
|
121
|
-
|
122
|
-
5|
|
123
|
-
--> #0 /home/ko1/src/rb/target.rb:3:in `<main>'
|
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`
|
124
237
|
|
125
|
-
|
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`.
|
126
239
|
|
127
|
-
|
128
|
-
1| a = 1
|
129
|
-
2| b = 2
|
130
|
-
3| c = 3
|
131
|
-
=> 4| p [a + b + c]
|
132
|
-
5|
|
133
|
-
--> #0 /home/ko1/src/rb/target.rb:4:in `<main>'
|
134
|
-
|
135
|
-
(rdbg) info # Show all local variables
|
136
|
-
%self => main
|
137
|
-
a => 1
|
138
|
-
b => 2
|
139
|
-
c => 3
|
140
|
-
|
141
|
-
(rdbg) c # Continue the program ("c" is a short name of "continue")
|
142
|
-
[6]
|
143
|
-
```
|
240
|
+
NOTE: If you want to use bundler (`bundle` command), you need to write `gem debug` line in your `Gemfile`.
|
144
241
|
|
145
|
-
###
|
242
|
+
### Using VSCode
|
146
243
|
|
147
|
-
|
148
|
-
# (1) Use `rdbg` command
|
149
|
-
$ rdbg --open target.rb # or rdbg -O target.rb for shorthand
|
150
|
-
Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-5042)
|
151
|
-
...
|
244
|
+
Like other langauges, you can use this debugger on the VSCode.
|
152
245
|
|
153
|
-
|
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.
|
154
252
|
|
155
|
-
|
156
|
-
Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-5042)
|
157
|
-
...
|
253
|
+
Plase refer [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) for operations on VSCode.
|
158
254
|
|
159
|
-
|
160
|
-
|
161
|
-
require 'debug/open' # open the debugger entry point by UNIX domain socket.
|
162
|
-
...
|
255
|
+
You can configure the extension in `.vscode/launch.json`.
|
256
|
+
Please see the extension page for more details.
|
163
257
|
|
164
|
-
|
258
|
+
## Remote debugging
|
165
259
|
|
166
|
-
|
167
|
-
require 'debug/server' # introduce remote debugging feature
|
168
|
-
DEBUGGER__.open # open the debugger entry point by UNIX domain socket.
|
169
|
-
# or DEBUGGER__.open_unix to specify UNIX domain socket.
|
260
|
+
You can use this debugger as a remote debugger. For example, it will help the following situations:
|
170
261
|
|
171
|
-
|
172
|
-
|
173
|
-
|
174
|
-
|
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).
|
175
267
|
|
176
|
-
|
177
|
-
The debuggee process waits for debugger connection at the beginning of `target.rb` like that:
|
268
|
+
You can run your application as a remote debuggee and the remote debugger console can attach to the debugee anytime.
|
178
269
|
|
179
|
-
|
180
|
-
$ rdbg -O ~/src/rb/target.rb
|
181
|
-
DEBUGGER: Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-29828)
|
182
|
-
DEBUGGER: wait for debugger connection...
|
183
|
-
```
|
270
|
+
### Invoke as a remote debuggee
|
184
271
|
|
185
|
-
|
272
|
+
There are two ways to invoke a script as remote debuggee: Use `rdbg --open` and require `debug/open` (or `debug/open_nonstop`).
|
186
273
|
|
187
|
-
|
188
|
-
$ rdbg --attach # or rdbg -A for shorthand
|
189
|
-
|
190
|
-
[1, 4] in /home/ko1/src/rb/target.rb
|
191
|
-
1| (1..).each do |i|
|
192
|
-
=> 2| sleep 0.5
|
193
|
-
3| p i
|
194
|
-
4| end
|
195
|
-
--> #0 [C] /home/ko1/src/rb/target.rb:2:in `sleep'
|
196
|
-
#1 /home/ko1/src/rb/target.rb:2:in `block in <main>' {|i=17|}
|
197
|
-
#2 [C] /home/ko1/src/rb/target.rb:1:in `each'
|
198
|
-
# and 1 frames (use `bt' command for all frames)
|
199
|
-
|
200
|
-
(rdb)
|
201
|
-
```
|
274
|
+
#### `rdbg --open` (or `rdbg -O` for short)
|
202
275
|
|
203
|
-
|
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`.
|
204
277
|
|
205
|
-
|
206
|
-
|
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...
|
283
|
+
```
|
207
284
|
|
208
|
-
|
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).
|
209
286
|
|
210
|
-
|
211
|
-
* Set the environment variable `RUBY_DEBUG_NONSTOP=1`
|
287
|
+
You can connect to the debuggee with `rdbg --attach` command (`rdbg -A` for short).
|
212
288
|
|
213
|
-
|
289
|
+
```shell
|
290
|
+
$ rdbg -A
|
291
|
+
[1, 7] in target.rb
|
292
|
+
=> 1| a = 1
|
293
|
+
2| b = 2
|
294
|
+
3| c = 3
|
295
|
+
4| d = 4
|
296
|
+
5| p [a, b, c, d]
|
297
|
+
6|
|
298
|
+
7| __END__
|
299
|
+
=>#0 <main> at target.rb:1
|
214
300
|
|
215
|
-
|
216
|
-
$ rdbg --attach
|
217
|
-
Please select a debug session:
|
218
|
-
ruby-debug-ko1-19638
|
219
|
-
ruby-debug-ko1-19603
|
301
|
+
(rdbg:remote)
|
220
302
|
```
|
221
303
|
|
222
|
-
|
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.
|
223
305
|
|
224
|
-
|
225
|
-
$ rdbg --attach ruby-debug-ko1-19638
|
226
|
-
```
|
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.
|
227
307
|
|
228
|
-
|
229
|
-
* `RUBY_DEBUG_SOCK_DIR` environment variable if available.
|
230
|
-
* `XDG_RUNTIME_DIR` environment variable if available.
|
231
|
-
* `$HOME/.ruby-debug-sock` if `$HOME` is available.
|
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.
|
232
309
|
|
233
|
-
|
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`.
|
234
311
|
|
235
|
-
|
312
|
+
To connect to the debugeee, you need to specify the port.
|
236
313
|
|
314
|
+
```shell
|
315
|
+
$ rdbg --attach 12345
|
237
316
|
```
|
238
|
-
# (1) Use `rdbg` command
|
239
|
-
$ rdbg -O --port=12345 target.rb
|
240
|
-
# or
|
241
|
-
$ rdbg --open --port=12345 target.rb
|
242
|
-
Debugger can attach via TCP/IP (localhost:12345)
|
243
|
-
...
|
244
317
|
|
245
|
-
|
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.
|
246
320
|
|
247
|
-
|
248
|
-
Debugger can attach via TCP/IP (localhost:12345)
|
249
|
-
...
|
321
|
+
#### `require 'debug/open'` in a program
|
250
322
|
|
251
|
-
|
252
|
-
$ cat target.rb
|
253
|
-
require 'debug/open' # open the debugger entry point.
|
254
|
-
...
|
323
|
+
If you can modify the program, you can open debugging port by adding `require 'debug/open'` line in the program.
|
255
324
|
|
256
|
-
|
257
|
-
|
258
|
-
|
259
|
-
|
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.
|
260
329
|
|
261
|
-
|
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.
|
262
331
|
|
263
|
-
|
264
|
-
|
265
|
-
DEBUGGER__.open(port: 12345)
|
266
|
-
# or DEBUGGER__.open_tcp(port: 12345)
|
267
|
-
|
268
|
-
$ ruby target.rb
|
269
|
-
Debugger can attach via TCP/IP (localhost:12345)
|
270
|
-
...
|
332
|
+
```shell
|
333
|
+
$ RUBY_DEBUG_PORT=12345 ruby target.rb
|
271
334
|
```
|
272
335
|
|
273
|
-
|
336
|
+
## Configuration
|
274
337
|
|
275
|
-
|
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.
|
340
|
+
|
341
|
+
### Configuration list
|
342
|
+
|
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.
|
276
344
|
|
277
345
|
```
|
278
|
-
|
279
|
-
|
346
|
+
# configulation example
|
347
|
+
config set log_level INFO
|
348
|
+
config set no_color true
|
280
349
|
```
|
281
350
|
|
282
|
-
### Initial scripts
|
283
351
|
|
284
|
-
If there are `.rdbgrc` files are there at the current directory and the home directory, files are loaded as initial scripts which contains debugger commands. `RUBY_DEBUG_INIT_SCRIPT` environment variable can specify the initial script file.
|
285
352
|
|
286
|
-
|
353
|
+
* UI
|
354
|
+
* `RUBY_DEBUG_LOG_LEVEL` (`log_level`): Log level same as Logger (default: WARN)
|
355
|
+
* `RUBY_DEBUG_SHOW_SRC_LINES` (`show_src_lines`): Show n lines source code on breakpoint (default: 10 lines)
|
356
|
+
* `RUBY_DEBUG_SHOW_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2 frames)
|
357
|
+
* `RUBY_DEBUG_SHOW_INFO_LINES` (`show_info_lines`): Show n lines on info command (default: 10 lines, 0 for unlimited)
|
358
|
+
* `RUBY_DEBUG_USE_SHORT_PATH` (`use_short_path`): Show shoten PATH (like $(Gem)/foo.rb)
|
359
|
+
* `RUBY_DEBUG_SKIP_NOSRC` (`skip_nosrc`): Skip on no source code lines (default: false)
|
360
|
+
* `RUBY_DEBUG_SKIP_PATH` (`skip_path`): Skip showing frames for given paths (default: [])
|
361
|
+
* `RUBY_DEBUG_NO_COLOR` (`no_color`): Do not use colorize (default: false)
|
362
|
+
* `RUBY_DEBUG_NO_SIGINT_HOOK` (`no_sigint_hook`): Do not suspend on SIGINT (default: false)
|
363
|
+
|
364
|
+
* BOOT
|
365
|
+
* `RUBY_DEBUG_NONSTOP` (`nonstop`): Nonstop mode
|
366
|
+
* `RUBY_DEBUG_INIT_SCRIPT` (`init_script`): debug command script path loaded at first stop
|
367
|
+
* `RUBY_DEBUG_COMMANDS` (`commands`): debug commands invoked at first stop. commands should be separated by ';;'
|
368
|
+
* `RUBY_DEBUG_NO_RC` (`no_rc`): ignore loading ~/.rdbgrc(.rb)
|
287
369
|
|
288
|
-
|
370
|
+
* REMOTE
|
371
|
+
* `RUBY_DEBUG_PORT` (`port`): TCP/IP remote debugging: port
|
372
|
+
* `RUBY_DEBUG_HOST` (`host`): TCP/IP remote debugging: host (localhost if not given)
|
373
|
+
* `RUBY_DEBUG_SOCK_PATH` (`sock_path`): UNIX Domain Socket remote debugging: socket path
|
374
|
+
* `RUBY_DEBUG_SOCK_DIR` (`sock_dir`): UNIX Domain Socket remote debugging: socket directory
|
375
|
+
* `RUBY_DEBUG_COOKIE` (`cookie`): Cookie for negotiation
|
289
376
|
|
290
|
-
###
|
377
|
+
### Initial scripts
|
291
378
|
|
292
|
-
|
379
|
+
If there is `~/.rdbgrc`, the file is loaded as an initial scripts which contains debug commands) when the debug session is started.
|
293
380
|
|
294
|
-
* `
|
295
|
-
*
|
296
|
-
* `RUBY_DEBUG_COMMANDS`: Debug commands invoked at the first stop. Commands should be separated by ';;'.
|
297
|
-
* `RUBY_DEBUG_SHOW_SRC_LINES`: Show n lines source code on breakpoint (default: 10 lines).
|
298
|
-
* `RUBY_DEBUG_SHOW_FRAMES`: Show n frames on breakpoint (default: 2 frames).
|
381
|
+
* `RUBY_DEBUG_INIT_SCRIPT` environment variable can specify the initial script file.
|
382
|
+
* You can specify the initial script with `rdbg -x initial_script` (like gdb's `-x` option).
|
299
383
|
|
300
|
-
|
301
|
-
|
302
|
-
|
303
|
-
|
384
|
+
Initial scripts are useful to write your favorite configurations.
|
385
|
+
For example, you can set break points with `break file:123` in `~/.rdbgrc`.
|
386
|
+
|
387
|
+
If there are `~/.rdbgrc.rb` is available, it is also loaded as a ruby script at same timing.
|
304
388
|
|
305
389
|
## Debug command on the debug console
|
306
390
|
|
391
|
+
On the debug console, you can use the following debug commands.
|
392
|
+
|
307
393
|
* `Enter` repeats the last command (useful when repeating `step`s).
|
308
394
|
* `Ctrl-D` is equal to `quit` command.
|
309
395
|
* [debug command compare sheet - Google Sheets](https://docs.google.com/spreadsheets/d/1TlmmUDsvwK4sSIyoMv-io52BUUz__R5wpu-ComXlsw0/edit?usp=sharing)
|
@@ -343,15 +429,19 @@ The `<...>` notation means the argument.
|
|
343
429
|
* Set breakpoint on the method `<class>#<name>`.
|
344
430
|
* `b[reak] <expr>.<name>`
|
345
431
|
* Set breakpoint on the method `<expr>.<name>`.
|
346
|
-
* `b[reak] ... if <expr>`
|
432
|
+
* `b[reak] ... if: <expr>`
|
347
433
|
* break if `<expr>` is true at specified location.
|
348
|
-
* `b[reak]
|
349
|
-
* break
|
434
|
+
* `b[reak] ... pre: <command>`
|
435
|
+
* break and run `<command>` before stopping.
|
436
|
+
* `b[reak] ... do: <command>`
|
437
|
+
* break and run `<command>`, and continue.
|
438
|
+
* `b[reak] if: <expr>`
|
439
|
+
* break if: `<expr>` is true at any lines.
|
350
440
|
* Note that this feature is super slow.
|
351
441
|
* `catch <Error>`
|
352
442
|
* Set breakpoint on raising `<Error>`.
|
353
|
-
* `watch
|
354
|
-
* Stop the execution when the result of
|
443
|
+
* `watch @ivar`
|
444
|
+
* Stop the execution when the result of current scope's `@ivar` is changed.
|
355
445
|
* Note that this feature is super slow.
|
356
446
|
* `del[ete]`
|
357
447
|
* delete all breakpoints.
|
@@ -362,6 +452,12 @@ The `<...>` notation means the argument.
|
|
362
452
|
|
363
453
|
* `bt` or `backtrace`
|
364
454
|
* Show backtrace (frame) information.
|
455
|
+
* `bt <num>` or `backtrace <num>`
|
456
|
+
* Only shows first `<num>` frames.
|
457
|
+
* `bt /regexp/` or `backtrace /regexp/`
|
458
|
+
* Only shows frames with method name or location info that matches `/regexp/`.
|
459
|
+
* `bt <num> /regexp/` or `backtrace <num> /regexp/`
|
460
|
+
* Only shows first `<num>` frames with method name or location info that matches `/regexp/`.
|
365
461
|
* `l[ist]`
|
366
462
|
* Show current frame's source code.
|
367
463
|
* Next `list` command shows the successor lines.
|
@@ -377,7 +473,7 @@ The `<...>` notation means the argument.
|
|
377
473
|
* `i[nfo]`, `i[nfo] l[ocal[s]]`
|
378
474
|
* Show information about the current frame (local variables)
|
379
475
|
* It includes `self` as `%self` and a return value as `%return`.
|
380
|
-
* `i[nfo] th[read[s]]
|
476
|
+
* `i[nfo] th[read[s]]`
|
381
477
|
* Show all threads (same as `th[read]`).
|
382
478
|
* `display`
|
383
479
|
* Show display setting.
|
@@ -387,8 +483,6 @@ The `<...>` notation means the argument.
|
|
387
483
|
* Remove all display settings.
|
388
484
|
* `undisplay <displaynum>`
|
389
485
|
* Remove a specified display setting.
|
390
|
-
* `trace [on|off]`
|
391
|
-
* enable or disable line tracer.
|
392
486
|
|
393
487
|
### Frame control
|
394
488
|
|
@@ -419,6 +513,19 @@ The `<...>` notation means the argument.
|
|
419
513
|
* `th[read] <thnum>`
|
420
514
|
* Switch thread specified by `<thnum>`.
|
421
515
|
|
516
|
+
### Configuration
|
517
|
+
|
518
|
+
* `config`
|
519
|
+
* Show all configuration with description.
|
520
|
+
* `config <name>`
|
521
|
+
* Show current configuration of <name>.
|
522
|
+
* `config set <name> <val>` or `config <name> = <val>`
|
523
|
+
* Set <name> to <val>.
|
524
|
+
* `config append <name> <val>` or `config <name> << <val>`
|
525
|
+
* Append `<val>` to `<name>` if it is an array.
|
526
|
+
* `config unset <name>`
|
527
|
+
* Set <name> to default.
|
528
|
+
|
422
529
|
### Help
|
423
530
|
|
424
531
|
* `h[elp]`
|
@@ -427,6 +534,83 @@ The `<...>` notation means the argument.
|
|
427
534
|
* Show help for the given command.
|
428
535
|
|
429
536
|
|
537
|
+
## Debugger API
|
538
|
+
|
539
|
+
### Start debugging
|
540
|
+
|
541
|
+
#### Start by requiring a library
|
542
|
+
|
543
|
+
You can start debugging without `rdbg` command by requiring the following libraries:
|
544
|
+
|
545
|
+
* `require 'debug'`: Same as `rdbg --nonstop --no-sigint-hook`.
|
546
|
+
* `require 'debug/start'`: Same as `rdbg`.
|
547
|
+
* `require 'debug/open'`: Same as `rdbg --open`.
|
548
|
+
* `require 'debug/open_nonstop'`: Same as `rdbg --open --nonstop`.
|
549
|
+
|
550
|
+
You need to require one of them at the very beginning of the application.
|
551
|
+
Using `ruby -r` (for example `ruby -r debug/start target.rb`) is another way to invoke with debugger.
|
552
|
+
|
553
|
+
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:
|
554
|
+
|
555
|
+
```shell
|
556
|
+
$ ruby -r debug -e0
|
557
|
+
.../2.7.3/lib/ruby/2.7.0/x86_64-linux/continuation.so: warning: callcc is obsolete; use Fiber instead
|
558
|
+
Debug.rb
|
559
|
+
Emacs support available.
|
560
|
+
|
561
|
+
.../2.7.3/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:162: if RUBYGEMS_ACTIVATION_MONITOR.respond_to?(:mon_owned?)
|
562
|
+
(rdb:1)
|
563
|
+
```
|
564
|
+
|
565
|
+
`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.
|
566
|
+
|
567
|
+
#### Start by method
|
568
|
+
|
569
|
+
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.
|
570
|
+
|
571
|
+
* `DEBUGGER__.start(**kw)`: start debug session with local console.
|
572
|
+
* `DEBUGGER__.open(**kw)`: open debug port with configuration (without configurations open with UNIX domain socket)
|
573
|
+
* `DEBUGGER__.open_unix(**kw)`: open debug port with UNIX domain socket
|
574
|
+
* `DEBUGGER__.open_tcp(**kw)`: open debug port with TCP/IP
|
575
|
+
|
576
|
+
For example:
|
577
|
+
|
578
|
+
```ruby
|
579
|
+
require 'debug/session'
|
580
|
+
DEBUGGER__.start(no_color: true, # disable colorize
|
581
|
+
log_level: 'INFO') # Change log_level to INFO
|
582
|
+
|
583
|
+
... # your application code
|
584
|
+
```
|
585
|
+
|
586
|
+
### `binding.break` method
|
587
|
+
|
588
|
+
`binding.break` (or `binding.b`) set breakpoints at written line. It also has several keywords.
|
589
|
+
|
590
|
+
If `do: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command and continue the program.
|
591
|
+
It is useful if you only want to call a debug command and don't want to stop there.
|
592
|
+
|
593
|
+
```
|
594
|
+
def initialzie
|
595
|
+
@a = 1
|
596
|
+
binding.b do: 'watch @a'
|
597
|
+
end
|
598
|
+
```
|
599
|
+
|
600
|
+
On this case, register a watch breakpont for `@a` and continue to run.
|
601
|
+
|
602
|
+
If `pre: 'command'` is specified, the debuger suspends the program and run the `command` as a debug command, and keep suspend.
|
603
|
+
It is useful if you have operations before suspend.
|
604
|
+
|
605
|
+
```
|
606
|
+
def foo
|
607
|
+
binding.b pre: 'p bar()'
|
608
|
+
...
|
609
|
+
end
|
610
|
+
```
|
611
|
+
|
612
|
+
On this case, you can see the result of `bar()` everytime when you stops there.
|
613
|
+
|
430
614
|
## rdbg command help
|
431
615
|
|
432
616
|
```
|
@@ -434,18 +618,30 @@ exe/rdbg [options] -- [debuggee options]
|
|
434
618
|
|
435
619
|
Debug console mode:
|
436
620
|
-n, --nonstop Do not stop at the beginning of the script.
|
437
|
-
-e
|
438
|
-
-
|
621
|
+
-e DEBUG_COMMAND Execute debug command at the beginning of the script.
|
622
|
+
-x, --init-script=FILE Execute debug command in the FILE.
|
623
|
+
--no-rc Ignore ~/.rdbgrc
|
624
|
+
--no-color Disable colorize
|
625
|
+
--no-sigint-hook Disable to trap SIGINT
|
626
|
+
-c, --command Enable command mode.
|
627
|
+
The first argument should be a command name in $PATH.
|
628
|
+
Example: 'rdbg -c bundle exec rake test'
|
629
|
+
|
630
|
+
-O, --open Start remote debugging with opening the network port.
|
439
631
|
If TCP/IP options are not given,
|
440
632
|
a UNIX domain socket will be used.
|
441
|
-
--sock-path=
|
442
|
-
--port=
|
443
|
-
--host=
|
633
|
+
--sock-path=SOCK_PATH UNIX Doman socket path
|
634
|
+
--port=PORT Listening TCP/IP port
|
635
|
+
--host=HOST Listening TCP/IP host
|
636
|
+
--cookie=COOKIE Set a cookie for connection
|
444
637
|
|
445
638
|
Debug console mode runs Ruby program with the debug console.
|
446
639
|
|
447
640
|
'rdbg target.rb foo bar' starts like 'ruby target.rb foo bar'.
|
448
641
|
'rdbg -- -r foo -e bar' starts like 'ruby -r foo -e bar'.
|
642
|
+
'rdbg -c rake test' starts like 'rake test'.
|
643
|
+
'rdbg -c -- rake test -t' starts like 'rake test -t'.
|
644
|
+
'rdbg -c bundle exec rake test' starts like 'bundle exec rake test'.
|
449
645
|
'rdbg -O target.rb foo bar' starts and accepts attaching with UNIX domain socket.
|
450
646
|
'rdbg -O --port 1234 target.rb foo bar' starts accepts attaching with TCP/IP localhost:1234.
|
451
647
|
'rdbg -O --port 1234 -- -r foo -e bar' starts accepts attaching with TCP/IP localhost:1234.
|
@@ -462,10 +658,23 @@ Attach mode:
|
|
462
658
|
'rdbg -A port' tries to connect to localhost:port via TCP/IP.
|
463
659
|
'rdbg -A host port' tries to connect to host:port via TCP/IP.
|
464
660
|
|
661
|
+
Other options:
|
662
|
+
-h, --help Print help
|
663
|
+
--util=NAME Utility mode (used by tools)
|
664
|
+
|
665
|
+
NOTE
|
666
|
+
All messages communicated between a debugger and a debuggee are *NOT* encrypted.
|
667
|
+
Please use the remote debugging feature carefully.
|
668
|
+
|
465
669
|
```
|
466
670
|
|
467
671
|
# Contributing
|
468
672
|
|
469
673
|
Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/debug.
|
674
|
+
This debugger is not mature so your feedback will help us.
|
470
675
|
|
471
676
|
Please also check the [contributing guideline](/CONTRIBUTING.md).
|
677
|
+
|
678
|
+
# Acknowledgement
|
679
|
+
|
680
|
+
* Some tests are based on [deivid-rodriguez/byebug: Debugging in Ruby 2](https://github.com/deivid-rodriguez/byebug)
|