Debugging How-To

.gitignore

@@ -14,6 +14,7 @@ distribute-*
 .coverage.*
 coverage.xml
 venv*/
+.venv*/
 .vscode/
 .eggs/
 .tox/

changes/2147.feature.rst

@@ -0,0 +1 @@
+Added basic functions for an ``--debug <debugger>`` option.

docs/how-to/debugging/console.rst

@@ -0,0 +1,74 @@
+=================
+Debug via Console
+=================
+
+Debugging an app on the console is normally done via `PDB <https://docs.python.org/3/library/pdb.html>`_.
+It is possible to debug a briefcase app at different stages in your development
+process. You can debug a development app via ``briefcase dev``, but also an bundled
+app that is build via ``briefcase build`` and run via ``briefcase run``.
+
+
+Development
+-----------
+Debugging an development app is quiet easy. Just add ``breakpoint()`` inside
+your code and start the app via ``briefcase dev``. When the breakpoint got hit
+the pdb console opens on your console and you can debug your app.
+
+
+Bundled App
+-----------
+It is also possible to debug a bundled app. This is the only way to debug your
+app on a mobile device (iOS/Android). Note that there are some :ref:`limitations <debugging_limitations>`
+when debugging an bundled app.
+
+For this you need to embed a remote debugger into your app. This is done via:
+
+.. code-block:: console
+
+    $ briefcase build --debug pdb
+
+This will build your app in debug mode and add `remote-pdb <https://pypi.org/project/remote-pdb/>`_
+together with a package that automatically starts ``remote-pdb`` at the
+startup of your bundled app. Additionally it will optimize the app for
+debugging. This means e.g. that all ``.py`` files are accessible on the device.
+
+Then it is time to run your app. You can do this via:
+
+.. code-block:: console
+
+    $ briefcase run --debug pdb
+
+Running the app in debug mode will automatically start the ``remote-pdb`` debugger
+and wait for incoming connections. By default it will listen on ``localhost``
+and port ``5678``.
+
+Then it is time to create a new console window on your host system and connect
+to your bundled app by calling:
+
+.. tabs::
+
+  .. group-tab:: Windows
+
+    .. code-block:: console
+
+      $ telnet localhost 5678
+
+  .. group-tab:: Linux
+
+    .. code-block:: console
+
+      $ telnet localhost 5678
+
+    or
+
+    .. code-block:: console
+
+      $ rlwrap socat - tcp:localhost:5678
+
+  .. group-tab:: macOS
+
+    .. code-block:: console
+
+      $ rlwrap socat - tcp:localhost:5678
+
+The app will start after the connection is established.

docs/how-to/debugging/index.rst

@@ -0,0 +1,25 @@
+==============
+Debug your app
+==============
+
+If you get stuck when programming your app, it is time to debug your app. The
+following sections describe how you can debug your app with or without an IDE.
+
+.. toctree::
+   :maxdepth: 1
+
+   console
+   vscode
+
+
+.. _debugging_limitations:
+
+Limitations when debugging bundled apps
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To debug an bundle app you need an network connection from your host system to
+the device your are trying to debug. If your bundled app is also running on
+your host system this is no problem. But when debugging a mobile device your
+app is running on another device. Running an iOS app in simulator is also no
+problem, because the simulator shares the same network stack as your host.
+But on Android there is a separate network stack. That's why briefcase will
+automatically forward the port from your host to the Android device via ADB.

docs/how-to/debugging/vscode.rst

