Document how to debug a Briefcase app with popular IDEs

[freakboy3742]

What is the problem or limitation you are having?

briefcase dev is the documented way to run a Briefcase app; however, the only way to debug an app with briefcase dev is to set a breakpoint() and use pdb. This is less than ideal, as modern IDEs provide built-in debuggers and test runners.

Describe the solution you'd like

Add documentation how to configure VSCode, PyCharm, and other common IDEs so that their native "run" and "test" mechanisms reproduce what briefcase dev does.

The tl;dr is that you need to:

1. Add every directory mentioned in sources to the PYTHONPATH
2. Set the working directory to the user's home directory
3. Remove the project directory (the directory that contains pyproject.tomlfrom the PYTHONPATH (it's usually the first entry insys.path`)
4. Run the app name as a module (i.e., the equivalent of python -m myapp)

To run in test mode, you also need to add all the directories mentioned in test_sources, plus change the runtime module to tests.myapp.

Specifics can be found by reverse engineering src/briefcase/commands/dev.py.

We should document the specific instructions for configuring common IDEs (at present, I'd say that means VSCode and PyCharm); but we should also document the generic requirements so that any other IDE user knows what is needed.

Describe alternatives you've considered

Continue to encourage briefcase dev and breakpoint().

Additional context

Documenting manual configuration is a stop-gap measure. Longer term, it would be desirable to capture these instructions as a Briefcase plugin for VSCode and PyCharm.

[pathunstrom]

Notes on PyCharm:

PyCharm has built in options for adding the content root (the "project" directory. . . usually) and the sources root to the path as part of its run function. Oddly, I cannot seem to disable the content root if I'm using the sources root. This might be a bug in pycharm.

The setting the working directory to the user's home is simple there's a field for it.

This also runs in the debugger without issue.

Testing configuration:

This was actually easier, I started with the default test runner configuration for pytest, and filled in the relevant fields. Here, the content root and sources root are actually separate check boxes and seem to work more reliably.

[merhovon]

Anleitung für das Debugging einer BeeWare-Anwendung in Visual Studio Code:

1. Vorbereitung des Projekts:

   • Stelle sicher, dass du das neueste BeeWare Briefcase und Visual Studio Code installiert hast.
   • Öffne dein BeeWare-Projekt in VS Code.

2. Konfiguration der Debugging-Einstellungen:

   • Gehe zu der Debug-Ansicht in VS Code (das Symbol, das wie ein Käfer aussieht, in der Sidebar).
   • Erstelle eine neue launch.json-Datei oder bearbeite die vorhandene mit der folgenden Konfiguration:

     {
         "version": "0.2.0",
         "configurations": [
             {
                 "name": "Python Debugger: Attach using Process Id",
                 "type": "python",
                 "request": "attach",
                 "processId": "${command:pickProcess}",
                 "justMyCode": true
             }
         ]
     }

3. Start des Debuggings:

   • Gebe im integrierten Terminal von VS Code den Befehl briefcase dev ein, um deine BeeWare-Anwendung zu starten.
   • Sobald deine Anwendung läuft, drücke F5 oder klicke auf den grünen "Start Debugging"-Button in der Debug-Ansicht. Du wirst aufgefordert, den Prozess auszuwählen, den du debuggen möchtest – wähle deine BeeWare-Anwendung.

4. Debugging:

   • Nutze die Debugging-Werkzeuge von VS Code, wie Breakpoints, Schritt-für-Schritt-Execution, Variableninspektion etc., um deine Anwendung zu debuggen.

5. Beenden des Debuggings:

   • Drücke Shift + F5 oder klicke auf den roten "Stop Debugging"-Button in der Debug-Ansicht, um den Debugging-Prozess zu beenden und zurück zur Entwicklungsumgebung zu gelangen.

[eltoro0815]

Hi:)

I tried to use the solution for debugging briefcase dev in Visual Code on a Windows 10 System.

My briefcase version is: 0.3.18

Visual Studio Code version is: 1.89.1

I tried to use this launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python Debugger: Attach using Process Id",
            "type": "python",
            "request": "attach",
            "processId": "${command:pickProcess}",
            "justMyCode": true
        }
    ]
}

I run briefcase dev in the integrated Terminal. I run the Debugger with the name Python Debugger: Attach using Process Id I am asked to select the process. The briefcase.exe is shown as expected. After selecting it there are shown three items under CALL STACK:

• MainThread
• daciaspringstatus output streamer
• Dummy-2

The problem is:

- None of my breakpoints is working

Can anybody validate if this solution actually works and give feedback?

[freakboy3742]

@eltoro0815 If you're on Windows, the issue is almost certainly the threading approach used by Windows apps. A Toga windows app immediately starts a subthread which is where the app actually runs. I have no idea if VSCode needs special handling to catch breakpoints in that subthread, but given that we're using the Windows threading API to start that thread, not the Python API, it wouldn't surprise me if VSCode isn't able to "see" the child thread.