Merge pull request #1360 from rmartin16/arch-checks

Implement architecture and bitness checks
beeware · Aug 30, 2023 · 7ceb159 · 7ceb159
2 parents dac307f + 5aedb7c
commit 7ceb159
Show file tree

Hide file tree

Showing 49 changed files with 844 additions and 233 deletions.
diff --git a/changes/1360.feature.rst b/changes/1360.feature.rst
@@ -0,0 +1 @@
+Support for less common environments, such as Linux on ARM, is improved and error messages for unsupported platforms are more accurate.
diff --git a/docs/conf.py b/docs/conf.py
@@ -97,6 +97,16 @@
 
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
+# API status indicators.
+rst_prolog = """
+.. role:: full
+.. role:: yes
+.. role:: ymmv
+.. |f| replace:: :full:`●`
+.. |y| replace:: :yes:`○`
+.. |v| replace:: :ymmv:`△`
+"""
+
 # -- Options for link checking -------------------------------------------------
 
 linkcheck_anchors_ignore = [
@@ -310,6 +320,17 @@
 # Location of word list.
 spelling_word_list_filename = "spelling_wordlist"
 
+# -- Options for link check -------------------------------------------
+
+linkcheck_ignore = [
+    r"./android.html",
+    r"./iOS.html",
+    r"./linux/system.html",
+    r"./macOS/app.html",
+    r"./web.html",
+    r"./windows/app.html",
+]
+
 # -- Options for Todos -------------------------------------------
 
 # If this is True, todo and todolist produce output, else they produce nothing. The default is False.

diff --git a/docs/reference/platforms/android.rst b/docs/reference/platforms/android.rst
@@ -2,6 +2,17 @@
 Android
 =======
 
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| Host Platform Support (:ref:`platform-support-key`)                |
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| macOS          | Windows              | Linux                      |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64 |
++========+=======+=====+========+=======+=====+========+=====+=======+
+| |f|    | |y|   |     | |f|    |       | |v| | |f|    | |v| | |v|   |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+
+
 When generating an Android project, Briefcase produces a Gradle project.
 
 Gradle requires an install of the Android SDK and a Java 17 JDK.

diff --git a/docs/reference/platforms/iOS.rst b/docs/reference/platforms/iOS.rst
@@ -2,6 +2,16 @@
 iOS
 ===
 
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| Host Platform Support (:ref:`platform-support-key`)                |
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| macOS          | Windows              | Linux                      |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64 |
++========+=======+=====+========+=======+=====+========+=====+=======+
+| |f|    | |y|   |     |        |       |     |        |     |       |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+
 When generating an iOS project, Briefcase produces an Xcode project.
 
 Icon format

diff --git a/docs/reference/platforms/index.rst b/docs/reference/platforms/index.rst
@@ -3,11 +3,71 @@ Platform support
 ================
 
 .. toctree::
-   :maxdepth: 2
+   :hidden:
 
    macOS/index
    windows/index
    linux/index
    iOS
    android
    web
+
+.. _platform-support-key:
+
+Key
+---
+
++-----+-------------------------------------+
+| |f| | Supported and tested in CI          |
++-----+-------------------------------------+
+| |y| | Supported and tested by maintainers |
++-----+-------------------------------------+
+| |v| | Supported but not tested regularly  |
++-----+-------------------------------------+
+
+
+.. |Gradle| replace:: **Gradle**
+.. _Gradle: ./android.html
+
+.. |iOS| replace:: **Xcode**
+.. _iOS: ./iOS.html
+
+.. |System| replace:: **Native System Packages**
+.. _System: ./linux/system.html
+
+.. |macOSApp| replace:: **.app bundle**
+.. _macOSApp: ./macOS/app.html
+
+.. |windowsApp| replace:: **Windows app**
+.. _windowsApp: ./windows/app.html
+
+.. |Web| replace:: **Static**
+.. _Web: ./web.html
+
++---------+--------------------------------------+--------+-------+---------+--------+---+-----+--------+-----+-------+
+| Target App Format                              | Host System                                                        |
++                                                +--------+-------+---------+--------+---+-----+--------+-----+-------+
+|                                                | macOS          | Windows              | Linux                      |
++                                                +--------+-------+-----+--------+-------+-----+--------+-----+-------+
+|                                                | x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64 |
++=========+======================================+========+=======+=====+========+=======+=====+========+=====+=======+
+| Android | |Gradle|_                            | |f|    | |y|   |     | |f|    |       | |v| | |f|    | |v| | |v|   |
++---------+--------------------------------------+--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| iOS     | |iOS|_                               | |f|    | |y|   |     |        |       |     |        |     |       |
++---------+--------------------------------------+--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| Linux   | :doc:`./linux/appimage`              | |f|    |       |     |        |       | |v| | |f|    |     |       |
++         +--------------------------------------+--------+-------+-----+--------+-------+-----+--------+-----+-------+
+|         | :doc:`./linux/flatpak`               |        |       |     |        |       | |v| | |f|    | |v| | |v|   |
++         +--------------------------------------+--------+-------+-----+--------+-------+-----+--------+-----+-------+
+|         | |System|_                            | |y|    | |y|   |     |        |       | |v| | |f|    | |v| | |v|   |
++---------+--------------------------------------+--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| macOS   | |macOSApp|_                          | |f|    | |y|   |     |        |       |     |        |     |       |
++         +--------------------------------------+--------+-------+-----+--------+-------+-----+--------+-----+-------+
+|         | :doc:`Xcode project <./macOS/xcode>` | |f|    | |y|   |     |        |       |     |        |     |       |
++---------+--------------------------------------+--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| Web     | |web|_                               | |f|    | |y|   | |v| | |f|    | |v|   | |v| | |f|    | |v| | |v|   |
++---------+--------------------------------------+--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| Windows | |windowsApp|_                        |        |       |     | |f|    |       |     |        |     |       |
++         +--------------------------------------+--------+-------+-----+--------+-------+-----+--------+-----+-------+
+|         | :doc:`./windows/visualstudio`        |        |       |     | |f|    |       |     |        |     |       |
++---------+--------------------------------------+--------+-------+-----+--------+-------+-----+--------+-----+-------+
diff --git a/docs/reference/platforms/linux/appimage.rst b/docs/reference/platforms/linux/appimage.rst
@@ -2,6 +2,16 @@
 AppImage
 ========
 
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| Host Platform Support (:ref:`platform-support-key`)                |
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| macOS          | Windows              | Linux                      |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64 |
++========+=======+=====+========+=======+=====+========+=====+=======+
+| |f|    |       |     |        |       | |v| | |f|    |     |       |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+
 `AppImage <https://appimage.org>`__ provides a way for developers to provide
 "native" binaries for Linux users. It allow packaging applications for any
 common Linux based operating system, including Ubuntu, Debian, Fedora, and more.

diff --git a/docs/reference/platforms/linux/flatpak.rst b/docs/reference/platforms/linux/flatpak.rst
@@ -2,6 +2,16 @@
 Flatpak
 =======
 
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| Host Platform Support (:ref:`platform-support-key`)                |
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| macOS          | Windows              | Linux                      |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64 |
++========+=======+=====+========+=======+=====+========+=====+=======+
+|        |       |     |        |       | |v| | |f|    | |v| | |v|   |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+
 `Flatpak <https://flatpak.org>`__ provides a way for developers to distribute
 apps to Linux users in a format that is independent of the specific distribution
 used by the end-user. It allow packaging applications for use on any common

diff --git a/docs/reference/platforms/linux/system.rst b/docs/reference/platforms/linux/system.rst
@@ -2,6 +2,16 @@
 Native System Packages
 ======================
 
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| Host Platform Support (:ref:`platform-support-key`)                |
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| macOS          | Windows              | Linux                      |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64 |
++========+=======+=====+========+=======+=====+========+=====+=======+
+| |y|    | |y|   |     |        |       | |v| | |f|    | |v| | |v|   |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+
 All modern Linux distributions have a native format for distributing packages
 that are integrated into their overall operating system:
 
@@ -12,17 +22,10 @@ that are integrated into their overall operating system:
 The Briefcase ``system`` backend provides a way to build your app in these
 system package formats.
 
-.. note:: Not all Linux distributions are currently supported!
-
-    At present, Briefcase only has full support for Debian-based distributions.
-    It should be possible to build and run an application on other Linux
-    distributions; however, it won't be possible to package the app for
-    distribution on those platforms. We intend to add support for other
-    packaging formats - patches are welcome.
+.. admonition:: Not all Linux distributions are supported!
 
-    In addition, Briefcase cannot reliably identify *every* Linux vendor. If
-    your Linux distribution isn't being identified (or isn't being identified
-    correctly), please `open a ticket
+    Briefcase cannot reliably identify *every* Linux vendor. If your Linux distribution
+    isn't being identified (or isn't being identified correctly), please `open a ticket
     <https://github.com/beeware/briefcase/issues>`__ with the contents of your
     ``/etc/os-release`` file.
 
