From 73a125ed41290c23035835f178443a326ca66124 Mon Sep 17 00:00:00 2001 From: baldurk Date: Wed, 12 Aug 2026 10:19:42 +0100 Subject: [PATCH] Document problems with VS Code path mappings * When adding a 'remote attach' target in VS Code it adds path mappings that then break itself when debugging on the same machine :(. --- docs/python_api/faq.rst | 9 +++++++++ docs/python_api/ide_integration.rst | 5 ++++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/python_api/faq.rst b/docs/python_api/faq.rst index 01dad5560..121718ce5 100644 --- a/docs/python_api/faq.rst +++ b/docs/python_api/faq.rst @@ -93,6 +93,15 @@ In theory RenderDoc's scripting works transparently regardless of where the repl However Android is an unstable, unreliable, and often broken platform. As a result the use of python scripting with Android captures is not considered officially supported. It is possible that you can use scripting when running on Android but this should be taken with care. +Why doesn't VS Code apply breakpoints or catch exceptions properly? +------------------------------------------------------------------- + +VS Code's python debugging requires some particular setup as in :doc:`ide_integration` and may only partially function if something is not configured as needed. + +If you find that script files open in a new tab even if the file is already open, and breakpoints aren't applied, you may have "path mappings" configured in your :file:`launch.json` when attaching the debugger. VS Code creates these by default when it adds remote debugging as an option, but RenderDoc does not. These mappings are intended for debugging across different machines but it causes VS Code to get confused when debugging on the same machine with the same path. You should delete these, and restart RenderDoc before trying to attach again. + +If exceptions are not being caught by VS Code, make sure you have the ``User Uncaught Exceptions`` setting under ``Breakpoints`` enabled, as RenderDoc itself catches otherwise-uncaught exceptions when running python code to improve UI stability and so VS Code's unhandled exception handler will not usually catch them. + .. _example_preamble: Why do the examples have a preamble for ``pyrenderdoc``? diff --git a/docs/python_api/ide_integration.rst b/docs/python_api/ide_integration.rst index 33338174d..6fc476559 100644 --- a/docs/python_api/ide_integration.rst +++ b/docs/python_api/ide_integration.rst @@ -46,7 +46,7 @@ Python Stubs Python modules written in C like RenderDoc's can't have type annotations that are key to providing good autocomplete in an IDE. The standard alternative is to provide python 'stub' files which are written in pure python and have no implementations, only signatures and other type annotations. -RenderDoc generates appropriate stubs within your application data directory with one per version as well as a rolling 'latest' version. On Windows this is ``%APPDATA%\qrenderdoc\pystubs`` and on linux it's ``~/.local/share/qrenderdoc/pystubs``. +RenderDoc generates appropriate stubs within your application data directory with one per version as well as a rolling 'latest' version. On Windows this is :file:`%APPDATA%\qrenderdoc\pystubs` and on linux it's :file:`~/.local/share/qrenderdoc/pystubs`. Typically you can use the ``latest`` version without problems, but if you are targeting a specific version of RenderDoc you can use one of the versioned directories. @@ -79,6 +79,9 @@ If RenderDoc has detected your installation of VS Code it also provides convenie You may also need to check the ``User Uncaught Exceptions`` setting under ``Breakpoints`` to properly trap exceptions that are thrown in the python code, as otherwise RenderDoc will catch them itself for display. +.. warning:: + By default, RenderDoc creates a :file:`.vscode` folder and :file:`launch.json` configuring the debugging setup for attaching, but it will not overwrite an existing file. Be warned that VS Code's default remote attach configuration contains "path mappings" which can cause RenderDoc debugging to not function correctly, since remote attach is normally not used on the same folder. It is strongly recommended you delete any path mappings and restart RenderDoc & VS Code if you have already tried to attach. + Next steps ----------