beeware / beeware/briefcase

Document how to debug a Briefcase app with popular IDEs

Open
#1,393 8 comments 5 reactions 0 assignees View on GitHub
documentation enhancement
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?

`briefcase dev` is the documented way to run a Briefcase app; however, the only way to debug an app with `briefcase dev` is to set a `breakpoint()` and use pdb. This is less than ideal, as modern IDEs provide built-in debuggers and test runners.

### Describe the solution you'd like

Add documentation how to configure VSCode, PyCharm, and other common IDEs so that their native "run" and "test" mechanisms reproduce what `briefcase dev` does.

The tl;dr is that you need to:
1. Add every directory mentioned in `sources` to the PYTHONPATH
2. Set the working directory to the user's home directory
3. Remove the project directory (the directory that contains pyproject.toml` from the PYTHONPATH (it's usually the first entry in `sys.path`)
4. Run the app name as a module (i.e., the equivalent of `python -m myapp`)

To run in test mode, you also need to add all the directories mentioned in `test_sources`, plus change the runtime module to `tests.myapp`.

Specifics can be found by reverse engineering `src/briefcase/commands/dev.py`.

We should document the specific instructions for configuring common IDEs (at present, I'd say that means VSCode and PyCharm); but we should also document the generic requirements so that any other IDE user knows what is needed.

### Describe alternatives you've considered

Continue to encourage `briefcase dev` and `breakpoint()`.

### Additional context

Documenting manual configuration is a stop-gap measure. Longer term, it would be desirable to capture these instructions as a Briefcase plugin for VSCode and PyCharm.

Contributor guide

Open the contributing guide

Research direction

Start by reverse engineering src/briefcase/commands/dev.py to verify how briefcase dev sets PYTHONPATH, the working directory, and the runtime module. Document the generic requirements plus native run and test configurations for VSCode and PyCharm. Done means a user can reproduce briefcase dev and test mode through those IDEs using the documented steps.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, vscode
Domain
developer-experience, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.