VSCode Ruby rdbg Debugger
MIT License
Ruby debugger to connect debug library which utilize recent Ruby's debug support features.
You need to install latest debug
gem and rdbg
command should be in $PATH
.
$ gem install debug
Without any configuration, you can use this debugger by "Start Debugging" (F5 key) if you activate .rb
file.
You will see the "Debug command line" input dialog. Please specify your favorite command line you want to debug.
For example:
ruby foo.rb
(launch foo.rb
)ruby foo.rb 10 20 30
(launch foo.rb
with options 10
, 20
and 30
)rake taskA
(launch rake
task taskA
)bundle exec rspec
(launch rspec
command with bundle exec
)bin/rails s
(launch bin/rails s
)When you select a command line, the specified command will run on rdbg
debugger, and VSCode will connect to the rdbg
debugger with UNIX domain socket.
And new terminal is created (named rdbg
).
You can see stdout/err outputs and you can input stdin on rdbg
terminal.
You can stop the programs
When the program stops, you can see "Call stack", "Variables" and you can set "Watch" expressions. On the debug console, you can input valid Ruby program and you will get an evaluation result on selected context ("Call stack").
See also: Debugging in Visual Studio Code
For developers: RUBY_DEBUG_DAP_SHOW_PROTOCOL=1
on rdbg
terminal will show the all DAP protocol.
You can write your favorite setting in .vscode/launch.json
.
To make a .vscode/launch.json
with default settings, you only need to click "create a launch.json file" on the "Run and Debug" pane. And you will see the following default configurations.
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"type": "rdbg",
"name": "Debug current file with rdbg",
"request": "launch",
"script": "${file}",
"args": [],
"askParameters": true
},
{
"type": "rdbg",
"name": "Attach with rdbg",
"request": "attach"
}
]
}
It contains "Debug current file with rdbg" (launch) configuration and "Attach with rdbg" (attach) configuration. You can modify this configuration, and also you can add your favorite configuration like:
{
"type": "rdbg",
"name": "Run rake test",
"request": "launch",
"command": "rake",
"script": "test", // launch rake test with debugger
"args": [],
"askParameters": false // Do not ask startup parameter any more
},
You can use the following "launch" configurations.
script
command
bundle exec ruby
for example.ruby
cwd
${workspaceFolder}
args
[]
env
useBundler
:
bundle exec
if command
configuration is not given. and Gemfile
is available in the workspace.useBundler
by the extension configuration (default: true).true
)askParameters
rdbgPath
rdbgPath
by the extension configuration (default: rdbg
).rdbg
debugPort
debugPort
configuration, open a UNIX Domain Socket (or TCP/IP localhost:0
on Windows) to communicate with debuggee. If you want to use another debug port, set this configuration.
12345
): open a TCP/IP debug port with port 12345
hostname:port
(e.g. hostname:12345
): open a TCP/IP port 12345
and hostname hostname
0
TCP/IP port (choose usable port) with debug.gem v1.5.0 or later.waitLaunchTime
5000
in milliseconds).useTerminal
showProtocolLog
Note that if you have a trouble by launching rdbg
, please try to specify rdbgPath
. Without this configuration, this extension simply calls rdbg
in PATH.
You can attach to a Ruby process which run with an opening debugger port.
The following commands starts the foo.rb
with opening debug port. There are more methods to open the port. See more for ruby/debug: Debugging functionality for Ruby.
# With rdbg command
$ rdbg --open foo.rb # open debug port. -O is short for --open
$ rdbg -n -O foo.rb # do not stop at the beginning of application
$ rdbg -O -c -- bundle exec rspec # run rspec with remote
# With debug/open lib
$ ruby -r debug/open foo.rb
$ ruby -r debug/open_nonstop foo.rb # do not stop at the beginning of application
# If your application requires debug/open (or debug/open_nonstop) explicitly, of course -r is not needed.
$ ruby foo.rb
# With debug lib with RUBY_DEBUG_OPEN
$ RUBY_DEBUG_OPEN=true ruby -r debug foo.rb
# If your application requires debug explicitly, of course -r is not needed.
$ RUBY_DEBUG_OPEN=true ruby foo.rb
# If your Gemfile has a line `gem 'debug'` with Rails, you only need to launch it with the `RUBY_DEBUG_OPEN` envval.
$ RUBY_DEBUG_OPEN=true rails server
After that, you can connect to the debug port. This extension searches opening debugger port and attach to that port by running Attach with rdbg
(select it on the top of "RUN AND DEBUG" pane and push the green "Start Debugging" button).
You can specify the following "attach" configurations.
rdbgPath
launch
request.debugPort
launch
request.localfs
true
and you can open the file directlylocalfsMap
/remote_dir:/local_dir
if sharing the same source repository with local and remote computers./rem1:/loc1,/rem2:/loc2
by concatenating with ,
.Without debugPort
configuration, the
With debugPort
, you can attach to TCP/IP debug port.
rdbg
command like: rdbg --open --port 12345 foo.rb
debug/open
lib: RUBY_DEBUG_PORT=12345 ruby -r debug/open foo.rb
debug
lib with RUBY_DEBUG_OPEN
envval: RUBY_DEBUG_OPEN=true RUBY_DEBUG_PORT=12345 ruby -r debug foo.rb
debugPort: '12345'
attach configuration.Attach with rdbg
and start attach debugginglocalfsMap
is helpful if you run the debuggee and share the same file system with another name in debuggee.
For example, running a docker container with -v
option (and --network=host
to communicate with the host and a docker container) option like that:
$ docker run --network=host -it -v `pwd`:/app/ --rm ruby bash
/:# cd app
/app:# rdbg -O --port=12345 target.rb
In this case, the current directory of host (${workspaceFolder}
) is shared with the name /app
in a container and VSCode on the host can connect to the debuggee process in a container by TCP/IP port 12345. The launch.json
configuration should be:
{
"type": "rdbg",
"name": "Attach with rdbg (tcp 12345)", // Specify your favorite name
"request": "attach",
"debugPort": "localhost:12345",
"localfsMap": "/app:${workspaceFolder}"
}
In order to launch the debugger using the correct Ruby version, rdbg allows configuring your preferred version manager, which is used to activate the Ruby environment with extension settings (or settings.json
).
// Default value is "none" for not using a version manager to activate the environment
// Available managers are shadowenv, chruby, asdf, rbenv and rvm
{
// User settings
"rdbg.rubyVersionManager": "none"
}
If you are using rbenv
configured with a login shell (on bash or zsh), you do not need to specify this configuration because vscode-rdbg will launch ruby command with login shell setting like bash -lic ruby ...
. With this configuration, vscode-rdbg will launch simply ruby
command. This configuration will be useful if you are using other environment such as chruby and so on.