### Install Flatpak App Bundle

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/flatpak.md

Users can install a Flatpak app bundle directly from a .flatpak file. The `--user` flag installs it for the current user; omitting it installs system-wide.

```console
$ flatpak install --user App_Name-1.2.3-x86_64.flatpak
```

--------------------------------

### Example build.gradle with abiFilters

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/android/gradle.md

This is an example of how the defaultConfig block in build.gradle might look when android_abis is configured in pyproject.toml.

```groovy
...
    defaultConfig {
...
        ndk {
            abiFilters 'arm64-v8a', 'x86_64'
        }
...
```

--------------------------------

### Package Application (Default)

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/package.md

Use this command to build an installer for the default output format of the current platform.

```console
$ briefcase package
```

--------------------------------

### Install and Test Release from TestPyPI

Source: https://github.com/beeware/briefcase/blob/main/docs/en/how-to/internal/release.md

Create a virtual environment, install the new release from TestPyPI, and perform manual checks to ensure the release functions as expected.

```console
python3 -m venv testvenv
. ./testvenv/bin/activate
(testvenv) $ pip install --extra-index-url https://test.pypi.org/simple/ briefcase==1.2.3
(testvenv) $ briefcase --version
briefcase 1.2.3
(testvenv) $ #... any other manual checks you want to perform ...
```

--------------------------------

### Package Application for Specific Platform and Output Format

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/package.md

Build an installer for a specific platform and a particular output format.

```console
$ briefcase package <platform> <output format>
```

--------------------------------

### Example cleanup_paths Configuration

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/configuration.md

Define paths to be removed from the project after support package and app code installation. Paths can be files, directories, or globs, and can use format strings for dynamic references.

```python
cleanup_paths = [
    "path/to/unneeded_file.txt",
    "path/to/unneeded_directory",
    "path/**/*.exe",
    "{app.formal_name}/content/extra.doc"
]
```

--------------------------------

### Start a new Briefcase project

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/new.md

Run this command in your terminal to begin the new project creation wizard.

```console
$ briefcase new
```

--------------------------------

### Force All Packages Installation from Source

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/appimage.md

Use '--no-binary :all:' to instruct Briefcase to install all packages from source, preventing the use of any binary wheels.

```python
requires = [
    "pillow==9.1.0",
    "cryptography==37.0.2",
    "--no-binary", ":all:",
]
```

--------------------------------

### Example Application Metadata

Source: https://github.com/beeware/briefcase/blob/main/docs/en/topics/access-packaging-metadata.md

This is an example of the metadata dictionary that might be returned for an application packaged by Briefcase, derived from its pyproject.toml configuration.

```text
Metadata-Version: 2.1
Briefcase-Version: 0.3.1
Name: helloworld
Formal-Name: Hello World
App-ID: com.example.helloworld
Version: 0.0.1
Home-page: https://example.com/helloworld
Author: Jane Developer
Author-email: jane@example.com
Summary: My first application
```

--------------------------------

### Install Briefcase

Source: https://github.com/beeware/briefcase/blob/main/README.md

Install Briefcase using pip. This command installs the latest version of Briefcase.

```bash
python -m pip install briefcase
```

--------------------------------

### Example license_files Configuration

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/configuration.md

Specify license files to be included with the packaged app. This list must contain filenames relative to the pyproject.toml.

```toml
license_files = ["LICENSE"]
```

--------------------------------

### Briefcase v0.2 Invocation

Source: https://github.com/beeware/briefcase/blob/main/docs/en/how-to/upgrading/upgrade-from-v0.2.md

In Briefcase v0.2, the single entry point was `python setup.py <platform>` to generate output artifacts and optionally start the app.

```console
python setup.py <platform>
```

--------------------------------

### Package Application for Specific Platform

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/package.md

Build an installer for a different platform by specifying the platform name.

```console
$ briefcase package <platform>
```

--------------------------------

### Force Multiple Packages Installation from Source

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/appimage.md

To install multiple specific packages from source, add a separate '--no-binary' entry for each package.

