Debug via VS Code¶

You can use Visual Studio Code to debug a development app via briefcase dev, or a bundled app that is built via briefcase build and run via briefcase run - including mobile apps.

Development¶

During development on your host system, you can configure Visual Studio Code to start Briefcase. The "Run" menu in VS Code has an "Open Configurations" option; if that option is enabled, select it, and modify the configurations key so that it contains an entry like the following:

{
    ...
    "configurations": [
        ...
        {
            "name": "Briefcase: Dev",
            "type": "debugpy",
            "request": "launch",
            "module": "briefcase",
            "args": [
                "dev",
            ],
            "justMyCode": false
        }
    ]
}

If you need to specify other options to briefcase dev, you can specify them in the args value.

If "Open Configurations" isn't enabled, select "Add Configuration" instead, and then enter the following details:

Select "Python Debugger" as the debugger
Select "Module" as the debug configuration
Enter briefcase as the name of the module to run.

This will give you a stub configuration that is mostly correct; edit it to match the example above. The configuration will be saved in a .vscode/launch.json file in your project.

To start a debug session, open the debug view in VS Code using the sidebar, select the "Briefcase: Dev" configuration from the list at the top of the sidebar, and select "Start Debugging" from the "Run" menu. This will run briefcase dev in a debug session; you can set breakpoints, use the data inspection, use the debug console REPL and all other debugging features of VS Code. For more details about the VS Code configurations in the .vscode/launch.json file, see the VS Code documentation.

Bundled App¶

Experimental feature

This is currently an experimental feature that is only supported on Windows, macOS, iOS and Android.

To debug a bundled app, the app must be modified to include a bootstrap that will connect to the VS Code debugger. This is done by passing the --debug debugpy option to briefcase build:

$ briefcase build --debug debugpy

To build a mobile app, include the platform name in the build command - for example:

$ briefcase build iOS --debug debugpy

This will build your app in debug mode and add debugpy, and a package that automatically starts debugpy at the startup of your bundled app.

Then, select "Open Configurations" from the "Run" menu, and add a new debug configuration to your .vscode/launch.json file:

{
    "version": "0.2.0",
    "configurations": [
        ...
        {
            "name": "Briefcase: Attach",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "justMyCode": false
        }
    ]
}

You can now start your app in debug mode:

$ briefcase run --debug debugpy

To run a mobile app, include the platform name in the run command - for example:

$ briefcase run iOS --debug debugpy

Running the app in debug mode will automatically start the debugpy debugger and listen for incoming connections. By default it will listen on localhost and port 5678. The app will pause at the start of execution, waiting for the debugger to attach.

To attach the debugger, select the Debug sidebar, select the "Briefcase: Attach" configuration, and then select "Start Debugging" from the "Run" menu. The app will then resume, and the debugger will be enabled. You can then use any debugger features you require.

Debugging quirks¶

The VS Code debugger has some notable behavior when used to debug a Briefcase app:

The "Restart" debug control will not work. To restart the app, you need to disconnect the debugger, restart the app manually, running it with briefcase run --debug debugpy, and then re-connecting the debugger.
justMyCode must be set to false. When setting it to true, or not defining it at all, breakpoints are missed on some platforms (e.g., Windows). The reason for this is currently unknown.
pathMappings should not be set manually in the launch.json. The path mappings will be set by Briefcase programmatically and if setting it manually too the manual setting will overwrite settings by Briefcase.
VS Code will not honor any breakpoint in code that is part of a file that is ignored by .gitignore.