2. Launching from VS Code

Debugging from VS Code

Setting up your launcher

Open the VS Code launch.json file by clicking the gear icon in the debug side bar.

If you don't have one, an environment selection option should pop up. Select Ruby. This will give you a basic debug configuration.

The simplest launch.json for Ruby looks like this:

{
	"version": "0.2.0",
	"configurations": [
		{
			"name": "Debug Local",
			"type": "Ruby",
			"request": "launch",
			"program": "${workspaceRoot}/main.rb"
		}
	]
}

This has just one configuration in the configurations array. You can add as many as you want here, as long as the name element is unique.

Pressing the debug start button (the play icon) will start the debugger and load the file main.rb from the base directory of the workspace as the executable script. All environment variables set when VS Code was executed will be passed to the provided program. By default, the folder the program is in is set as the current working directory.

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

By default, the working directory is set to the location of the file provided in the program string. It is common for this value to be set to "cwd": "${workspaceRoot}".

"stopOnEntry"

Stop program execution on the first line always. Note that all active breakpoints are set before the debugger starts even if this field is not set. Valid options are true and false (default).

"showDebuggerOutput"

Provide some extra output to the debug terminal, specifically about the running of rdebug-ide. Valid options are true and false (default).

"args"

variable substitution available

An array of arguments to provide to the script under debug. Each string in the array is sent as a seperate argument, so if you would call the script from a terminal as:

ruby main.js --infile '/the/file name/with spaces' --count 3 --base

this setting should read:

	"args": ["--infile", "/the/file name/with spaces", "--count", "3"]

There is no need to include the quotes around the second argument. Doing so would actually result in the string WITH the quotes being passed to the script.

"env"

variable substitution available

Provide a hash of environment variable to set before launching the program. For example:

	"env": {
		"BASE": "${workspaceRoot}",
		"EXT": "${fileExtname}",
		"RAILS_ENV": "test"
	}

"pathToRDebugIDE"

Set the absolute path to rdebug-ide if it's not in your PATH. On windows you need to provide the .bat file.

"useBundler"

Run rdebug-ide within bundler exec. You may need to do this if you've installed the ruby-debug-ide gem within your project. Valid options are true and false (default).

"pathToBundler"

If you have useBundler set, and bundler isn't in your PATH, set the absolute path here. If you're wrapping in bundler, you shouldn't need to provide a pathToRDebugIDE setting. On windows you need to provide the .bat file.

Also, if you've installed with the bundler install --binstubs you should be able to skip the bundler related settings and use "pathToRDebugIDE": "${workspaceRoot}/bin/rdebug-ide".

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

Debugging Ruby GEM executables

There is not much difference to the regular setup. Have a look at Running gem scripts for tips on the changes needed.