```python
requires = [
    "pillow==9.1.0",
    "cryptography==37.0.2",
    "--no-binary", "pillow",
    "--no-binary", "cryptography",
]
```

--------------------------------

### Briefcase v0.3 Invocation Examples

Source: https://github.com/beeware/briefcase/blob/main/docs/en/how-to/upgrading/upgrade-from-v0.2.md

Briefcase v0.3 uses a `briefcase` entry point with subcommands for specific functions. Platform is auto-detected unless specified.

```console
briefcase new
```

```console
briefcase dev
```

```console
briefcase create
```

```console
briefcase update
```

```console
briefcase build
```

```console
briefcase run
```

```console
briefcase package
```

--------------------------------

### Specify Requirement Installer Arguments

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/configuration.md

Pass arguments to the requirement installer. Relative paths are automatically transformed to absolute paths if they exist. Arguments starting with '-' are not transformed.

```toml
requirement_installer_args = ["--find-links", "./wheels"]
```

```toml
requirement_installer_args = ["-f", "../wheels"]
```

```toml
requirement_installer_args = ["-f./wheels"]
```

```toml
requirement_installer_args = ["--find-links=./wheels"]
```

```toml
requirement_installer_args = ["-f", "wheels"]
```

```toml
requirement_installer_args = ["-f", "./this/path/does/not/exist"]
```

--------------------------------

### Run Flatpak App

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/flatpak.md

After installation, Flatpak applications can be launched using their bundle identifier. Ensure the identifier is correct for the installed app.

```console
$ flatpak run com.example.appname
```

--------------------------------

### Add Custom Dockerfile Instructions

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/system.md

Include additional Dockerfile instructions to configure the build container. This example demonstrates switching users to execute commands as root and then back to the default user.

```dockerfile
dockerfile_extra_content = """
RUN <first command run as brutus>

USER root
RUN <second command run as root>

USER brutus
"""
```

--------------------------------

### macOS Entitlements Example

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/macOS/index.md

Illustrates how a TOML configuration for an entitlement translates into an XML declaration within an Entitlements.plist file.

```xml
<key>com.apple.vm.networking</key><true/>
```

--------------------------------

### Example Android Manifest Permission with Attributes

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/android/gradle.md

This example shows how to declare permissions with additional attributes like maxSdkVersion and usesPermissionFlags. It includes declarations for BLUETOOTH_ADMIN and BLUETOOTH_SCAN.

```xml
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30"/>
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation"/>

```

--------------------------------

### Set up Briefcase Development Environment

Source: https://github.com/beeware/briefcase/blob/main/AGENTS.md

Installs the necessary development tools and dependencies for Briefcase. Ensure you are using Python 3.13 and have activated your virtual environment before running these commands.

```bash
python3.13 -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -e . --group dev
```

--------------------------------

### Example config.toml for PyScript Deployment

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/web/static.md

Defines the web implementation and PyScript version for a Briefcase deployment. Ensure this file is located in the `deploy` folder.

```toml
implementation = "pyscript"

[pyscript]
version = "2024.11.1"
```

--------------------------------

### Configure Flatpak Sandbox Permissions (Allow Bluetooth)

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/flatpak.md

Use `finish_arg` in `pyproject.toml` to specify arguments for configuring the Flatpak sandbox. This example allows Bluetooth access.

```python
finish_arg."allow=bluetooth" = true
```

--------------------------------

### Minimal pyproject.toml for External App

Source: https://github.com/beeware/briefcase/blob/main/docs/en/how-to/building/external-apps.md

This TOML configuration defines a minimal setup for an external app named 'Hello World' across macOS, Linux, and Windows platforms. It specifies the project name, bundle identifier, formal name, and the external package path for each OS.

```toml
[tool.briefcase]
project_name = "Hello World"
bundle = "com.example"

[tool.briefcase.app.helloworld]
formal_name = "Hello World"
version = "0.0.1"

[tool.briefcase.app.helloworld.macOS]
external_package_path = "..."

[tool.briefcase.app.helloworld.linux]
external_package_path = "..."

[tool.briefcase.app.helloworld.windows]
external_package_path = "..."
```

