Allow running Linux System apps for foreign targets

Author: rmartin16

changes/1603.feature.rst

@@ -0,0 +1 @@
+The ``briefcase run`` command now supports the ``--target`` option to run Linux apps from within Docker for other distributions.

src/briefcase/bootstraps/toga.py

@@ -71,6 +71,9 @@ def pyproject_table_linux_system_debian(self):
     "libcairo2-dev",
     # Needed to compile PyGObject wheel
     "libgirepository1.0-dev",
+    # Needed to run the app
+    "gir1.2-gtk-3.0",
+    # "gir1.2-webkit2-4.0",
 ]
 
 system_runtime_requires = [
@@ -91,6 +94,8 @@ def pyproject_table_linux_system_rhel(self):
     "cairo-gobject-devel",
     # Needed to compile PyGObject wheel
     "gobject-introspection-devel",
+    # Needed to run the app
+    "gtk3",
 ]
 
 system_runtime_requires = [
@@ -112,6 +117,9 @@ def pyproject_table_linux_system_suse(self):
     "cairo-devel",
     # Needed to compile PyGObject wheel
     "gobject-introspection-devel",
+    # Needed to run the app
+    "gtk3", "typelib-1_0-Gtk-3_0",
+    # "libwebkit2gtk3", "typelib-1_0-WebKit2-4_1",
 ]
 
 system_runtime_requires = [

src/briefcase/integrations/docker.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import contextlib
 import json
 import operator
 import os
@@ -109,18 +110,17 @@ def ensure_console_is_safe(sub_method):
     """
 
     @wraps(sub_method)
-    def inner(sub: Subprocess, sub_args: SubprocessArgsT, *args, **kwargs):
+    def inner(sub: Subprocess, args: SubprocessArgsT, *wrapped_args, **wrapped_kwargs):
         """Evaluate whether conditions are met to remove any dynamic elements in the
         console before returning control to Subprocess.
 
         :param sub: Bound Subprocess object
-        :param sub_args: command line to run in subprocess
-        :param args: list of implicit strings that will be run as subprocess command
+        :param args: command line to run in subprocess
         :return: the return value for the Subprocess method
         """
         # Just run the command if no dynamic elements are active
         if not sub.tools.input.is_console_controlled:
-            return sub_method(sub, sub_args, *args, **kwargs)
+            return sub_method(sub, args, *wrapped_args, **wrapped_kwargs)
 
         remove_dynamic_elements = False
 
@@ -129,18 +129,18 @@ def inner(sub: Subprocess, sub_args: SubprocessArgsT, *args, **kwargs):
         # it may prompt the user to abort the script and dynamic elements
         # such as the Wait Bar can hide this message from the user.
         if sub.tools.host_os == "Windows":
-            executable = str(sub_args[0]).strip() if sub_args else ""
+            executable = str(args[0]).strip() if args else ""
             remove_dynamic_elements |= executable.lower().endswith(".bat")
 
         # Release control for commands that cannot be streamed.
-        remove_dynamic_elements |= kwargs.get("stream_output") is False
+        remove_dynamic_elements |= wrapped_kwargs.get("stream_output") is False
 
         # Run subprocess command with or without console control
         if remove_dynamic_elements:
             with sub.tools.input.release_console_control():
-                return sub_method(sub, sub_args, *args, **kwargs)
+                return sub_method(sub, args, *wrapped_args, **wrapped_kwargs)
         else:
-            return sub_method(sub, sub_args, *args, **kwargs)
+            return sub_method(sub, args, *wrapped_args, **wrapped_kwargs)
 
     return inner
 
@@ -177,6 +177,15 @@ def prepare(self):
         # This is a no-op; the native subprocess environment is ready-to-use.
         pass
 
+    @contextlib.contextmanager
+    def run_app_context(self, subprocess_kwargs: dict[str, ...]) -> dict[str, ...]:
+        """A manager to wrap subprocess calls to run a Briefcase project app.
+
+        :param subprocess_kwargs: initialized keyword arguments for subprocess calls
+        """
+        # This is a no-op; the native subprocess environment is ready-to-use.
+        yield subprocess_kwargs
+
     def full_env(self, overrides: dict[str, str]) -> dict[str, str]:
         """Generate the full environment in which the command will run.
 

src/briefcase/integrations/subprocess.py

@@ -43,18 +43,26 @@ class LinuxSystemPassiveMixin(LinuxMixin):
 
     @property
     def use_docker(self):
-        # The passive mixing doesn't expose the `--target` option, as it can't use
-        # Docker. However, we need the use_docker property to exist so that the
-        # app config can be finalized in the general case.
-        return False
+        # The system backend doesn't have a literal "--use-docker" option, but
+        # `use_docker` is a useful flag for shared logic purposes, so evaluate
+        # what "use docker" means in terms of target_image.
+        return bool(self.target_image)
+
+    def add_options(self, parser):
+        super().add_options(parser)
+        parser.add_argument(
+            "--target",
+            dest="target",
+            help="Docker base image tag for the distribution to target for the build (e.g., `ubuntu:jammy`)",
+            required=False,
+        )
 
     def parse_options(self, extra):
-        # The passive mixin doesn't expose the `--target` option, but if run infers
-        # build, we need target image to be defined.
-        options = super().parse_options(extra)
-        self.target_image = None
+        """Extract the target_image option."""
+        options, overrides = super().parse_options(extra)
+        self.target_image = options.pop("target")
 
-        return options
+        return options, overrides
 
     def build_path(self, app):
         # Override the default build path to use the vendor name,
@@ -196,13 +204,6 @@ class LinuxSystemMostlyPassiveMixin(LinuxSystemPassiveMixin):
     # The Mostly Passive mixin verifies that Docker exists and can be run, but
     # doesn't require that we're actually in a Linux environment.
 
-    @property
-    def use_docker(self):
-        # The system backend doesn't have a literal "--use-docker" option, but
-        # `use_docker` is a useful flag for shared logic purposes, so evaluate
-        # what "use docker" means in terms of target_image.
-        return bool(self.target_image)
-
     def app_python_version_tag(self, app: AppConfig):
         if self.use_docker:
             # If we're running in Docker, we can't know the Python3 version
@@ -372,22 +373,6 @@ def verify_tools(self):
         if self.use_docker:
             Docker.verify(tools=self.tools, image_tag=self.target_image)
 
-    def add_options(self, parser):
-        super().add_options(parser)
-        parser.add_argument(
-            "--target",
-            dest="target",
-            help="Docker base image tag for the distribution to target for the build (e.g., `ubuntu:jammy`)",
-            required=False,
-        )
-
-    def parse_options(self, extra):
-        """Extract the target_image option."""
-        options, overrides = super().parse_options(extra)
-        self.target_image = options.pop("target")
-
-        return options, overrides
-
     def clone_options(self, command):
         """Clone the target_image option."""
         super().clone_options(command)
@@ -792,7 +777,7 @@ def build_app(self, app: AppConfig, **kwargs):
             self.tools.subprocess.check_output(["strip", self.binary_path(app)])
 
 
-class LinuxSystemRunCommand(LinuxSystemPassiveMixin, RunCommand):
+class LinuxSystemRunCommand(LinuxSystemMixin, RunCommand):
     description = "Run a Linux system project."
     supported_host_os = {"Linux"}
     supported_host_os_reason = "Linux system projects can only be executed on Linux."
@@ -809,23 +794,24 @@ def run_app(
         # Set up the log stream
         kwargs = self._prepare_app_env(app=app, test_mode=test_mode)
 
-        # Start the app in a way that lets us stream the logs
-        app_popen = self.tools.subprocess.Popen(
-            [os.fsdecode(self.binary_path(app))] + passthrough,
-            cwd=self.tools.home_path,
-            **kwargs,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.STDOUT,
-            bufsize=1,
-        )
+        with self.tools[app].app_context.run_app_context(kwargs) as kwargs:
+            # Start the app in a way that lets us stream the logs
+            app_popen = self.tools[app].app_context.Popen(
+                [os.fsdecode(self.binary_path(app))] + passthrough,
+                cwd=self.tools.home_path,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                bufsize=1,
+                **kwargs,
+            )
 
-        # Start streaming logs for the app.
-        self._stream_app_logs(
-            app,
-            popen=app_popen,
-            test_mode=test_mode,
-            clean_output=False,
-        )
+            # Start streaming logs for the app.
+            self._stream_app_logs(
+                app,
+                popen=app_popen,
+                test_mode=test_mode,
+                clean_output=False,
+            )
 
 
 def debian_multiline_description(description):

src/briefcase/platforms/linux/system.py

@@ -119,6 +119,9 @@ def main():
     "libcairo2-dev",
     # Needed to compile PyGObject wheel
     "libgirepository1.0-dev",
+    # Needed to run the app
+    "gir1.2-gtk-3.0",
+    # "gir1.2-webkit2-4.0",
 ]
 
 system_runtime_requires = [
@@ -137,6 +140,8 @@ def main():
     "cairo-gobject-devel",
     # Needed to compile PyGObject wheel
     "gobject-introspection-devel",
+    # Needed to run the app
+    "gtk3",
 ]
 
 system_runtime_requires = [
@@ -156,6 +161,9 @@ def main():
     "cairo-devel",
     # Needed to compile PyGObject wheel
     "gobject-introspection-devel",
+    # Needed to run the app
+    "gtk3", "typelib-1_0-Gtk-3_0",
+    # "libwebkit2gtk3", "typelib-1_0-WebKit2-4_1",
 ]
 
 system_runtime_requires = [
@@ -1125,6 +1133,9 @@ def main():
     "libcairo2-dev",
     # Needed to compile PyGObject wheel
     "libgirepository1.0-dev",
+    # Needed to run the app
+    "gir1.2-gtk-3.0",
+    # "gir1.2-webkit2-4.0",
 ]
 
 system_runtime_requires = [
@@ -1143,6 +1154,8 @@ def main():
     "cairo-gobject-devel",
     # Needed to compile PyGObject wheel
     "gobject-introspection-devel",
+    # Needed to run the app
+    "gtk3",
 ]
 
 system_runtime_requires = [
@@ -1162,6 +1175,9 @@ def main():
     "cairo-devel",
     # Needed to compile PyGObject wheel
     "gobject-introspection-devel",
+    # Needed to run the app
+    "gtk3", "typelib-1_0-Gtk-3_0",
+    # "libwebkit2gtk3", "typelib-1_0-WebKit2-4_1",
 ]
 
 system_runtime_requires = [