@@ -108,13 +111,13 @@ supported by the vendor, and system Python is Python 3.8 or later.
 
 The following Linux vendors are known to work as Docker targets:
 
-  * Debian (e.g., ``debian:bullseye`` or ``debian:11``)
-  * Ubuntu (e.g., ``ubuntu:jammy`` or ``ubuntu:22.04``)
-  * Fedora (e.g, ``fedora:37``)
-  * AlmaLinux (e.g., ``almalinux:9``)
-  * Red Hat Enterprise Linux (e.g., ``redhat/ubi9:9``)
-  * Arch Linux (e.g., ``archlinux:latest``)
-  * Manjaro Linux (e.g., ``manjarolinux/base:latest``)
+* Debian (e.g., ``debian:bullseye`` or ``debian:11``)
+* Ubuntu (e.g., ``ubuntu:jammy`` or ``ubuntu:22.04``)
+* Fedora (e.g, ``fedora:37``)
+* AlmaLinux (e.g., ``almalinux:9``)
+* Red Hat Enterprise Linux (e.g., ``redhat/ubi9:9``)
+* Arch Linux (e.g., ``archlinux:latest``)
+* Manjaro Linux (e.g., ``manjarolinux/base:latest``)
 
 Application configuration
 =========================

diff --git a/docs/reference/platforms/macOS/app.rst b/docs/reference/platforms/macOS/app.rst
@@ -2,6 +2,16 @@
 .app bundle
 ===========
 
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| Host Platform Support (:ref:`platform-support-key`)                |
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| macOS          | Windows              | Linux                      |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64 |
++========+=======+=====+========+=======+=====+========+=====+=======+
+| |f|    | |y|   |     |        |       |     |        |     |       |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+
 A macOS ``.app`` bundle is a collection of directory with a specific layout,
 and with some key metadata. If this structure and metadata exists, macOS treats
 the folder as an executable file, giving it an icon.

