Merge pull request #19 from PranayAgarwal/hhvm_vsdebug_adapter

HHVM Debugger support

.vscode/launch.json

@@ -7,22 +7,53 @@
             "type": "extensionHost",
             "request": "launch",
             "runtimeExecutable": "${execPath}",
-            "args": ["--extensionDevelopmentPath=${workspaceRoot}" ],
+            "args": [
+                "--extensionDevelopmentPath=${workspaceFolder}"
+            ],
             "stopOnEntry": false,
             "sourceMaps": true,
-            "outFiles": [ "${workspaceRoot}/out/**/*.js" ],
+            "outFiles": [
+                "${workspaceFolder}/out/**/*.js"
+            ],
             "preLaunchTask": "npm: watch"
         },
+        {
+            "name": "Debug Server",
+            "type": "node",
+            "request": "launch",
+            "cwd": "${workspaceFolder}",
+            "program": "${workspaceFolder}/src/debugger.ts",
+            "args": [
+                "--server=4711"
+            ],
+            "outFiles": [
+                "${workspaceFolder}/out/**/*.js"
+            ]
+        },
         {
             "name": "Extension Tests",
             "type": "extensionHost",
             "request": "launch",
             "runtimeExecutable": "${execPath}",
-            "args": ["--extensionDevelopmentPath=${workspaceRoot}", "--extensionTestsPath=${workspaceRoot}/out/test" ],
+            "args": [
+                "--extensionDevelopmentPath=${workspaceFolder}",
+                "--extensionTestsPath=${workspaceFolder}/out/test"
+            ],
             "stopOnEntry": false,
             "sourceMaps": true,
-            "outFiles": [ "${workspaceRoot}/out/test/**/*.js" ],
+            "outFiles": [
+                "${workspaceFolder}/out/test/**/*.js"
+            ],
             "preLaunchTask": "npm: watch"
         }
+    ],
+    "compounds": [
+        {
+            "name": "Extension + Debug Server",
+            "configurations": [
+                "Extension",
+                "Debug Server"
+            ]
+        }
     ]