@@ -0,0 +1,83 @@
+================
+Debug via VSCode
+================
+
+Debugging is possible at different stages in your development process. It is
+different to debug a development app via ``briefcase dev`` than an bundled app
+that is build via ``briefcase build`` and run via ``briefcase run``.
+
+Development
+-----------
+During development on your host system you should use ``briefcase dev``. To
+attach VSCode debugger you can simply create a configuration like this,
+that runs ``briefcase dev`` for you and attaches a debugger.
+
+.. code-block:: JSON
+
+    {
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "Briefcase: Dev",
+                "type": "debugpy",
+                "request": "launch",
+                "module": "briefcase",
+                "args": [
+                    "dev",
+                ],
+                "justMyCode": false
+            },
+        ]
+    }
+
+
+Bundled App
+-----------
+It is also possible to debug a bundled app. This is the only way to debug your
+app on a mobile device (iOS/Android). Note that there are some :ref:`limitations <debugging_limitations>`
+when debugging an bundled app.
+
+For this you need to embed a remote debugger into your app. This is done via:
+
+.. code-block:: console
+
+    $ briefcase build --debug debugpy
+
+This will build your app in debug mode and add the `debugpy <https://code.visualstudio.com/docs/debugtest/debugging#_debug-console-repl>`_ together with a
+package that automatically starts ``debugpy`` at the startup of your bundled app.
+Additionally it will optimize the app for debugging. This means e.g. that all
+``.py`` files are accessible on the device.
+
+Then it is time to run your app. You can do this via:
+
+.. code-block:: console
+
+    $ briefcase run --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``. You can then connect your VSCode debugger to the app by
+creating a configuration like this in the ``launch.json`` file:
+
+.. code-block:: JSON
+
+    {
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "Briefcase: Attach",
+                "type": "debugpy",
+                "request": "attach",
+                "connect": {
+                    "host": "localhost",
+                    "port": 5678
+                }
+            }
+        ]
+    }
+
+The app will not start until you attach the debugger. Once you attached the
+VSCode debugger you are ready to debug your app. You can set `breakpoints <https://code.visualstudio.com/docs/debugtest/debugging#_breakpoints>`_
+, use the `data inspection <https://code.visualstudio.com/docs/debugtest/debugging#_data-inspection>`_
+, use the `debug console REPL <https://code.visualstudio.com/docs/debugtest/debugging#_debug-console-repl>`_
+and all other debugging features of VSCode :)

docs/how-to/index.rst

@@ -17,6 +17,7 @@ stand alone.
    ci
    cli-apps
    x11passthrough
+   debugging/index
    external-apps
    publishing/index
    contribute/index

docs/reference/commands/build.rst

@@ -113,6 +113,24 @@ If you have previously run the app in "normal" mode, you may need to pass ``-r``
 / ``--update-requirements`` the first time you build in test mode to ensure that
 your testing requirements are present in the test app.
 
+``--debug <debugger>``
+----------------------
+
+Build the app in debug mode in the bundled app environment and establish an
+debugger connection via a socket. This installs the selected debugger in the
+bundled app.
+
+Currently the following debuggers are supported (default is ``pdb``):
+
+- ``pdb``: This is used for debugging via console (see :doc:`Debug via Console </how-to/debugging/console>`)
+- ``debugpy``: This is used for debugging via VSCode (see :doc:`Debug via VSCode </how-to/debugging/vscode>`)
+
+It also optimizes the app for debugging. E.g. on Android it ensures, that all
+`.py` files are extracted from the APK and are accessible for the debugger.
+
+This option may slow down the app a little bit.
+
+
 ``--no-update``
 ---------------
 

docs/reference/commands/run.rst

@@ -137,6 +137,39 @@ contains the most recent test code. To prevent this update and build, use the
 Prevent the automated update and build of app code that is performed when
 specifying by the ``--test`` option.
 
+``--debug <debugger>``
+----------------------
+
+Run the app in debug mode in the bundled app environment and establish an
+debugger connection via a socket.
+
+Currently the following debuggers are supported (default is ``pdb``):
+
+- ``pdb``: This is used for debugging via console (see :doc:`Debug via Console </how-to/debugging/console>`)
+- ``debugpy``: This is used for debugging via VSCode (see :doc:`Debug via VSCode </how-to/debugging/vscode>`)
+
+For ``debugpy`` there is also a mapping of the source code from your bundled
+app to your local copy of the apps source code in the ``build`` folder. This
+is useful for devices like iOS and Android, where the running source code is
+not available on the host system.
+
+``--debugger-host <host>``
+--------------------------
+
+Specifies the host of the socket connection for the debugger. This
+option is only used when the ``--debug <debugger>`` option is specified. The
+default value is ``localhost``.
+
+``--debugger-port <port>``
+--------------------------
+
+Specifies the port of the socket connection for the debugger. This
+option is only used when the ``--debug <debugger>`` option is specified. The
+default value is ``5678``.
+
+On Android this also forwards the port from the Android device to the host pc
+via ADB if the port is ``localhost``.
+
 Passthrough arguments
 ---------------------
 

