Merge pull request raix#77 from pullhub/fork3

feat(fork): support for multi-session/multi-process/fork debugging

DEBUGGING.md

@@ -18,6 +18,8 @@ Details are in:
 
 #### The user running debugger
 
+<!-- FIXME(bh): this is outdated -->
+
 1. The extension starts up in a separate process from vscode, a `debug server`
 2. The `debug server` will then spawn `perl5db` - somthing like `perl -d` *(unless overwritten by user settings)*
 
@@ -38,6 +40,14 @@ The [perlDebug.ts](src/perlDebug.ts) is the layer wiring up the perl5db `adapter
 
 *Theres also some inconsistencies in how the vs code debug api handles variables/breakpoints vs watchers etc. making somethings hard to keep track of - things we might workaround later on*
 
+#### Running extension.ts and perlDebug.ts in the same process
+
+In `extension.ts` you can set `EMBED_DEBUG_ADAPTER` to `true` during
+development. Visual Studio Code will then run the extension and any
+instance of the debug adapter in the same process, so you can have
+breakpoints in `extension.ts` and other parts of the code that work
+during the same session. This option is not suitable for releases.
+
 #### Test coverage
 
 Theres added a test matrix making it possible to test in `macOS`/`linux` and `windows` - it's not perfect and not complete. First issue is to have a stable way of installing different distributions of perl *is not solved*.

package.json

@@ -10,7 +10,7 @@
   },
   "license": "MIT",
   "engines": {
-    "vscode": ">=1.19.0",
+    "vscode": ">=1.30.0",
     "node": ">=8.0.0"
   },
   "icon": "images/vscode-perl-debug.png",
@@ -44,8 +44,8 @@
   },
   "dependencies": {
     "await-notify": "1.0.1",
-    "vscode-debugadapter": "1.24.0",
-    "vscode-debugprotocol": "1.24.0"
+    "vscode-debugadapter": "1.34.0",
+    "vscode-debugprotocol": "1.34.0"
   },
   "devDependencies": {
     "@commitlint/cli": "^7.5.2",
@@ -62,7 +62,7 @@
     "tslint": "5.8.0",
     "typescript": "2.7.1",
     "vscode": "1.1.30",
-    "vscode-debugadapter-testsupport": "1.24.0"
+    "vscode-debugadapter-testsupport": "1.34.0"
   },
   "scripts": {
     "prepublish": "tsc",
@@ -103,7 +103,7 @@
       {
         "type": "perl",
         "label": "Perl Debug",
-        "program": "./out/perlDebug.js",
+        "program": "./out/debugAdapter.js",
         "runtime": "node",
         "languages": [
           "perl"
@@ -192,7 +192,8 @@
                   "integratedTerminal",
                   "externalTerminal",
                   "remote",
-                  "none"
+                  "none",
+                  "_attach"
                 ],
                 "description": "Where to launch the debug target",
                 "default": "integratedTerminal"
@@ -201,6 +202,21 @@
                 "type": "boolean",
                 "description": "Log raw I/O with debugger in output channel",
                 "default": false
+              },
+              "debugLog": {
+                "type": "boolean",
+                "description": "Log debug messages in output channel",
+                "default": false
+              },
+              "sessions": {
+                "type": "string",
+                "description": "How to handle forked children or multiple connections",
+                "default": "single",
+                "enum": [
+                  "single",
+                  "watch",
+                  "break"
+                ]
               }
             }
           }
@@ -218,7 +234,10 @@
             "inc": [],
             "args": [],
             "env": {},
-            "stopOnEntry": true
+            "debugRaw": false,
+            "debugLog": false,
+            "stopOnEntry": true,
+            "sessions": "single"
           },
           {
             "type": "perl",
@@ -228,7 +247,8 @@
             "program": "${workspaceFolder}/${relativeFile}",
             "root": "${workspaceRoot}/",
             "stopOnEntry": true,
-            "port": 5000
+            "port": 5000,
+            "sessions": "single"
           }
         ]
       }

readme.md

@@ -11,13 +11,16 @@ A debugger for perl in vs code.
 ### Features
 
 * Breakpoints *(continue, step over, step in, step out)*
+* Function breakpoints *(for now functions have to be loaded at launch)*
+* Process control *(pause, resume, restart)*
 * Stacktrace
 * Variable inspection *(support for objects, arrays, strings, numbers and boolean)*
 * Variable watching *(for now we don't create actual watch breakpoints - figuring out how to maintain t)*
 * Setting new values of variables *(works inside of arrays and objects too)*
 * Debug console for writing expressions *(write perl expressions in the debug console)*
 * Variable values on hover in code
 * Loaded modules view *(including source code retrieval from remote)*
+* Multi-session/multi-target debugging *(including support for `fork` where available)*
 
 ### Settings
 
@@ -30,6 +33,8 @@ A debugger for perl in vs code.
 * `port` Number for port to listen for remote debuggers to connect to. *(Used only for remote debugging)*
 * `console` String to identify where to launch the debuggee
 * `debugRaw` Boolean to enable logging of raw I/O with the Perl debugger in an output channel
+* `debugLog` Boolean to enable logging of other debug messages in an output channel
+* `sessions` String to configure how child processes are handled
 
 ### Setup notes
 
@@ -60,7 +65,9 @@ A standard `launch.json` will resemble the following (on Windows, *nix distros w
 
 ### Remote debugger
 
-When setting the `port` attribute in `launch.json` the vs code debug extension will start a debug server for the remote perl debug instance to connect to.
+When setting the `console` attribute in `launch.json` to `remote` the
+vs code debug extension will start a debug server for the remote perl
+debug instance to connect to.
 
 eg.:
 ```bash