-}
+}

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 See the full list of recent releases and features added on the [Github releases page](https://github.com/PranayAgarwal/vscode-hack/releases).
 
+## v0.8.0 - 2018-05-10
+- **HHVM Debugger (Alpha version)** — Launch scripts or attach to an HHVM server straight from VS Code. See the [debugger doc](https://github.com/PranayAgarwal/vscode-hack/blob/master/docs/debugging.md) for details on setup and usage. _This is a very early release. Please file any bugs at the Issues page._
+- Hack coverage check works again. A new icon in the editor status bar shows % coverage for the file and can be clicked to highlight uncovered areas. (Can be disabled by setting `"hack.enableCoverageCheck": false`)
+
 ## v0.7.0 - 2018-01-25
 - Language Server mode is now on by default for users running HHVM 3.23 or later. Add `"hack.useLanguageServer": false` to your workspace config to disable it.
 

README.md

@@ -8,6 +8,10 @@ It is published in the Visual Studio Marketplace [here](https://marketplace.visu
 
 ## Latest releases
 
+## v0.8.0
+- **HHVM Debugger (Alpha version)** — Launch scripts or attach to an HHVM server straight from VS Code. See the [debugger doc](https://github.com/PranayAgarwal/vscode-hack/blob/master/docs/debugging.md) for details on setup and usage. _This is a very early release. Please file any bugs at the Issues page._
+- Hack coverage check works again. A new icon in the editor status bar shows % coverage for the file and can be clicked to highlight uncovered areas. (Can be disabled by setting `"hack.enableCoverageCheck": false`)
+
 ## v0.7.0
 - Language Server mode is now on by default for users running HHVM 3.23 or later. Add `"hack.useLanguageServer": false` to your workspace config to disable it.
 
@@ -42,7 +46,7 @@ This extension adds the following Visual Studio Code settings. These can be set
 
 * `hack.clientPath`: Absolute path to the hh_client executable. This can be left empty if hh_client is already in your environment $PATH. A `docker exec` command is supported as well.
 * `hack.workspaceRootPath`: Absolute path to the workspace root directory. This will be the VS Code workspace root by default, but can be changed if the project is in a subdirectory or mounted in a Docker container.
-* `hack.enableCoverageCheck`: Enable calculation of Hack type coverage percentage for every file and display in status bar (default: `false`).
+* `hack.enableCoverageCheck`: Enable calculation of Hack type coverage percentage for every file and display in status bar (default: `true`).
 * `hack.useLanguageServer`: Start hh_client in Language Server mode. Only works for HHVM version 3.23 and above (default: `true`).
 
 ### Docker

docs/debugging.md

@@ -0,0 +1,62 @@
+# Using the HHVM Debugger
+
+HHVM versions 3.25 and later come with a built-in debugging extension that can be enabled with a runtime flag. You can use the VS Code debug interface to launch and debug PHP/Hack scripts or attach to an existing HHVM server process on a local or remote machine.
+
+## For local script execution
+
+Add a new HHVM `launch` config to `.vscode/launch.json`. The default template should be good enough, but you can change the values if needed:
+
+`script`: The PHP/Hack script to launch. Use `${file}` to run the currently open file in the editor, or set to any other static file path.
+`hhvmPath`: [Optional] Absolute path to the HHVM executable (default `hhvm`)
+`hhvmArgs`: [Optional] Extra arguments to pass to HHVM when launching the script, if needed
+`cwd`: [Optional] Working directory for the HHVM process
+
+Debug -> Start Debugging (F5) with this configuration selected will launch the currently open PHP/Hack script in a new HHVM process and pipe input/output to the editor OUTPUT tab.
+
+You will need to set breakpoints before script execution to be able to hit them.
+
+## For remote server debugging
+
+Start your HHVM server with the following additional configuration strings in server.ini or CLI args:
+
+`hhvm.debugger.vs_debug_enable=1` to enable the debugging extension  
+`hhvm.debugger.vs_debug_listen_port=<port>` to optionally change the port the debugger listens on (default: `8999`)  
+
+E.g. `hhvm -m server -p 8080 -d hhvm.debugger.vs_debug_enable=1 -d hhvm.debugger.vs_debug_listen_port=1234`
+
+Add a new HHVM `attach` config to `.vscode/launch.json` and configure as needed:
+
+`host`: [Optional] The remote HHVM host (default: `localhost`)  
+`port`: [Optional] The server debugging port, if changed in HHVM config (default: `8999`) 
+
+If the site root on the server is different from your local workspace, set the following to automatically map them: 
+
+`remoteSiteRoot`: [Optional] Absolute path to site root on the HHVM server  
+`localWorkspaceRoot`: [Optional] Absolute path to local workspace root. Set to `${workspaceFolder}` to use the current VS Code workspace.
+
+### SSH tunneling
+
+The HHVM debugger port is only exposed on the localhost (loopback) interface, so unless the server is running on the local machine you will likely need to foward a local port to the remote host via a SSH tunnel:
+
+`ssh -nNT -L 8999:localhost:8999 [email protected]`
+
+You can now connect to localhost:8999 as normal.
+
+### Docker containers
+
+For the same reason, Docker port forwarding won't work for the debugger port. You need to either use your host network driver for the container (`docker run` with `--network host`) or use SSH tunneling or other solutions like [socat](http://www.dest-unreach.org/socat/) instead.
+
+E.g. publish port 8998 to the Docker host and in your container install and run:
+
+`socat tcp-listen:8998,reuseaddr,fork tcp:localhost:8999`
+
+This will foward connections to exposed port 8998 to port 8999 in your container.
+
+### Common server debugging setups
+
+![Common debugging setups](images/debugger-setups.png)
+
+1. Single PHP/Hack script launched by VS Code 
+2. Everything running locally on the same network
+3. Connected to debugging port on a remote server through a SSH tunnel
+4. Running HHVM in a Docker container and forwarding debugger port via [socat](http://www.dest-unreach.org/socat/doc/socat.html)