Add --debug option to briefcase run

.github/workflows/ci.yml

@@ -46,6 +46,16 @@ jobs:
     with:
       attest: ${{ inputs.attest-package }}
 
+  package-debugger:
+    name: Package Debugger
+    permissions:
+      id-token: write
+      contents: read
+      attestations: write
+    uses: beeware/.github/.github/workflows/python-package-create.yml@main
+    with:
+      build-subdirectory: "debugger-support"
+
   package-automation:
     name: Package Automation
     permissions:
@@ -58,7 +68,7 @@ jobs:
 
   unit-tests:
     name: Unit tests
-    needs: [ pre-commit, towncrier, package ]
+    needs: [ pre-commit, towncrier, package, package-debugger ]
     runs-on: ${{ matrix.platform }}
     continue-on-error: ${{ matrix.experimental || false }}
     strategy:
@@ -101,7 +111,7 @@ jobs:
         requirements: tox
         extra: dev
 
-    - name: Test
+    - name: Test Briefcase
       id: test
       run: |
         RUNNER_OS=$(cut -d- -f1 <<< ${{ matrix.platform }})
@@ -124,6 +134,16 @@ jobs:
       # coverage reporting must use the same Python version used to produce coverage
       run: tox -qe coverage$(tr -dc "0-9" <<< "${{ matrix.python-version }}")
 
+    - name: Get Debugger Package
+      uses: actions/[email protected]
+      with:
+        name: ${{ needs.package-debugger.outputs.artifact-name }}
+        path: dist
+
+    - name: Test Debugger
+      run: |
+          tox -e py-debugger --installpkg dist/briefcase_debugger-*.whl
+
   coverage:
     name: Project coverage
     runs-on: ubuntu-24.04

.gitignore

@@ -5,6 +5,7 @@
 /dist
 /build
 automation/build
+debugger-support/build
 docs/_build/
 distribute-*
 .DS_Store

changes/2147.feature.rst

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

debugger-support/README.md

@@ -0,0 +1,7 @@
+# Briefcase Debugger Support
+This package contains the debugger support package for the `pdb` and `debugpy` debuggers.
+
+It starts the remote debugger automatically at startup through an .pth file, if a `BRIEFCASE_DEBUGGER` environment variable is set.
+
+## Installation
+Normally you do not need to install this package manually, because it is done automatically by briefcase using the `--debug=pdb` or `--debug=debugpy` option.

