Merge pull request #108 from puremourning/debugpy

Document how to use debugpy directly instead of vscode-python

README.md

@@ -41,6 +41,7 @@ For a tutorial and usage overview, take a look at the
    * [Debug adapter configuration](#debug-adapter-configuration)
       * [C, C  , Rust, etc.](#c-c-rust-etc)
       * [Python](#python)
+         * [Alternative: Use debugpy directly](#alternative-use-debugpy-directly)
       * [TCL](#tcl)
       * [C♯](#c)
       * [Go](#go)
@@ -54,7 +55,7 @@ For a tutorial and usage overview, take a look at the
    * [FAQ](#faq)
    * [License](#license)
 
-<!-- Added by: ben, at: Tue 28 Jan 2020 08:46:26 GMT -->
+<!-- Added by: ben, at: Sat  1 Feb 2020 00:08:19 GMT -->
 
 <!--te-->
 
@@ -173,6 +174,7 @@ neovim doesn't implement some features Vimspector relies on:
   the output window's current output.
 * Prompt Buffers - used to send commands in the Console and add Watches
 * Balloons - used to display the values of variables when debugging.
+* Environment variables when laucnhing debugee in embedded terminal.
 
 Workarounds are in place as follows:
 
@@ -185,6 +187,9 @@ Workarounds are in place as follows:
 There is no workaroud for the lack of balloons; you'll just have to use
 `:VimspectorEval` or `:VimspectorWatch`, or switch to Vim.
 
+The only workaround for the missing environment variables feature is to use
+neovim master (it doesn't work in neovim 0.4).
+
 ## Language dependencies
 
 The debug adapters themselves have certain runtime dependencies:
@@ -192,7 +197,7 @@ The debug adapters themselves have certain runtime dependencies:
 | Language         | Status       | Switch                       | Adapter           | Dependencies           |
 |------------------|--------------|------------------------------|-------------------|------------------------|
 | C, C++, etc.     | Supported    | `--all` or ` --enable-c`     | vscode-cpptools   | mono-core              |
-| Python           | Supported    | `--all` or `--enable-python` | vscode-python     | Python 2.7 or Python 3 |
+| Python           | Supported    | `--all` or `--enable-python` | vscode-python     | Node 10, Python 2.7 or Python 3 |
 | TCL              | Experimental | `--all` or `--enable-tcl`    | tclpro            | TCL 8.5                |
 | Bourne Shell     | Experimental | `--all` or `--enable-bash`   | vscode-bash-debug | Bash v??               |
 | C# (dotnet core) | Experimental | `--force-enable-csharp`      | netcoredbg        | DotNet core            |
@@ -695,7 +700,14 @@ For `lldb-vscode` replace the name of the adapter with `lldb-vscode`:
 
 ## Python
 
+NOTE: Please see the alternative approach below, as this will become the
+standard approach in future.
+
 * Python: [vscode-python](https://github.com/Microsoft/vscode-python)
+* NOTE: You must be running `node` 10. See [this issue](https://github.com/puremourning/vimspector/issues/105)
+
+I recommend installing `nvm` and then `nvm use 10` prior to starting your Vim
+session.
 
 ```
 {
@@ -718,6 +730,47 @@ For `lldb-vscode` replace the name of the adapter with `lldb-vscode`:
 }
 ```
 
+### Alternative: Use debugpy directly
+
+*** NOTE: This solution does not work in NeoVim 0.4 due to missing environment
+variables support when launching a terminal. Do not raise issues about this if
+you are using NeoVim 0.4. ***
+
+If you can't get a node 10 environment set up for whatver reason, then you can
+avoid that issue by using `debugpy` (formerly `ptvsd`) directly.
+
+Here's how:
+
+1. Instal `debugpy`: `pip install debugpy`
+2. Create `/path/to/vimspector/gadgets/<os>/.gadgets.d/debugpy.json`:
+
+```json
+{
+  "adapters": {
+    "debugpy": {
+      "command": [
+        "python",
+        "-m",
+        "debugpy.adapter"
+      ],
+      "name": "debugpy",
+      "configuration": {
+        "python": "python"
+      }
+    }
+  }
+}
+```
+
+Then in theory you should just have to change `"adapter": "vscode-python"` to
+`"adapter": "debugpy"`.
+
+See `support/test/python/simple_python/.vimspector.json` as an example.
+
+NOTE: This will likely become the default in future, and vscode-python will be
+phased out.
+
+
 ## TCL
 
 * TCL (TclProDebug)

support/test/python/simple_python/.vimspector.json

@@ -1,4 +1,17 @@
 {
+  "adapters": {
+    "debugpy": {
+      "command": [
+        "python",
+        "-m",
+        "debugpy.adapter"
+      ],
+      "name": "debugpy",
+      "configuration": {
+        "python": "python"
+      }
+    }
+  },
   "configurations": {
     "run": {
       "adapter": "vscode-python",
@@ -31,6 +44,23 @@
           "uncaught": ""
         }
       }
+    },
+    "run - debugpy": {
+      "adapter": "debugpy",
+      "configuration": {
+        "request": "launch",
+        "type": "python",
+        "cwd": "${workspaceRoot}",
+        "program": "${file}",
+        "stopOnEntry": true,
+        "console": "integratedTerminal"
+      },
+      "breakpoints": {
+        "exception": {
+          "raised": "N",
+          "uncaught": ""
+        }
+      }
     }
   }
 }