diff --git a/docs/reference/platforms/macOS/xcode.rst b/docs/reference/platforms/macOS/xcode.rst
@@ -1,6 +1,16 @@
-=============
-Xcode project
-=============
+===================
+macOS Xcode project
+===================
+
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| Host Platform Support (:ref:`platform-support-key`)                |
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| macOS          | Windows              | Linux                      |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64 |
++========+=======+=====+========+=======+=====+========+=====+=======+
+| |f|    | |y|   |     |        |       |     |        |     |       |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
 
 Briefcase supports creating a full Xcode project for a macOS app. This project
 can then be used to build an actual app bundle, with the ``briefcase build``

diff --git a/docs/reference/platforms/web.rst b/docs/reference/platforms/web.rst
@@ -2,6 +2,16 @@
 Web
 ===
 
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| Host Platform Support (:ref:`platform-support-key`)                |
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| macOS          | Windows              | Linux                      |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64 |
++========+=======+=====+========+=======+=====+========+=====+=======+
+| |f|    | |y|   | |v| | |f|    | |v|   | |v| | |f|    | |v| | |v|   |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+
 When generating a web project, Briefcase produces a static folder of HTML, CSS
 and JavaScript resources that can be deployed as a web site. The static web site
 is packaged as a ``.zip`` file for distribution.

