How to setup a development environment to debug an extension that uses local changes to vscode.d.ts?

[nicksnyder]

I would like to experiment with some changes to vscode.d.ts (the API exposed to extensions).

In order to test these changes locally, I would like to be able to have an extension FOO such that

1. FOO can consume the new/modified APIs in vscode.d.ts
2. I can set breakpoints in FOO and VS Code for debugging.

In my case FOO=vscode-go (an extension that already exists).

tl;dr what is the recommended setup to accomplish what I want?

Long version...here is what I have attempted...

Method 1: Inline vscode-go into vscode/extensions/vscode-go.

This requires making quite a few changes in vscode

• Exclude vscode-go from some lint rules in gulpfile.hygine.js
• Add vscode-go to list of extensions in build/npm/postinstall.js
• Update vscode-go's package.json
  • Remove vscode as a dev dependency from vscode-go
  • Remove references to node ./node_modules/vscode/bin/install
  • Update compile and watch scripts to look like gulp compile-extension:vscode-go and gulp watch-extension:vscode-go
• Add a refs.d.ts to point to local version of vscode.d.ts

  /// <reference path='../../../../src/vs/vscode.d.ts'/>
  /// <reference path='../../../../src/vs/vscode.proposed.d.ts'/> 
  

• Extension specific hacking. For vscode-go this involved
  • Updating main entry point due to how extension compilation works

    -"main": "./out/src/goMain",
    +"main": "./out/goMain",
    

  • Rewriting some import paths

    -import { getBinPathFromEnvVar } from '../src/goPath';
    +import { getBinPathFromEnvVar } from './goPath';
    

  • Export interfaces that need to be exported
  • Update settings in tsconfig.json

I had this method working for a bit (both debugging and consuming new APIs), but within the last 24 hours debugging has broken twice (I can't seem to step in to function calls once I hit a breakpoint). I was able to "fix" this the first time by trying to re-do my setup (ultimately I am not sure what fixed it), but now that it has broken again (and I am not sure what causes this setup to break), I have so far been unable to fix it my repeating my setup process.

Method 2: use --extensionDevelopmentPath

This is something that I have just started trying because it seems less than ideal to need to "inline" extensions into vscode via method 1.

The goal of this method is to use ./scripts/code.sh --extensionDevelopmentPath=/Users/nick/code/vscode-go.

Steps:

• Update vscode-go's package.json
  • Remove vscode as a dev dependency from vscode-go
  • Remove references to node ./node_modules/vscode/bin/install
• Add a refs.d.ts to point to local version of vscode.d.ts

  /// <reference path='../../../../src/vs/vscode.d.ts'/>
  /// <reference path='../../../../src/vs/vscode.proposed.d.ts'/> 
  

Right now I am stuck on trying to get breakpoints to work with this method. Setting a breakpoint in vscode-go requires vscode-go to be a subdirectory of my project.

I tried creating a sandbox directory that contains just vscode and vscode-go. In this directory I have a .vscode/launch.json that looks like this

{
    // Use IntelliSense to learn about possible Node.js debug 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": "node",
            "request": "attach",
            "name": "Attach to Extension Host",
            "protocol": "legacy",
            "port": 5870,
            "sourceMaps": true,
            "outFiles": [
                "/Users/nick/code/sandbox/vscode-clean/out/**/*.js",
                "/Users/nick/code/sandbox/vscode-go/out/**/*.js"
            ]
        }
    ]
}

The vscode-go extension appears to load, but my breakpoints in vscode-go files don't catch.

[isidorn]

Appologies for not reading the whole description.
Can you simply debug your extension by pressing F5 (without making any changes to vscode.d.ts). You should be able to do this

Now you should be able to simply change the vscode.d.ts file manually inside your node modules folder any way you want

However just changing the definition file does not actually change VSCode. I believe you also want to change vscode and your extension. For that you need to build a development version of vscode. In the development version of vscode you need to add a node debug extension, do that by copying ms-vscode.node-debug (path on my mac /Applications/Visual Studio Code - Insiders.app/Contents/Resources/app/extensions) from your stable vscode instalation to your users folder oss dev extensions (path on my mac /Users/isidor/.vscode-oss-dev/extensions). Now debug your extension from the development version of vscode

Will reopen if this does not solve your issue

[nicksnyder]

@isidorn Thanks! This unblocked me but I do have a few clarifying questions.

(1) Should I copy both ms-vscode.node-debug and ms-vscode.node-debug2? I have copied both and it seems to work.

(2) The extension always downloads vscode.d.ts from network via ./node_modules/vscode/bin/install instead of using modifications I have made in my local copy of VS Code.