--------------------------------

### Using Setuptools-SCM for Dynamic Versioning in Briefcase

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/configuration.md

Configure your project to use setuptools_scm for dynamic versioning by defining build system requirements and declaring the 'version' field as dynamic. This example shows the necessary pyproject.toml structure.

```toml
[build-system]
# Set up a PEP 517 build configuration using setuptools
requires = ["setuptools", "setuptools_scm"]
build-backend = "setuptools.build_meta"

# Declare `version` to be dynamically defined
# The "name" field must also be defined as a PEP 621 key to satisfy setuptools
[project]
dynamic = ["version"]
name = "myproject"

# An empty table definition is required to enable setuptools-scm
[tool.setuptools_scm]

# Provide the rest of your project configuration as usual
[tool.briefcase]
...

```

--------------------------------

### Specify System Requirements for Compilation

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/appimage.md

When installing from source, include necessary system development libraries (e.g., libjpeg-dev, libpng-dev) in 'system_requires' for compilation.

```python
system_requires = [
    ... other system requirements ...
    "libjpeg-dev",
    "libpng-dev",
    "libtiff-dev",
]
```

--------------------------------

### Package External App on Windows

Source: https://github.com/beeware/briefcase/blob/main/docs/en/how-to/building/external-apps.md

Use this command to package an external app on Windows. It generates an installer (.msi) in the dist folder.

```doscon
(venv) C:\...>briefcase package

[helloworld] Packaging external content from Z:\projects\helloworld\output\windows-app

[helloworld] Generating application template...
...
[helloworld] Packaged dist\Hello_World-0.0.1.msi
```

--------------------------------

### Build Application with Debugger (pdb)

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/build.md

Installs the `pdb` debugger into the bundled app. If no debugger is specified, `pdb` is used by default. This is an experimental feature and may slow down the app.

```console
$ briefcase build --debug <debugger>
```

--------------------------------

### Specify System Runtime Requirements

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/system.md

Define a list of system packages required at runtime. This example shows version pinning for a GTK library and a WebKit library.

```python
system_runtime_requires = ["libgtk-3-0 (>=3.14)", "libwebkit2gtk-4.1-0"]
```

--------------------------------

### Example of passing a Docker build argument

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/system.md

Pass an additional build argument to the Dockerfile during the app image build process. Multiple arguments can be specified.

```bash
--Xdocker-build=--build-arg=ARG=value
```

--------------------------------

### Force Package Installation from Source

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/appimage.md

Use the '--no-binary' option in the 'requires' list to prevent Briefcase from using pre-compiled binary wheels for specific packages like Pillow.

```python
requires = [
    "pillow==9.1.0",
    "--no-binary", "pillow",
]
```

--------------------------------

### Example system_requires for RedHat-based systems

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/system.md

Specify operating system packages required for building on RedHat-derived distributions. These are used during the Docker build process if a Docker build is requested.

```python
system_requires = ["gobject-introspection-devel", "python3-cairo-devel"]
```

--------------------------------

### Specifying Output Format for Briefcase v0.3 on macOS

Source: https://github.com/beeware/briefcase/blob/main/docs/en/how-to/upgrading/upgrade-from-v0.2.md

To use a different output format on macOS, add the format as an extra argument after the platform. This example shows creating an 'app' file.

```console
$ briefcase create macOS app
$ briefcase build macOS app
$ briefcase run macOS app
$ briefcase package macOS app
```

--------------------------------

### Building Documentation

Source: https://github.com/beeware/briefcase/blob/main/AGENTS.md

Build the project's documentation, including all necessary components, using the 'docs-all' tox environment.

```bash
tox -e docs-all
```

--------------------------------

### Run application with custom debugger host and port

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/run.md

Start the application in debug mode, specifying a custom host and port for the debugger's socket connection. This is useful for remote debugging setups.

```console
$ briefcase run --debug <debugger> --debugger-host <host> --debugger-port <port>
```

--------------------------------

### Executing Installed Console App

Source: https://github.com/beeware/briefcase/blob/main/docs/en/how-to/building/cli-apps.md

