Merge b022df8 into 2857b9a

projectDocs/dev/readme.md

@@ -11,6 +11,7 @@ This includes information on reporting issues, triaging issues, testing, transla
 * [NVDA Developer Guide](https://www.nvaccess.org/files/nvda/documentation/developerGuide.html)
 * [Technical design overview](../design/technicalDesignOverview.md)
 * [Configuring AppVeyor to build forks of NVDA (making a local build environment unnecessary)](./buildingNVDAOnAppVeyor.md)
+* [Remote debugging NVDA (for when you need to step through NVDA's code as it runs)](./remoteDebugging.md)
 * [NVDA ControllerClient manual (NVDA API for external applications to directly speak or braille messages, etc.)](https://github.com/nvaccess/nvda/tree/master/extras/controllerClient)
 * [Release process](../community/releaseProcess.md)
 

projectDocs/dev/remoteDebugging.md

@@ -0,0 +1,128 @@
+# Remote Debugging NVDA
+
+Sometimes, it is not possible to effectively debug a running copy of NVDA, especially if you rely on NVDA or another screen reader for development.
+In such cases, using a secondary machine to debug the running copy of NVDA can be helpful.
+This document explains how to use [Visual Studio Code] (VS Code) to remotely debug NVDA.
+It is recommended that you use the [Visual Studio Code Workspace Configuration for NVDA] when using VS Code as your IDE for NVDA development.
+
+Note: keyboard shortcuts used in this guide assume you are using VS Code in English with a QWERTY keyboard, and that you haven't customised your keymap.
+If they don't work, search the action in the Command Palette or Keyboard Shortcuts settings to find or change the key binding on your system.
+
+## You will need
+
+* Development machine: The machine with VS Code and all required extensions installed.
+  * It is recommended that you use VS Code with the [Remote - Tunnels] extension installed.
+  * To remotely debug NVDA, you must have the debug extension for the language you want to debug installed--[Python Debugger] for python and [C/C++] for C++.
+    The [Python C++ Debugger] is recommended for debugging Python and C++ simultaneously.
+  * Consider using the pre-configured NVDA VS Code workspace, which recommends all required extensions, and has other necessary settings configured.
+  * Alternatively, you can use Visual Studio Code for the Web to debug the remote copy of NVDA in a web browser if you wish.
+* Secondary machine: The machine with NVDA's source and the [NVDA dev environment] set up.
+  This is the machine you will use to run the copy of NVDA being debugged.
+  * As we are going to connect to VS Code, you will need to have VS Code installed.
+    Alternatively, you can use the [VS Code Standalone CLI].
+
+If you do not have (or do not want to use) two physical machines, you can use a virtual machine as the secondary machine.
+Depending on the virtualisation software (hypervisor) in use, this may require hardware virtualisation support.
+Without hardware virtualisation support, using a virtual machine will likely be slow, or may not be possible.
+
+Instructions on how to create and use virtual machines are out of scope for this document.
+Popular hypervisors for windows include [Oracle VM VirtualBox], [VMware Workstation] and [Microsoft Hyper-V].
+
+## Workflow
+
+### On the secondary machine
+
+1. Open your NVDA repository in VS Code.
+   E.g. in a terminal `cd` to the NVDA repo and run `code .`.
+2. Set up a Remote tunnel so that another instance of VS code can control this one:
+   1. Open the Command Palette (`Ctrl`+`Shift`+`P`) and select "Remote Tunnels: Turn on Remote Tunnel Access...".
+   2. Choose whether you want the tunnel to be open for this session (only when VS Code is open), or as a service (whenever you're logged in to this machine).
+      * Installing the tunnel as a service will keep it active in the background, even when VS Code is closed.
+        This option is not recommended.
+   3. Choose how you will publish the tunnel.
+      GitHub is probably easiest if you're already using GitHub for development.
+      If you're not already logged in, log in when asked.
+   4. A notification should appear informing you that your tunnel is available.
+      Take note of the tunnel's name.
+
+If you prefer, you can set up the tunnel [at the command line instead][CLI create tunnel].
+
+* `code tunnel` to create a session tunnel.
+* `code tunnel service install` to create a background service tunnel.
+
+### On the development machine
+
+1. Open VS Code.
+2. Open the Remote Menu (`Ctrl`+`Alt`+`O`) and choose "Connect to Tunnel...".
+   * If you do not have the Remote-Tunnels extension installed, select "Tunnel" to install it.
+3. Choose the account type you used to publish the tunnel from your secondary machine.
+   If you're not already logged in, log in when prompted.
+   Ensure you log in to the same account you used to publish the tunnel.
+4. Select the tunnel that you created from your secondary machine.
+   VS Code will let you know when you have connected.
+   * The first time you connect, this may take some time as VS Code downloads necessary components.
+   * Even if you have the required extensions installed locally, VS Code may prompt you to install them in the remote workspace.
+     If prompted, proceed with the installation of the extensions.
+5. Go to the Explorer view (`Ctrl`+`Shift`+`E`), select "Open Folder" and browse to the NVDA repository on the secondary machine (or type its path).
+6. VS Code on your development machine is now acting as a remote control for your secondary machine.
+   Anything you do now will be carried out on your secondary machine.
+7. With an appropriate `launch.json` (such as that in the NVDA VS Code workspace configuration) in the secondary machine's `.vscode` directory in the NVDA repository, you can now run and debug NVDA.
+   NVDA will run on the secondary machine, and you can interact with the Debug view on the development machine.
+
+If you prefer, you can also debug the remote copy of NVDA in a browser by entering the vscode.dev URL that was generated on the secondary machine.
+
+### When you're done
+
+When you're done, it's a good idea to disconnect from the remote tunnel on your development machine, and close the tunnel on your secondary machine.
+
+* On your development machine, make sure you've saved any changes you have made, then open the Remote menu (`Ctrl`+`Alt`+`O`) and choose "Close Remote Connection".
+* On your secondary machine, open the Command Palette (`Ctrl`+`Shift`+`P`) and run "Remote Tunnels: Turn off Remote Tunnel Access...".
+  Press "Yes" when prompted.
+  * If you created a session tunnel, closing VS Code without turning off remote tunnel access will close the tunnel until you open VS Code again.
+  * If you created the tunnel as a service, the tunnel will continue to remain active in the background until you turn off remote tunnel access.
+  * If you created the tunnel at the CLI, use `Ctrl`+`C` to close it.
+    If you created it as a service, run `code tunnel kill` to close the tunnel, or `code tunnel service uninstall` to remove it.
+
+## Example session: debug the date/time command
+
+1. Set up your development and secondary machines as above, so that your development machine is now controlling your secondary machine.
+2. On your development machine, navigate to `source/globalCommands.py`.
+   Use the Explorer view (`Ctrl`+`Shift`+`E`) to browse there, or the "Go to File..." command (`Ctrl`+`P`) to enter the path directly.
+3. go to the date/time script (`script_dateTime`).
+   Search (`Ctrl`+`F`) or use the breadcrumbs view (`Ctrl`+`Shift`+`.`) to browse through the symbols in the file (you can type to filter in this list).
+4. Insert a breakpoint (`F9`) in the `dateTime` script, for instance at the last line, and save the file (`Ctrl`+`S`).
+5. Open the Debug view (`Ctrl`+`Shift`+`D`) and ensure the appropriate debug launch configuration is selected (if you are using the pre-configured NVDA VS Code workspace, this is "NVDA (Python)").
+   Note that to get to the launch selector, you need to press right arrow when focused on the "Start Debugging" button.
+   The selector is not currently reachable with tab.
+6. Start debugging with the "Start Debugging" button (`F5`).
+   NVDA should start up on your secondary machine.
+7. On your secondary machine, execute the report time/date script (`NVDA`+`F12`).
+   On your secondary machine, you will not hear anything, as NVDA will hit a breakpoint before it has the chance to speak.
+   On your development machine, VS Code will let you know you have hit a breakpoint.
+8. Now you can inspect NVDA's state (variables, stack frames etc) in the Debug view.
+9. To continue debugging, run "Debug: Continue" (`F5`).
+   On your secondary machine, NVDA should report the time.
+10. To stop debugging, run "Debug: Stop" (`Shift`+`F5`).
+   When you're done with your breakpoint, toggle it off (`F9`) or remove it through the Debug view.
+
+## Further reading
+
+To learn more about debugging in VS Code, check out the following resources:
+
+* [Debugging in Visual Studio Code](https://code.visualstudio.com/Docs/editor/debugging)
+* [Debugging configurations for Python apps in Visual Studio Code](https://code.visualstudio.com/docs/python/debugging)
+* [Debug C++ in Visual Studio Code](https://code.visualstudio.com/docs/cpp/cpp-debug)
+* [Remote Tunnels documentation](https://code.visualstudio.com/docs/remote/tunnels)
+
+[NVDA dev environment]: createDevEnvironment.md
+[Visual Studio Code]: https://code.visualstudio.com/
+[Remote - Tunnels]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-server
+[Visual Studio Code Workspace Configuration for NVDA]: https://github.com/nvaccess/vscode-nvda
+[Python C++ Debugger]: https://marketplace.visualstudio.com/items?itemName=benjamin-simmonds.pythoncpp-debug
+[C/C++]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools
+[Oracle VM VirtualBox]: https://www.virtualbox.org/
+[VMware Workstation]: https://www.vmware.com/products/desktop-hypervisor/workstation-and-fusion
+[Microsoft Hyper-V]: https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/about/
+[Python Debugger]: https://marketplace.visualstudio.com/items?itemName=ms-python.debugpy
+[VS Code Standalone CLI]: https://code.visualstudio.com/docs/remote/tunnels#_alternative-downloads
+[CLI create tunnel]: https://code.visualstudio.com/docs/editor/command-line#_create-remote-tunnel