I assume I need to delete the dev dependency on vscode (including the reference to ./node_modules/vscode/bin/install) and then add a ref.d.ts that points to my local copy of vscode.d.ts (example)? Is there a better way?

(3) I also needed to modify launch.json as you mentioned here. Would you be open to me submitting a PR to document this process somewhere? Where would this doc belong?

[nicksnyder]

@isidorn another question:

(4) I have the extension debuggable running against my dev version of vscode, but how do I attach a debugger to the main thread of the vscode instance that is running my extension and set breakpoints?

• My dev version of vscode is opened to the extension's directory so it doesn't have access to vscode files (can't set a breakpoint, and not sure if it can attach it to the main thread).
• My stable version of vscode can attach to my dev version that isn't running the extension (but that isn't what I want).
• I tried modifying the "Launch Extension" task in vscode-go's .vscode/launch.json to add an argument --remote-debugging-port=9222 but my stable vscode doesn't seem to be able to attach to that (timeout).

I don't seem to be able to even see console.log messages.

[isidorn]

1. Yes, due to Prepare for node -> node2 transition #19650
2. I do not know a better way maybe @jrieken has some advice here
3. Absolutely. This page seems like the right location - is it possible for you to add a new section there
4. As far as I understand you want to attach to the vscode renderer process - for that you need the chrome debug extension. You can see how we use it to launch and attach to vscode here

[nicksnyder]

As far as I understand you want to attach to the vscode renderer process - for that you need the chrome debug extension.

Awesome!

To summarize (for the record), my setup consists of three instances of VS Code:

1. VS Code 1.9.1
   • Opened to vscode development directory (e.g. /Users/nick/code/vscode).
   • This is where I make changes to vscode (e.g. vscode.d.ts).
2. Development version of VS Code
   • Opened to my extension development directory (e.g. /Users/nick/code/vscode-go).
   • Started by running ./Users/nick/code/vscode/scripts/code.sh /Users/nick/code/vscode-go.
   • This is where I make changes to the extension code and set breakpoints.
3. Development version of VS Code running extension
   • Launched by running "Launch Extension" task from (2)

     {
     	"name": "Launch Extension",
     	"type": "extensionHost",
     	"request": "launch",
     	// path to VSCode executable
     	"runtimeExecutable": "${execPath}",
     	"args": [
     		"/Users/nick/code/vscode",
     		"--extensionDevelopmentPath=${workspaceRoot}"
     		],
     	"stopOnEntry": false,
     	"sourceMaps": true,
     	"outFiles": ["${workspaceRoot}/out/**/*.js"],
     	"preLaunchTask": "npm"
     },
     

   • This is where I perform actions that trigger breakpoints

✅ Breakpoints set on extension code in (2) catch when I perform actions in (3), hooray! 🎉
✅ I can open the "Debugger for Chrome" extension in (3) to set breakpoints on render code and see console.log, horray! 🎉

You can see how we use it to launch and attach to vscode here

Is there any way for me to us VS Code instead of setting breakpoints inside of the "Debugger for Chrome" extension? What you linked is a launch task but what I would need is an attach task.

• Can (2) attach to main thread of (3)?
  • Even if it can, (2) doesn't have vscode directory open so I don't know how I would set breakpoints.
• Can (1) attach to the main thread of (3)?
  • Running the built in "Attach to VS Code" launch configuration attaches (1) to (2) not (1) to (3) assuming that (2) is run with --remote-debugging-port=9222.
  • I tried adding the --remote-debugging-port=9222 to the "Launch Extension" configuration that launches (3), but (1) was not able to attach.

Thanks again for the help! I will try to submit a PR to document this process at some point.

[isidorn]

Attach should also be possible in both cases but you just need to start vscode development with a special flag debug flag. More details https://github.com/Microsoft/vscode-chrome-debug/issues/35
Just experiment with the chrome debug and if something does not work feel free to post questions in the chrome debug extension repo.

[nicksnyder]

More details Microsoft/vscode-chrome-debug#35

This tells me to use --remote-debugging-port which is what I have already tried.

you just need to start vscode development with a special flag debug flag.

Starting (2) with --remote-debugging-port allows me to connect (1) to (2), but this isn't what I want. I want to connect (1) to (3) so I can debug the same process that the development extension is running on. I tried adding --remote-debugging-port=9222 to the "Launch Extension" configuration that launches (3), but (1) was not able to attach.

@roblourens Any ideas?

[guw]

@nicksnyder I know the issue is long time ago, but did you manage to find a solution to set a breakpoint in (1) and debug it in (3)?

[nicksnyder]

@guw Sorry, I don't remember. I haven't had to do this in a while and some of the debugging stuff has changed since then.