Once installed, console applications can be executed directly from the terminal using their app name.

```console
$ hello-cli John
Hello, John!

```

--------------------------------

### Example Android Manifest Permission Declaration

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/android/gradle.md

This example demonstrates how to declare a required permission in the AndroidManifest.xml. It requests the HIGH_SAMPLING_RATE_SENSORS permission.

```xml
<uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS">

```

--------------------------------

### Build Application for Specific Platform and Output Format

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/build.md

Build the application for a given platform and a specific output format.

```console
$ briefcase build <platform> <output format>
```

--------------------------------

### Example Android Manifest Feature Declaration

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/android/gradle.md

This example shows how to declare a required hardware feature in the AndroidManifest.xml. It specifies that the device must have Bluetooth hardware.

```xml
<uses-feature android:name="android.hardware.bluetooth" android:required="true">

```

--------------------------------

### Pass Arguments to Emulator Startup

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/android/gradle.md

Use the --Xemulator argument to pass configuration options to the emulator on startup, such as disabling the display window.

```console
--Xemulator=-no-window
```

--------------------------------

### Version Code Generation Examples

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/android/gradle.md

These examples illustrate how Briefcase generates the Android version code based on the app's version number and build number. The format ensures the version code increases with each release.

```text
Version 1.0, build 1 becomes 1000001 (i.e, 1, 00, 00, 01)
Version 1.2, build 37 becomes 1020037 (i.e., 1, 02, 00, 37)
Version 1.2.37, build 42 becomes 1023742 (i.e., 1, 02, 37, 42)
Version 2020.6, build 4 becomes 2020060004 (i.e., 2020, 06, 00, 04)

```

--------------------------------

### Build Application for Default Platform

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/build.md

Use this command to build the application for the default output format of the current operating system.

```console
$ briefcase build
```

--------------------------------

### Create scaffold for default platform

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/create.md

Use this command to create a scaffold for the default output format of the current platform.

```console
$ briefcase create
```

--------------------------------

### Pip Build Dependency Error Example

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/appimage.md

This error occurs if system requirements for compiling a package from source are missing.

```console
error: subprocess-exited-with-error

× pip subprocess to install build dependencies did not run successfully.
│ exit code: 1
╰─> See above for output.

note: This error originates from a subprocess, and is likely not a problem with pip.
>>> Return code: 1

Unable to install requirements. This may be because one of your
requirements is invalid, or because pip was unable to connect
to the PyPI server.
```

--------------------------------

### Build and Lint Documentation

Source: https://github.com/beeware/briefcase/blob/main/docs/en/how-to/internal/release.md

Build the documentation using tox to verify that the new release notes do not contain any spelling or markup errors.

```console
tox -e docs-lint,docs-all
```

--------------------------------

### Creating a New Console App

Source: https://github.com/beeware/briefcase/blob/main/docs/en/how-to/building/cli-apps.md

Use the `briefcase new` command and select 'Console' as the GUI framework to initiate a new console application project.

```console
$ briefcase new
...
-- GUI Framework -------------------------------------------------------------

What GUI toolkit do you want to use for this project?

Additional GUI bootstraps are available from the community.

Check them out at https://beeware.org/bee/briefcase-bootstraps

1) Toga
2) PySide6 (does not support iOS/Android/Web deployment)
3) Pygame  (does not support iOS/Android/Web deployment)
4) Console (does not support iOS/Android/Web deployment)
5) None

GUI Framework [1]: 4

```

--------------------------------

### Gradle Dependencies Example

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/android/gradle.md

This snippet lists the default libraries linked into the Android application. These are common AndroidX libraries for UI and layout.

```gradle
androidx.appcompat:appcompat:1.0.2
androidx.constraintlayout:constraintlayout:1.1.3
androidx.swiperefreshlayout:swiperefreshlayout:1.1.0

```

--------------------------------

### Update resources, build, and run application

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/run.md

This command sequence updates the application's resources (like icons), rebuilds it, and then runs the application. Use this when you've modified project assets.

