beeware / beeware/briefcase

Add ability for user-level configuration options

Open
#2,279 3 comments 1 reaction 0 assignees View on GitHub
enhancement good first issue
Dominant language
Python
Stars
3.3k
Forks
549
Avg merge
1d 4h
Merged PRs (30d)
40

Description

### What is the problem or limitation you are having?

At present, the only mode of Briefcase configuration is "project level" - if a setting isn't in the `pyproject.toml`, it must be specified manually at the command line of any given Briefcase command.

However, there are some values that will be consistent on a per-user basis for a project, or across *all* projects. There should be a way to configure project per-user and global per-user options for Briefcase.

For example, settings that you may want to define as defaults, but not persist in a `pyproject.toml` may include
* Your preferred iOS/Android simulator
* The credential identifiers to use when signing a project
* Cache or proxy configurations

### Describe the solution you'd like

A `briefcase config` command that allows a setting to be defined:
* `briefcase config iOS.device "iPhone 16e"`
* `briefcase config macOS.identity "...."`

These configuration items would be saved in a `.briefcase/config.toml` file in the project directory; `.briefcase` should be added to the `.gitignore` for a new repository.

`briefcase config --global` option that would save the same options on a *global* basis. Global configuration items would be saved in a `config.toml` stored in a platform-appropriate configuration location (i.e., `PlatformDirs("org.beeware.briefcase", "BeeWare").user_config_dir / "config.toml"`).

Global configuration options should take priority over user-level project options, and project level options should take priority over user-level project options. (i.e., if you configure an "iPhone 14" global option, "iPhone 15" as a user-level project option, "iPhone 15" would take priority; if you specify "iPhone 16" at the command line, "iPhone 16" would take priority).

The configuration structure for configuration options should match pyproject.toml - so there should be possible to configure options at a `global`, `macOS`, and `macOS.Xcode` level, with the same prioritization as they have in `pyproject.toml`.

Any option that has a command line option and can be set as a default should also allow for a `?` value - so, even if I configure a default simulator of `iPhone 15`, if I run `briefcase run iOS --device ?`, the command should override the configured option and ask.

### Describe alternatives you've considered

Do nothing, and continue to require all options to be explicit.

### Additional context

As a first pass, I'd suggest the only options that should be exposed are:

* Author name (used in the `new` wizard)
* Email (used in the `new` wizard)
* simulator choices
* signing identities

Contributor guide

Open the contributing guide

Research direction

Start by tracing Briefcase's existing pyproject.toml configuration handling and the command entry point for a proposed `briefcase config` command. Use the stated `.briefcase/config.toml` and PlatformDirs-based global `config.toml` locations as the configuration targets; done means implementing the precedence rules, supported defaults, `?` overrides, and repository ignore behavior described in the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.