diff --git a/docs/reference/platforms/windows/app.rst b/docs/reference/platforms/windows/app.rst
@@ -2,6 +2,16 @@
 Windows App
 ===========
 
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| Host Platform Support (:ref:`platform-support-key`)                |
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| macOS          | Windows              | Linux                      |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64 |
++========+=======+=====+========+=======+=====+========+=====+=======+
+|        |       |     | |f|    |       |     |        |     |       |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+
 A Windows app is a stub binary, allow with a collection of folders that contain
 the Python code for the app and the Python runtime libraries.
 

diff --git a/docs/reference/platforms/windows/visualstudio.rst b/docs/reference/platforms/windows/visualstudio.rst
@@ -2,6 +2,16 @@
 Visual Studio project
 =====================
 
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| Host Platform Support (:ref:`platform-support-key`)                |
++--------+-------+---------+--------+---+-----+--------+-----+-------+
+| macOS          | Windows              | Linux                      |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+| x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64 |
++========+=======+=====+========+=======+=====+========+=====+=======+
+|        |       |     | |f|    |       |     |        |     |       |
++--------+-------+-----+--------+-------+-----+--------+-----+-------+
+
 Briefcase supports creating a full Visual Studio project for a Windows App. This
 project can then be used to build the stub app binary with the ``briefcase
 build`` command, or directly from Visual Studio.

diff --git a/setup.cfg b/setup.cfg
@@ -94,7 +94,7 @@ dev =
     pytest == 7.4.0
     pytest-xdist == 3.3.1
     setuptools_scm[toml] == 7.1.0
-    tox == 4.10.0
+    tox == 4.11.0
 docs =
     furo == 2023.8.19
     pyenchant == 3.2.2

diff --git a/src/briefcase/commands/create.py b/src/briefcase/commands/create.py
@@ -344,6 +344,7 @@ def _download_support_package(self, app: AppConfig):
                             python_version_tag=self.python_version_tag,
                             platform=self.platform,
                             host_arch=self.tools.host_arch,
+                            is_32bit=self.tools.is_32bit_python,
                         )
 
                 support_package_url = self.support_package_url(support_revision)
@@ -384,6 +385,7 @@ def _download_support_package(self, app: AppConfig):
                     python_version_tag=self.python_version_tag,
                     platform=self.platform,
                     host_arch=self.tools.host_arch,
+                    is_32bit=self.tools.is_32bit_python,
                 ) from e
 
     def _write_requirements_file(

diff --git a/src/briefcase/exceptions.py b/src/briefcase/exceptions.py
@@ -103,6 +103,18 @@ def __init__(self, tool):
         super().__init__(msg=f"Unable to locate {tool!r}. Has it been installed?")
 
 
+class IncompatibleToolError(BriefcaseCommandError):
+    def __init__(self, tool: str, env_var: str):
+        self.tool = tool
+        super().__init__(
+            msg=f"""\
+Briefcase cannot install {tool} on this machine.
+
+Install {tool} manually and specify the installation directory in the {env_var} environment variable.
+            """
+        )
+
+
 class NonManagedToolError(BriefcaseCommandError):
     def __init__(self, tool):
         self.tool = tool
@@ -153,16 +165,18 @@ def __init__(self, app_bundle_path):
 
 
 class MissingSupportPackage(BriefcaseCommandError):
-    def __init__(self, python_version_tag, platform, host_arch):
+    def __init__(self, python_version_tag, platform, host_arch, is_32bit):
         self.python_version_tag = python_version_tag
         self.platform = platform
         self.host_arch = host_arch
+        self.is_32bit = is_32bit
+        platform_name = f"{'32 bit ' if is_32bit else ''}{platform}"
         super().__init__(
             f"""\
-Unable to download {self.platform} support package for Python {self.python_version_tag} on {self.host_arch}.
+Unable to download {platform_name} support package for Python {self.python_version_tag} on {self.host_arch}.
 
-This is likely because either Python {self.python_version_tag} and/or {self.host_arch}
-is not yet supported on {self.platform}. You will need to:
+This is likely because either Python {self.python_version_tag} and/or {self.host_arch} is not yet
+supported on {platform_name}. You will need to:
     * Use an older version of Python; or
     * Compile your own custom support package.
 """