debugger-support/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = [
+    # keep versions in sync with automation/pyproject.toml and ../pyproject.toml
+    "setuptools==80.9.0",
+    "setuptools_scm==8.3.1",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "briefcase-debugger"
+description = "Add-on for briefcase to add remote debugging."
+readme = "README.md"
+license = "BSD-3-Clause"
+dependencies = [
+    # see "pdb" or "debugpy" optional dependencies below
+]
+dynamic = ["version"]
+
+[tool.setuptools_scm]
+root = "../"
+
+[project.optional-dependencies]
+dev = [
+    "pytest == 8.4.1",
+    "coverage[toml] == 7.10.2",
+]
+pdb = [
+    "remote-pdb>=2.1.0,<3.0.0"
+]
+debugpy = [
+    "debugpy>=1.8.14,<2.0.0"
+]
+
+[tool.coverage.run]
+parallel = true
+branch = true
+relative_files = true
+source_pkgs = ["briefcase_debugger"]
+
+[tool.coverage.paths]
+source = [
+    "src",
+    "**/site-packages",
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+skip_empty = true
+precision = 1

debugger-support/setup.py

@@ -0,0 +1,42 @@
+import os
+
+import setuptools
+from setuptools.command.install import install
+
+
+# Copied from setuptools:
+# (https://github.com/pypa/setuptools/blob/7c859e017368360ba66c8cc591279d8964c031bc/setup.py#L40C6-L82)
+class install_with_pth(install):
+    """Custom install command to install a .pth file for distutils patching.
+
+    This hack is necessary because there's no standard way to install behavior
+    on startup (and it's debatable if there should be one). This hack (ab)uses
+    the `extra_path` behavior in Setuptools to install a `.pth` file with
+    implicit behavior on startup to give higher precedence to the local version
+    of `distutils` over the version from the standard library.
+
+    Please do not replicate this behavior.
+    """
+
+    _pth_name = "briefcase_debugger"
+    _pth_contents = "import briefcase_debugger"
+
+    def initialize_options(self):
+        install.initialize_options(self)
+        self.extra_path = self._pth_name, self._pth_contents
+
+    def finalize_options(self):
+        install.finalize_options(self)
+        self._restore_install_lib()
+
+    def _restore_install_lib(self):
+        """Undo secondary effect of `extra_path` adding to `install_lib`"""
+        suffix = os.path.relpath(self.install_lib, self.install_libbase)
+
+        if suffix.strip() == self._pth_contents.strip():
+            self.install_lib = self.install_libbase
+
+
+setuptools.setup(
+    cmdclass={"install": install_with_pth},
+)

debugger-support/src/briefcase_debugger/__init__.py

@@ -0,0 +1,47 @@
+import json
+import os
+import sys
+import traceback
+
+
+def start_remote_debugger():
+    try:
+        # check verbose output
+        verbose = os.environ.get("BRIEFCASE_DEBUG", "0") == "1"
+
+        # reading config
+        config_str = os.environ.get("BRIEFCASE_DEBUGGER", None)
+
+        # skip debugger if no config is set
+        if config_str is None:
+            if verbose:
+                print(
+                    "No 'BRIEFCASE_DEBUGGER' environment variable found. Debugger not starting."
+                )
+            return  # If BRIEFCASE_DEBUGGER is not set, this packages does nothing...
+
+        if verbose:
+            print(f"'BRIEFCASE_DEBUGGER'={config_str}")
+
+        # Parsing config json
+        config = json.loads(config_str)
+
+        # start debugger
+        print("Starting remote debugger...")
+        if config["debugger"] == "debugpy":
+            from briefcase_debugger.debugpy import start_debugpy
+
+            start_debugpy(config, verbose)
+        elif config["debugger"] == "pdb":
+            from briefcase_debugger.pdb import start_pdb
+
+            start_pdb(config, verbose)
+        else:
+            raise ValueError(f"Unknown debugger '{config['debugger']}'")
+    except Exception:
+        # Show exception and stop the whole application when an error occurs
+        print(traceback.format_exc())
+        sys.exit(-1)
+
+
+start_remote_debugger()

debugger-support/src/briefcase_debugger/config.py

@@ -0,0 +1,20 @@
+from typing import TypedDict
+
+
+class AppPathMappings(TypedDict):
+    device_sys_path_regex: str
+    device_subfolders: list[str]
+    host_folders: list[str]
+
+
+class AppPackagesPathMappings(TypedDict):
+    sys_path_regex: str
+    host_folder: str
+
+
+class DebuggerConfig(TypedDict):
+    debugger: str
+    host: str
+    port: int
+    app_path_mappings: AppPathMappings | None
+    app_packages_path_mappings: AppPackagesPathMappings | None

debugger-support/src/briefcase_debugger/debugpy.py

@@ -0,0 +1,116 @@
+import os
+import re
+import sys
+from pathlib import Path
+
+import debugpy
+
+from briefcase_debugger.config import DebuggerConfig
+
+
+def find_first_matching_path(regex: str) -> str:
+    """Returns the first element of sys.paths that matches regex, otherwise None."""
+    for p in sys.path:
+        if re.search(regex, p):
+            return p
+    raise ValueError(f"No sys.path entry matches regex '{regex}'")
+
+
+def load_path_mappings(config: DebuggerConfig, verbose: bool) -> list[tuple[str, str]]:
+    app_path_mappings = config.get("app_path_mappings", None)
+    app_packages_path_mappings = config.get("app_packages_path_mappings", None)
+
+    mappings_list = []
+    if app_path_mappings:
+        device_app_folder = find_first_matching_path(
+            app_path_mappings["device_sys_path_regex"]
+        )
+        for app_subfolder_device, app_subfolder_host in zip(
+            app_path_mappings["device_subfolders"],
+            app_path_mappings["host_folders"],
+            strict=False,
+        ):
+            mappings_list.append(
+                (
+                    app_subfolder_host,
+                    str(Path(device_app_folder) / app_subfolder_device),
+                )
+            )
+    if app_packages_path_mappings:
+        device_app_packages_folder = find_first_matching_path(
+            app_packages_path_mappings["sys_path_regex"]
+        )
+        mappings_list.append(
+            (
+                app_packages_path_mappings["host_folder"],
+                str(Path(device_app_packages_folder)),
+            )
+        )
+
+    if verbose:
+        print("Extracted path mappings:")
+        for idx, p in enumerate(mappings_list):
+            print(f"[{idx}] host =   {p[0]}")
+            print(f"[{idx}] device = {p[1]}")
+
+    return mappings_list
+
+
+def start_debugpy(config: DebuggerConfig, verbose: bool):
+    host = config["host"]
+    port = config["port"]
+    path_mappings = load_path_mappings(config, verbose)
+
+    # There is a bug in debugpy that has to be handled until there is a new
+    # debugpy release, see https://github.com/microsoft/debugpy/issues/1943
+    if not hasattr(os, "__file__"):
+        if verbose:
+            print("'os.__file__' not available. Patching it...")
+        os.__file__ = ""
+
+    # Starting remote debugger...
+    print(f"Starting debugpy in server mode at {host}:{port}...")
+    debugpy.listen((host, port), in_process_debug_adapter=True)
+
+    if verbose:
+        # pydevd is dynamically loaded and only available after debugpy is started
+        import pydevd
+
+        pydevd.DebugInfoHolder.DEBUG_TRACE_LEVEL = 3
+
+    if len(path_mappings) > 0:
+        if verbose:
+            print("Adding path mappings...")
+
+        # pydevd is dynamically loaded and only available after a debugger has connected
+        import pydevd_file_utils
+
+        pydevd_file_utils.setup_client_server_paths(path_mappings)
+
+    print("The debugpy server started. Waiting for debugger to attach...")
+    print(
+        f"""
+To connect to debugpy using VSCode add the following configuration to '.vscode/launch.json':
+{{
+    "version": "0.2.0",
+    "configurations": [
+        {{
+            "name": "Briefcase: Attach (Connect)",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {{
+                "host": "{host}",
+                "port": {port}
+            }},
+            "justMyCode": false
+        }}
+    ]
+}}
+
+For more information see: https://briefcase.readthedocs.io/en/stable/how-to/debugging/vscode.html#bundled-app
+"""
+    )
+    debugpy.wait_for_client()
+
+    print("Debugger attached.")
+    print("-" * 75)

debugger-support/src/briefcase_debugger/pdb.py

@@ -0,0 +1,33 @@
+import sys
+
+from remote_pdb import RemotePdb
+
+from briefcase_debugger.config import DebuggerConfig
+
+
+def start_pdb(config: DebuggerConfig, verbose: bool):
+    """Start remote PDB server."""
+    # Parsing host/port
+    host = config["host"]
+    port = config["port"]
+
+    print(
+        f"""
+Remote PDB server opened at {host}:{port}.
+Waiting for debugger to attach...
+To connect to remote PDB use eg.:
+    - telnet {host} {port} (Windows)
+    - rlwrap socat - tcp:{host}:{port} (Linux, macOS)
+
+For more information see: https://briefcase.readthedocs.io/en/stable/how-to/debugging/console.html#bundled-app
+"""
+    )
+
+    # Create a RemotePdb instance
+    remote_pdb = RemotePdb(host, port, quiet=True)
+
+    # Connect the remote PDB with the "breakpoint()" function
+    sys.breakpointhook = remote_pdb.set_trace
+
+    print("Debugger client attached.")
+    print("-" * 75)