pyproject.toml

@@ -136,6 +136,10 @@ Console = "briefcase.bootstraps.console:ConsoleBootstrap"
 PySide6 = "briefcase.bootstraps.pyside6:PySide6GuiBootstrap"
 Pygame = "briefcase.bootstraps.pygame:PygameGuiBootstrap"
 
+[project.entry-points."briefcase.debuggers"]
+pdb = "briefcase.debuggers.pdb:PdbDebugger"
+debugpy = "briefcase.debuggers.debugpy:DebugpyDebugger"
+
 [project.entry-points."briefcase.platforms"]
 android = "briefcase.platforms.android"
 iOS = "briefcase.platforms.iOS"

src/briefcase/commands/base.py

@@ -21,6 +21,8 @@
 from packaging.version import Version
 from platformdirs import PlatformDirs
 
+from briefcase.debuggers import get_debugger, get_debuggers
+
 if sys.version_info >= (3, 11):  # pragma: no-cover-if-lt-py311
     import tomllib
 else:  # pragma: no-cover-if-gte-py311
@@ -134,6 +136,8 @@ class BaseCommand(ABC):
     output_format: str
     # supports passing extra command line arguments to subprocess
     allows_passthrough = False
+    # supports remote debugging
+    supports_debugger = False
     # if specified for a platform, then any template for that platform must declare
     # compatibility with that version epoch. An epoch begins when a breaking change is
     # introduced for a platform such that older versions of a template are incompatible
@@ -681,7 +685,12 @@ def finalize_app_config(self, app: AppConfig):
         :param app: The app configuration to finalize.
         """
 
-    def finalize(self, app: AppConfig | None = None, test_mode: bool = False):
+    def finalize(
+        self,
+        app: AppConfig | None = None,
+        test_mode: bool = False,
+        debugger: str | None = None,
+    ):
         """Finalize Briefcase configuration.
 
         This will:
@@ -701,6 +710,7 @@ def finalize(self, app: AppConfig | None = None, test_mode: bool = False):
         apps = self.apps.values() if app is None else [app]
         for app in apps:
             if hasattr(app, "__draft__"):
+                self.finalize_debugger(app, debugger)
                 app.test_mode = test_mode
                 self.finalize_app_config(app)
                 delattr(app, "__draft__")
@@ -726,6 +736,18 @@ def finalize(self, app: AppConfig | None = None, test_mode: bool = False):
                             f"{app.app_name!r} defines 'external_package_executable_path', but not 'external_package_path'."
                         )
 
+    def finalize_debugger(self, app: AppConfig, debugger_name: str | None = None):
+        """Finalize the debugger configuration.
+
+        This will ensure that the debugger is available and that the app
+        configuration is valid.
+
+        :param app: The app configuration to finalize.
+        """
+        if debugger_name and debugger_name != "":
+            debugger = get_debugger(debugger_name)
+            app.debugger = debugger
+
     def verify_app(self, app: AppConfig):
         """Verify the app is compatible and the app tools are available.
 
@@ -982,6 +1004,28 @@ def _add_test_options(self, parser, context_label):
             help=f"{context_label} the app in test mode",
         )
 
+    def _add_debug_options(self, parser, context_label):
+        """Internal utility method for adding common debug-related options.
+
+        :param parser: The parser to which options should be added.
+        :param context_label: Label text for commands; the capitalized action being
+            performed (e.g., "Build", "Run",...)
+        """
+        debuggers = get_debuggers()
+        debugger_names = list(reversed(debuggers.keys()))
+        choices_help = [f"'{choice}'" for choice in debugger_names]
+
+        parser.add_argument(
+            "--debug",
+            dest="debugger",
+            nargs="?",
+            default=None,
+            const="pdb",
+            choices=debugger_names,
+            metavar="DEBUGGER",
+            help=f"{context_label} the app with the specified debugger. One of {', '.join(choices_help)} (default: pdb)",
+        )
+
     def add_options(self, parser):
         """Add any options that this command needs to parse from the command line.