@@ -69,6 +76,48 @@ eg.:
 ```
 *`localhost` should be replaced by the ip address*
 
+### Handling multiple processes
+
+Visual Studio Code supports running multiple debugging sessions in
+parallel, if you have multiple configurations in your `launch.json`,
+you can start several of them simultaneously.
+
+The extension can also automatically start additional debug sessions
+when a Perl process `fork`s or if multiple debuggers try to connect
+to the same `port`. This behaviour needs to be enabled with the
+`sessions` option. To illustrate, with `launch.json` like
+
+```json
+...
+  "sessions": "watch",
+  "console": "remote",
+  "port": 5000,
+...
+```
+
+Then you can start a debug session in vscode and launch:
+
+```bash
+PERL5OPT=-d PERLDB_OPTS='RemotePort=localhost:5000' prove -l
+```
+
+All the Perl processes launched in one way or another by `prove` will
+then connect to the extension. In `watch` mode execution of dependent
+processes will continue immediately, in `break` mode they will stop
+on entry (like with `stopOnEntry` for the first or main process).
+
+When using this feature, it is recommended to use the debugger module
+[Devel::vscode](https://metacpan.org/pod/Devel::vscode). It overrides
+the `fork` function so that the Perl debugger connects to the
+extension right after `fork` returns in the child. When the module is
+not loaded, the extension creates a global watch expression `w $$` to
+the same effect, but that puts the debugger in trace mode, wich can
+slow down debugging considerably.
+
+When you start the perl process you want to debug, instead of `-d`,
+specify `-d:vscode`. If the extension starts the Perl process, set
+`execArgs: ["-d:vscode"]` in `launch.json`.
+
 ### Stability
 
 Tests matrix running between os and perl versions:
@@ -102,7 +151,11 @@ If you want to help test / debug read [DEBUGGING.md](DEBUGGING.md)
 
 * Watching variables doesn't create actual expression watchers yet - need more api for actually maintaining the list of expressions to watch. I might be able to do a workaround for now.
 * Variable values on hover doesn't work all the time due to the lack of info, eg. `$obj->{ownObj}->{ownFoo}` hovering over `$obj` will work fine - but the children are not parsed correctly - to solve this we might need to parse the line of code.
-* Function breakpoints not working / added - need to figure out if possible
+
+### Problems with `perl5db.pl` affecting this extension
+
+* [#133875: warnLevel=0 is not the default](https://rt.perl.org/Ticket/Display.html?id=133875)
+* [#130361: debugger does not stop at postponed breakpoints](https://rt.perl.org/Ticket/Display.html?id=130361)
 
 ### Credits