3. Attaching to a debugger

Attaching to a debugger

Instead of launching directly from VS Code, you may want to attach to an instance of a running debugger, either locally, or on a remote server. The launch.json settings are simpler, but you'll need to make sure your debugger settings match.

The simplest launch.json for just a Ruby attach configuration looks like this:

{
	"version": "0.2.0",
	"configurations": [
		{
			"name": "Debug Attach",
			"type": "Ruby",
			"request": "attach",
			"cwd": "${workspaceRoot}",
			"remoteWorkspaceRoot": "${workspaceRoot}",
			"remoteHost": "SERVER_IP_ADDRESS",
			"remotePort": "SERVER_LISTENING_PORT"
		}
	]
}

Available settings:

"name"

You can set this to what ever you want. It will need to be unique within the configurations array. This is the string that will be shown in the drop-down selector on the debug side bar.

"type"

Must be "Ruby". This tells VS Code what debugger to run.

"request"

Either "launch" - which enables launching the provided program directly from VS Code - or "attach" - which allows you to attach to a remote debug session.

"program"

variable substitution available

This is the ruby script that will first be launched when debugging is started. You should not rely on relative paths working. If the file is in your workspace (which is usually is) this string should have the structure "${workspaceRoot}/path/to/script.rb".

You could debug the current open file with just "program": "${file}".

"cwd"

variable substitution available

Set this to the local base path. Usually the workspaceRoot variable will suffice.

"remoteWorkspaceRoot"

variable substitution available

Set this to the remote base path. The cwd setting above will be dropped from the start of any paths passed to the debugger and this value will replace it. This enables different paths to be used between the development and test devices.

With:

	"cwd": "/dev/folder",
	"remoteWorkspaceRoot": "/usr/local/www"

The path: /dev/folder/app/models/user.rb will become /usr/local/www/app/models/user.rb. Without this translation, break points won't be set correctly.

"remoteHost"

The IP address of the server the debugger will be running on. If you're running it locally, use 127.0.0.1 rather than localhost.

"remotePort"

The port to connect to on the remote server. The default listening port for ruby-debug-ide is 1234.

Available VS Code defined variables

• ${workspaceRoot} - the path of the folder opened in VS Code
• ${file} - the current opened file
• ${fileBasename} - the current opened file's basename
• ${fileDirname} - the current opened file's dirname
• ${fileExtname} - the current opened file's extension

Running the debugger

Run the debugger from the command line with:

rdebug-ide --host SERVER_IP_ADDRESS\
    --port SERVER_LISTENING_PORT\
    -- TARGET_SCRIPT {...script args} 

Where the SERVER_IP_ADDRESS and SERVER_LISTENING_PORT match the settings in your launch.json configuration. If there is only one network device on the server where the debugger is running, (and/or you have considered the security implications) you can use 0.0.0.0 to allow the debugger to listen on any connection.