Document how to debug a Briefcase app with popular IDEs
- 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
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