Briefcase

Features

* Existing projects with a `pyproject.toml` configuration can now be converted into Briefcase apps using the `briefcase convert` command. (1202)
* Apps packaged as AppImages are no longer dependent on `libcrypt.so.1`. (1383)
* The `briefcase run` command now supports the `--target` option to run Linux apps from within Docker for other distributions. (1603)
* The hints and recommendations that Docker prints in the console are now silenced. (1635)
* In non-interactive environments, such as CI, a message is now printed to signify a task has begun where an animated bar would be displayed in interactive console sessions. (1649)
* Additional options can now be passed to the `docker build` command for building native Linux packages and AppImages via the `--Xdocker-build` argument. (1661)
* The contents of `pyproject.toml` is now included in the log file. (1674)
* When an app runs on an Android device or emulator, the logging output is now colored. (1676)
* When deep debug is activated via `-vv`, `pip` now installs requirements for the app with verbose logging. (1708)
* The listing of filenames for updating permissions for building native Linux packages is now only shown when verbose logging is enabled via `-v`. (1720)
* When a platform supports a splash screen, that splash screen will be generated automatically based on the app icon, rather than requiring additional configuration. (1737)
* New projects for Toga on GTK3 now recommend using `gir1.2-webkit2-4.1` instead of `gir1.2-webkit2-4.0` for `WebView` support. (1748)

Bugfixes

* When Briefcase can't find `rpmbuild` on an RPM-based system, the message giving install instructions now uses the correct package name. (1638)
* Creating new projects is now compatible with cookiecutter v2.6.0. (1663)
* The minimum version of pip was bumped to 23.1.2 to ensure compatibility with Python 3.12. (1681)
* On Windows, the Android emulator will always open without needing to press CTRL-C. (1687)
* A spurious Android emulator named `INFO` will no longer be included in the list of available emulators. (1697)
* The configuration generated for iOS apps declaring geolocation permissions has been corrected. (1713)
* When using `-r/--update-requirements` for building for Android, the app's requirements are always reinstalled now. (1721)
* When creating a new project, the validation for App Name now rejects all non-ASCII values. (1762)
* Packages created for OpenSUSE now depend on `libcanberra-gtk3-module` instead of `libcanberra-gtk3-0`. (1774)


Backward Incompatible Changes

* WiX v3.14.1 is now used to package Windows apps. Run `briefcase upgrade wix` to start using this version. (1707)
* Java JDK 17.0.11+9 is now used to package Android apps. Use `briefcase upgrade java` to update your Briefcase-installed JDK instance to this version. (1736)
* The `splash` configuration option will no longer be honored. Splash screens are now generated based on the icon image. (1737)
* iOS apps now require 640px, 1280px and 1920px icon image. (1737)
* Android apps now require an `adaptive` variant for icons. This requires 108px, 162px, 216px, 324px and 432px images with a transparent background. The Android `square` icon variant requires additional 320px, 480px, 640px, 960px and 1280px images. (1737)

Documentation

* The documentation contribution guide was updated to use a more authoritative reStructuredText reference. (1695)
* The README badges were updated to display correctly on GitHub. (1763)

Misc

* 1428, 1495, 1637, 1639, 1642, 1643, 1644, 1645, 1646, 1652, 1653, 1656, 1657, 1658, 1659, 1660, 1666, 1671, 1672, 1679, 1683, 1684, 1686, 1689, 1690, 1691, 1692, 1694, 1699, 1700, 1701, 1702, 1710, 1711, 1712, 1716, 1717, 1722, 1723, 1725, 1730, 1731, 1732, 1741, 1742, 1743, 1744, 1745, 1752, 1753, 1754, 1756, 1757, 1758, 1759, 1760, 1761, 1766, 1769, 1775, 1776

Features

