Add briefcase config Command for User-Level and Global Configuration

.gitignore

@@ -37,3 +37,4 @@ coverage.xml
 
 tests/apps/verify-*/
 logs/
+.briefcase/

changes/2279.feature.rst

@@ -0,0 +1 @@
+Briefcase can now store per-project and per-user defaults for some options, such as author details, preferred simulators, and signing identities.

docs/reference/commands/config.rst

@@ -0,0 +1,93 @@
+======
+config
+======
+
+Manage user-level defaults without editing ``pyproject.toml``. Defaults can be
+stored per project (in ``.briefcase/``) or globally for your user account.
+
+Usage
+=====
+
+Set a value (project scope):
+
+.. code-block:: console
+
+    $ briefcase config android.device "@Pixel_5"
+    $ briefcase config iOS.device "iPhone 15"
+
+Set a value (global scope):
+
+.. code-block:: console
+
+    $ briefcase config --global android.device "emulator-5554"
+    $ briefcase config --global iOS.device "?"
+
+Get a value:
+
+.. code-block:: console
+
+    $ briefcase config --get android.device
+    $ briefcase config --global --get iOS.device
+
+List the current file:
+
+.. code-block:: console
+
+    $ briefcase config --list
+    $ briefcase config --global --list
+
+Unset a value:
+
+.. code-block:: console
+
+    $ briefcase config --unset android.device
+    $ briefcase config --global --unset iOS.device
+
+Where settings are stored
+-------------------------
+
+- Project user config: ``<project>/.briefcase/config.toml``
+- Global user config: platform user config directory, e.g.:
+
+  - macOS: ``~/Library/Application Support/org.beeware.briefcase/config.toml``
+  - Linux: ``~/.config/org.beeware.briefcase/config.toml``
+  - Windows: ``%LOCALAPPDATA%\\BeeWare\\org.beeware.briefcase\\config.toml``
+
+Format
+------
+
+On read, both a **root** TOML shape and a ``[tool.briefcase]`` block are accepted.
+On write, Briefcase uses the **root** shape.
+
+Example (project):
+
+.. code-block:: toml
+
+    [android]
+    device = "@Pixel_5"
+
+    [iOS]
+    device = "iPhone 15"
+
+Supported keys
+--------------
+
+- ``android.device`` — AVD name (``@Name``) or emulator id (e.g., ``emulator-5554``)
+- ``iOS.device`` — UDID (``xxxxxxxx-…-xxxxxxxxxxxx``), device name (e.g., ``"iPhone 15"``),
+  or ``"Device Name::iOS X[.Y]"``
+
+Validation & special values
+---------------------------
+
+- ``?`` is allowed for both device keys to **force** interactive selection next run.
+- Invalid formats are rejected with a helpful error; no file is written.
+
+Precedence
+----------
+
+**CLI overrides > ``pyproject.toml`` > project user config > global user config**
+
+Notes
+-----
+
+- Keys are case-sensitive (use ``iOS.device``, not ``ios.device``).

docs/reference/commands/index.rst

@@ -15,6 +15,7 @@ Command reference
    package
    publish
    upgrade
+   config
 
 Common options
 ==============

docs/spelling_wordlist

@@ -5,6 +5,7 @@ appimage
 artefact
 artefacts
 autodetect
+AVD
 backend
 backends
 backported
@@ -17,6 +18,7 @@ Chaquopy
 checkmarks
 cibuildwheel
 codebase
+config
 Cookiecutter
 cryptographic
 customizations
@@ -63,6 +65,7 @@ OSX
 passthrough
 Passthrough
 phablet
+PlatformDirs
 pre
 precompiled
 proxied
@@ -72,6 +75,7 @@ px
 pygame
 Pygame
 Pyodide
+pyproject.toml
 PyScript
 PySide
 pytest
@@ -102,6 +106,7 @@ triaged
 Triaging
 TTY
 tvOS
+UDID
 unallocated
 untrusted
 vendored

src/briefcase/cmdline.py

@@ -7,6 +7,7 @@
 from briefcase import __version__
 from briefcase.commands import (
     BuildCommand,
+    ConfigCommand,
     ConvertCommand,
     CreateCommand,
     DevCommand,
@@ -32,6 +33,7 @@
 COMMANDS = [
     NewCommand,
     DevCommand,
+    ConfigCommand,
     ConvertCommand,
     CreateCommand,
     OpenCommand,
@@ -133,6 +135,8 @@ def parse_known_args(args):
         Command = NewCommand
     elif options.command == "upgrade":
         Command = UpgradeCommand
+    elif options.command == "config":
+        Command = ConfigCommand
     else:
         # Commands dependent on the platform and format. The general form of such a
         # command is `briefcase <cmd> <platform> <format>`; but the format will be

src/briefcase/commands/__init__.py

@@ -1,4 +1,5 @@
 from .build import BuildCommand  # noqa: F401
+from .config import ConfigCommand  # noqa: F401
 from .convert import ConvertCommand  # noqa: F401
 from .create import CreateCommand  # noqa: F401
 from .dev import DevCommand  # noqa: F401

src/briefcase/commands/base.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import argparse
+import copy
 import importlib
 import importlib.metadata
 import inspect
@@ -28,7 +29,13 @@
 
 import briefcase
 from briefcase import __version__
-from briefcase.config import AppConfig, GlobalConfig, parse_config
+from briefcase.config import (
+    AppConfig,
+    GlobalConfig,
+    deep_merge,
+    load_user_config_files,
+    parse_config,
+)
 from briefcase.console import MAX_TEXT_WIDTH, Console
 from briefcase.exceptions import (
     BriefcaseCommandError,
@@ -1007,15 +1014,29 @@ def parse_config(self, filename, overrides):
                     console=self.console,
                 )
 
+                # Merge user-level config (global and per-project) before CLI overrides
+                project_root = Path(filename).resolve().parent
+                global_user_cfg, project_user_cfg = load_user_config_files(project_root)
+
+                # precedence within user-level config: global < project
+                user_merged = deep_merge(global_user_cfg, project_user_cfg)
+
+                # apply to global and each app (user config < pyproject)
+                merged_global = deep_merge(copy.deepcopy(user_merged), global_config)
+                merged_app_configs = {
+                    name: deep_merge(copy.deepcopy(user_merged), cfg)
+                    for name, cfg in app_configs.items()
+                }
+
                 # Create the global config
-                global_config.update(overrides)
+                merged_global.update(overrides)
                 self.global_config = create_config(
                     klass=GlobalConfig,
-                    config=global_config,
+                    config=merged_global,
                     msg="Global configuration",
                 )
 
-                for app_name, app_config in app_configs.items():
+                for app_name, app_config in merged_app_configs.items():
                     # Construct an AppConfig object with the final set of
                     # configuration options for the app.
                     app_config.update(overrides)