Document how to install and run Briefcase

[freakboy3742]

What kind of documentation issue is this?

Missing documentation

Affected page

No response

Describe the issue

Briefcase doesn't currently have any documentation on how to actually install and run Briefcase. The README has a very cursory "pip install" note, and then defers to the tutorial.

This means there's no standalone documentation describing how to install and invoke Briefcase as a user.

Suggested improvement

We should add a new How-to guide: "How to run Briefcase", which should be the first guide in How To index.

It should cover:

1. Default installs (create a virtual environment, python -m pip install briefcase, then run briefcase <command>. It should link off to the Command reference to describe the things that can be run, and the tutorial for a more general guide to the usage of Briefcase.
2. Using uvx (install uvx, then run uvx briefcase <command>)
3. Using pipx (install pipx, then run uvx briefcase <command>)

The FAQ should also include entries for:

• "how do I use Briefcase?" that links to the HOWTO
• "Can I use uvx/pipx to run briefcase?" that links to the relevant sections

[astrojuanlu]

uv run is difficult to make work, because a pyproject.toml file contains the code and requirements for a specific app, which won't include briefcase.

Originally posted by @freakboy3742 in #2314

For the record, I've been successful with

$ uv add --dev briefcase
$ uv run briefcase convert
...
$ uv run briefcase package

[freakboy3742]

For the record, I've been successful with

$ uv add --dev briefcase
$ uv run briefcase convert
...
$ uv run briefcase package

Using a dev dependency group may be helpful once you've got a working app, but it doesn't help with bootstrapping. convert requires a full pre-existing project. If you run:

$ uv init
$ uv add --dev briefcase
$ uv run briefcase new

You're going to end up with two pyproject.toml files: one that has a uv configuration, and one in a subdirectory that has the Briefcase configuration.

It may be possible to resolve this (for example, offering to modify the existing pyproject.toml if it appears to be "minimal", for some definition of minimal); but for now, I don't think it's reasonable to recommend bare uv.