* Android apps are now able to customize the libraries included in the app at build time. (485)
* App permissions can now be declared as part of an app's configuration. (547)
* The `-C`/`--config` option can now be used to override app settings from the command line. (1115)
* The verbosity flag, `-v`, was expanded to support three levels of logging verbosity. (1501)
* Briefcase now supports GUI bootstrap plugins to customize how new projects are created. (1524)
* GitPython's debug logging is now included in deep debug output. (1529)
* RCEdit v2.0.0 is now used to build Windows apps. Run `briefcase upgrade` to use this latest version. (1543)
* The Flatpak runtimes for new projects were updated. `org.freedesktop.Platform` will now default to 23.08; `org.gnome.Platform` will now default to 45; and `org.kde.Platform` will now default to 6.6. (1545)
* When creating new projects with the `briefcase new` command, project configuration overrides can be specified via the `-Q` command line argument. For instance, a specific license can be specified with `-Q "license=MIT license"`. (1552)
* New virtual devices for the Android emulator are created using the Pixel 7 Pro skin. (1554)
* The web server for running static web projects now falls back to a system allocated port if the requested port is already in use. (1561)
* Flatpaks are now created with permissions to access the GPU and sound devices. (1563)
* AppImages can now be built for the ARM architecture. (1564)
* Apps can now specify a primary color (for both light and dark modes), and an accent color. If the platform allows apps to customize color use, these colors will be used to style the app's presentation. (1566)
* The version of PursuedPyBear for new projects was bumped from 1.1 to 3.2.0. (1592)
* Python 3.12 is now supported on Android. (1596)
* Android apps can now specify the base theme used to style the application. (1610)
* The Java JDK was upgraded from 17.0.8.1+1 to 17.0.10+7. Run `briefcase upgrade java` to upgrade existing Briefcase installations. (1611)
* When the Android emulator fails to start up properly, users are now presented with additional resources to help resolve any issues. (1630)

Bugfixes

* When a custom Briefcase template from a git repository is used to create an app, Briefcase now ensures that git repository is always used. (1158)
* The filter for iOS build warnings was improved to catch messages from Xcode 15.0.1. (1507)
* When merging dependencies on macOS, file permissions are now preserved. (1510)
* `flatpak-builder` 1.3+ can now be correctly identified. (1513)
* The BeeWare icon of Brutus is now used as the runtime icon for new projects created with PyGame. (1532)
* Linux System RPM packaging for openSUSE Tumbleweed no longer errors with `FileNotFoundError`. (1595)
* Any ANSI escape sequences or console control codes are now stripped in all output captured in the Briefcase log file. (1604)
* The detection of physical Android devices on macOS was made more resilient. (1627)

Backward Incompatible Changes