```console
$ briefcase update --update-resources
$ briefcase build
$ briefcase run
```

--------------------------------

### Create scaffold for a specific platform and output format

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/create.md

Use this command to create a scaffold for a specific platform and a particular output format.

```console
$ briefcase create <platform> <output format>
```

--------------------------------

### AppImage Runtime Error Example

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/appimage.md

This traceback indicates a library corruption within an AppImage, often caused by double processing of binary wheels.

```console
Traceback (most recent call last):
File "/tmp/.mount_TestbewwDi98/usr/app/testbed/app.py", line 54, in main
  test()
File "/tmp/.mount_TestbewwDi98/usr/app/testbed/linux.py", line 94, in test_pillow
   from PIL import Image
File "/usr/app_packages/PIL/Image.py", line 132, in <module>
   from . import _imaging as core
ImportError: libtiff-d0580107.so.5.7.0: ELF load command address/offset not properly aligned
```

--------------------------------

### Run application with PDB debugger

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/run.md

Start the application in debug mode using the Python Debugger (pdb). This is the default debugger if none is specified.

```console
$ briefcase run --debug
```

--------------------------------

### Run Briefcase Convert Command

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/convert.md

Execute the `briefcase convert` command in the root directory of your application where `pyproject.toml` is located to start the conversion process.

```console
$ briefcase convert
```

--------------------------------

### Run App with PDB Debugging Enabled

Source: https://github.com/beeware/briefcase/blob/main/docs/en/how-to/debugging/pdb.md

Execute this command to run your application in debug mode, which will start the remote-pdb debugger and wait for connections.

```console
$ briefcase run --debug pdb
```

--------------------------------

### Platform-Specific --no-binary Declaration

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/linux/appimage.md

Place '--no-binary' declarations in platform-specific 'requires' lists to control which platforms are affected. This example applies it only to Linux.

```toml
[tool.briefcase.app.helloworld]
formal_name = "Hello World"
...
requires = [
    "pillow",
]

[tool.briefcase.app.helloworld.linux]
requires = [
    "--no-binary", "pillow"
]
```

--------------------------------

### Run application with specific output format

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/run.md

Execute your application, targeting a specific platform and output format. Replace `<platform>` and `<output format>` with the desired values.

```console
$ briefcase run <platform> <output format>
```

--------------------------------

### Define a Toga GUI Bootstrap Plugin

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/plugins.md

Configure a custom GUI bootstrap plugin by adding an entry point to your `pyproject.toml`. The name is the user-facing label in the wizard, and the value points to the implementing class.

```toml
[project.entry-points."briefcase.bootstraps"]
Toga = "briefcase.bootstraps.toga:TogaGuiBootstrap"
```

--------------------------------

### Add UIFileSharingEnabled to Info.plist

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/iOS/xcode.md

Example of how to add a boolean value to an app's Info.plist file by configuring the `tool.briefcase.app.<appname>.iOS.app.info` section in pyproject.toml.

```toml
info."UIFileSharingEnabled" = true
```

--------------------------------

### Update support package, build, and run application

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/run.md

This command sequence updates the application's support package, rebuilds it, and then runs the application. This is useful when the underlying support code needs updating.

```console
$ briefcase update --update-support
$ briefcase build
$ briefcase run
```

--------------------------------

### Run application on current platform

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/commands/run.md

Execute your application using the default output format for the current platform.

```console
$ briefcase run
```

--------------------------------

### Run Bundled App in Debug Mode

Source: https://github.com/beeware/briefcase/blob/main/docs/en/how-to/debugging/vscode.md

Execute this command to run your bundled application in debug mode. The application will start and wait for the debugger to attach.

```console
briefcase run --debug debugpy
```

```console
briefcase run iOS --debug debugpy
```

--------------------------------

### Require GPS Hardware in pyproject.toml

Source: https://github.com/beeware/briefcase/blob/main/docs/en/reference/platforms/android/gradle.md

Manually define hardware feature requirements to ensure they are explicitly required by the application. This example makes GPS hardware a requirement.

```toml
feature."android.hardware.location.gps" = True
```