* The use of AppImage as an output format now generates a warning. (1500)
* Support for creating new projects using PySide2 has been removed. Briefcase's release testing will no longer explicitly verify compatibility with PySide2. (1524)
* The Flatpak build process no longer strips binaries included in third-party (e.g. PyPI) packages that are bundled with the app. (1540)
* New projects will now use `manylinux_2_28` instead of `manylinux2014` to create AppImages in Docker. (1564)
* It is highly recommended that Android applications add a definition for `build_gradle_dependencies` to their app configuration. A default value will be used if this option is not explicitly provided. Refer to [the Android documentation](https://briefcase.readthedocs.io/en/latest/reference/platforms/android/gradle.html#build-gradle-dependencies) for the default value that will be used. (1610)

Documentation

* The common options available to every command have now been documented. (1517)

Misc

* 1504, 1505, 1506, 1515, 1516, 1518, 1519, 1526, 1527, 1533, 1534, 1535, 1536, 1538, 1541, 1548, 1549, 1550, 1551, 1555, 1556, 1557, 1560, 1562, 1567, 1568, 1569, 1571, 1575, 1576, 1579, 1582, 1585, 1586, 1589, 1590, 1597, 1606, 1607, 1613, 1614, 1615, 1618, 1621, 1622, 1623, 1624, 1628, 1632, 1633

Features

* Support for less common environments, such as Linux on ARM, has been improved. Error messages for unsupported platforms are now more accurate. (1360)
* Tool verification for Java, Android SDK, and WiX have been improved to provide more informative errors and debug logging. (1382)
* A super verbose logging mode was added (enabled using `-vv`). This turns on all Briefcase internal logging, but also enables verbose logging for all the third-party tools that Briefcase invokes. (1384)
* Briefcase now uses Android SDK Command-Line Tools v9.0. If an externally-managed Android SDK is being used, it must provide this version of Command-Line Tools. Use the SDK Manager in Android Studio to ensure it is installed. (1397)
* Support for OpenSuSE Linux distributions was added. (1416)
* iOS apps are no longer rejected by the iOS App Store for packaging reasons. (1439)
* The Java JDK version was upgraded to 17.0.8.1+1. (1462)
* macOS apps can now be configured to produce single platform binaries, or binaries that will work on both x86_64 and ARM64. (1482)


Bugfixes

* Build warnings caused by bugs in Xcode that can be safely ignored are now filtered out of visible output. (377)
* The run command now ensures Android logging is shown when the datetime on the device is different from the host machine. (1146)
* Briefcase will detect if you attempt to launch an Android app on a device whose OS doesn't meet minimum version requirements. (1157)
* macOS apps are now guaranteed to be universal binaries, even when dependencies only provide single-architecture binary wheels. (1217)
* The ability to build AppImages in Docker on macOS was restored. (1352)
* Error reporting has been improved when the target Docker image name is invalid. (1368)
* Creating Debian packages no longer fails due to a permission error for certain `umask` values (such as `0077`). (1369)
* Inside of Docker containers, the Briefcase data directory is now mounted at `/briefcase` instead of `/home/brutus/.cache/briefcase`. (1374)
* The console output from invoking Python via a subprocess call is now properly decoded as UTF-8. (1407)
* The command line arguments used to configure the Python environment for `briefcase dev` no longer leak into the runtime environment on macOS. (1413)


Backward Incompatible Changes

* AppImage packaging requires a recent release of LinuxDeploy to continue creating AppImages. Run `briefcase upgrade linuxdeploy` to install the latest version. (1361)
* The size of iOS splash images have changed. iOS apps should now provide 800px, 1600px and 2400px images (previously, this as 1024px, 2048px and 3072px). This is because iOS 14 added a hard limit on the size of image resources. (1371)
* Support for AppImage has been reduced to "best effort". We will maintain unit test coverage for the AppImage backend, but we no longer build AppImages as part of our release process. We will accept bug reports related to AppImage support, and we will merge PRs that address AppImage support, but the core team no longer considers addressing AppImage bugs a priority, and discourages the use of AppImage for new projects. (1449)


Documentation

* Documentation on the process of retrieving certificate identities on macOS and Windows was improved. (1473)


Misc

* 1136, 1290, 1363, 1364, 1365, 1372, 1375, 1376, 1379, 1388, 1394, 1395, 1396, 1398, 1400, 1401, 1402, 1403, 1408, 1409, 1410, 1411, 1412, 1418, 1419, 1420, 1421, 1427, 1429, 1431, 1433, 1435, 1436, 1437, 1438, 1442, 1443, 1444, 1445, 1446, 1447, 1448, 1454, 1455, 1456, 1457, 1464, 1465, 1466, 1470, 1474, 1476, 1477, 1478, 1481, 1485, 1486, 1487, 1488, 1489, 1490, 1492, 1494

Features

* Windows apps can now be packaged as simple ZIP files. (457)
* An Android SDK specified in `ANDROID_HOME` is respected now and will take precedence over the setting of `ANDROID_SDK_ROOT`. (463)
* Android support was upgraded to use Java 17 for builds. (1065)
* On Linux, Docker Desktop and rootless Docker are now supported. (1083)
* The company/author name in the installation path for Windows MSI installers is now optional. (1199)
* macOS code signing is now multi-threaded (and therefore much faster!) (1201)
* Briefcase will now honor PEP-621 project fields where they map to Briefcase configuration items. (1203)

Bugfixes

* XML compatibility warnings generated by the Android build have been cleaned up. (827)
* Non ASCII characters provided in the `briefcase new` wizard are quoted before being put into `pyproject.toml`. (1011)
* Requests to the web server are now recorded in the log file. (1090)
* An "Invalid Keystore format" error is no longer raised when signing an app if the local Android keystore was generated with a recent version of Java. (1112)
* Content before a closing square bracket (`]`) or `.so)` is no longer stripped by the macOS and iOS log filter. (1179)
* The option to run Linux system packages through Docker was removed. (1207)
* Error handling for incomplete or corrupted Github clones of templates has been improved. (1210)
* Application/Bundle IDs are normalized to replace underscores with dashes when possible (1234)
* Filenames and directories in RPM package definitions are quoted in order to include filenames that include white space. (1236)
* Briefcase will no longer display progress bars if the `FORCE_COLOR` environment variable is set. (1267)
* When creating a new Briefcase project, the header line in `pyproject.toml` now contains the version of Briefcase instead of "Unknown". (1276)
* Android logs no longer include timestamp and PID, making them easier to read on narrow screens. (1286)
* An warning is no longer logged if the Java identified by macOS is not usable by Briefcase. (1305)
* Incompatibilities with Cookiecutter 2.2.0 have been resolved. (1347)

Backward Incompatible Changes

* Names matching modules in the Python standard library, and `main`, can no longer be used as an application name. (853)
* The `--no-sign` option for packaging was removed. Briefcase will now prompt for a signing identity during packaging, falling back to adhoc/no signing as a default where possible. (865)
* The version of OpenJDK for Java was updated from 8 to 17. Any Android apps generated on previous versions of Briefcase must be re-generated by running `briefcase create android gradle`. If customizations were made to files within the generated app, they will need to be manually re-applied after re-running the create command. (1065)
* Flatpak apps no longer default to using the Freedesktop runtime and SDK version 21.08 when a runtime is not specified. Instead, the runtime now must be explicitly defined in the [application configuration](https://briefcase.readthedocs.io/en/latest/reference/platforms/linux/flatpak.html#application-configuration). (1272)


Documentation

* All code blocks were updated to add a button to copy the relevant contents on to the user's clipboard. (1213)
* The limitations of using WebKit2 in AppImage were documented. (1322)

Misc
----

* 856, 1093, 1178, 1181, 1186, 1187, 1191, 1192, 1193, 1195, 1197, 1200, 1204, 1205, 1206, 1215, 1226, 1228, 1232, 1233, 1239, 1241, 1242, 1243, 1244, 1246, 1248, 1249, 1253, 1254, 1255, 1257, 1258, 1262, 1263, 1264, 1265, 1273, 1274, 1279, 1282, 1283, 1284, 1293, 1294, 1295, 1299, 1300, 1301, 1310, 1311, 1316, 1317, 1323, 1324, 1333, 1334, 1335, 1336, 1339, 1341, 1350, 1351

Features

* Added support for code signing Windows apps. (366)
* The base image used to build AppImages is now user-configurable. (947)
* Support for Arch `.pkg.tar.zst` packaging was added to the Linux system backend. (1064)
* Pygame was added as an explicit option for a GUI toolkit. (1125)
* AppImage and Flatpak builds now use [indygreg's Python Standalone Builds](https://github.com/indygreg/python-build-standalone) to provide Python support. (#1132)
* BeeWare now has a presence on Mastodon. (1142)


Bugfixes

* When commands produce output that cannot be decoded to Unicode, Briefcase now writes the bytes as hex instead of truncating output or canceling the command altogether. (1141)
* When `JAVA_HOME` contains a path to a file instead of a directory, Briefcase will now warn the user and install an isolated copy of Java instead of logging a `NotADirectoryError`. (1144)
* If the Docker `buildx` plugin is not installed, users are now directed by Briefcase to install it instead of Docker failing to build the image. (1153)


Misc

* 1133, 1138, 1139, 1140, 1147, 1148, 1149, 1150, 1151, 1156, 1162, 1163, 1168, 1169, 1170, 1171, 1172, 1173, 1177

Features

* Distribution artefacts are now generated into a single `dist` folder. (424)
* When installing application sources and dependencies, any `__pycache__` folders are now automatically removed. (986)
* A Linux System backend was added, supporting `.deb` as a packaging format. (1062)
* Support for `.rpm` packaging was added to the Linux system backend. (1063)
* Support for passthrough arguments was added to the `dev` and `run` commands. (1077)
* Users can now define custom content to include in their `pyscript.toml` configuration file for web deployments. (1089)
* The `new` command now allows for specifying a custom template branch, as well as a custom template. (1101)

Bugfixes

* Spaces are no longer used in the paths for generated app templates. (804)
* The stub executable used by Windows now clears the threading mode before starting the Python app. This caused problems with displaying dialogs in Qt apps. (930)
* Briefcase now prevents running commands targeting Windows platforms when not on Windows. (1010)
* The command to store notarization credentials no longer causes Briefcase to hang. (1100)
* macOS developer tool installation prompts have been improved. (1122)

Misc

* 1070, 1074, 1075, 1076, 1080, 1084, 1085, 1086, 1087, 1094, 1096, 1097, 1098, 1103, 1109, 1110, 1111, 1119, 1120, 1130