You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/en/tutorial/tutorial-0.md
+8-2Lines changed: 8 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,7 +32,7 @@ You should ensure that the system Python is Python 3.10 or newer; if it isn't (e
32
32
33
33
Support for Raspberry Pi is limited at this time.
34
34
35
-
**Important:** You *must* use the system Python provided by your operating system. Alternative Python installations (pyenv, Anaconda, manually compiled Python, etc.) will prevent you from successfully packaging your application for distribution in later steps of this tutorial.
35
+
**Important:** You *must* use the system Python provided by your operating system. Python installs from other sources (such as uv, pyenv, Anaconda, manually compiled Python, etc.) will prevent you from successfully packaging your application for distribution in later steps of this tutorial.
If you're on a Linux distribution that isn't on this list, and isn't derived from one on this list (e.g., Linux Mint and Pop! OS are both Debian-derived distributions; AlmaLinux is Fedora-derived), you will probably have difficulty completing this tutorial. If Briefcase warns you that it "Can't verify system packages", you won't be able to complete this tutorial.
@@ -180,6 +192,12 @@ This should open a GUI window:
180
192
181
193
///
182
194
195
+
/// admonition | Possible errors when running `briefcase dev`
196
+
197
+
If you get an error when you run `briefcase dev`, it's almost certainly because some of the system requirements haven't been installed. Make sure you have [installed all the platform pre-requisites][install-dependencies]; the error message you receive should tell you which packages are missing.
Copy file name to clipboardExpand all lines: docs/en/tutorial/tutorial-7.md
+90-53Lines changed: 90 additions & 53 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -109,13 +109,65 @@ You can't run an iOS app in developer mode - use the instructions for your chose
109
109
110
110
///
111
111
112
-
What happened? We've added `faker` to our *code*, but we haven't added it to our development virtual environment. We can fix this by installing `faker` with `pip`, and then re-running `briefcase dev`:
112
+
What happened? We've added `faker` to our *code*, but we haven't added it to the virtual environment that is used to run the app in development mode.
113
+
114
+
The only way to guarantee that someone else will have a Python environment that contains everything it needs is to build a completely isolated Python environment. To ensure this happens, when Briefcase runs an app in development mode, it creates a standalone virtual environment for that application. If your app doesn't declare that it needs a particular library, that library won't be installed in the development virtual environment.
115
+
116
+
So how do you add a new requirement to your application?
117
+
118
+
## Updating dependencies
119
+
120
+
In the root directory of your app, there is a file named `pyproject.toml`. This file contains all the app configuration details that you provided when you originally ran `briefcase new`.
121
+
122
+
`pyproject.toml` is broken up into sections; one of the sections describes the settings for your app:
123
+
124
+
```toml
125
+
[tool.briefcase.app.helloworld]
126
+
formal_name = "Hello World"
127
+
description = "A Tutorial app"
128
+
long_description = """More details about the app should go here.
129
+
"""
130
+
sources = ["src/helloworld"]
131
+
requires = []
132
+
```
133
+
134
+
The `requires` option describes the dependencies of our application. It is a list of strings, specifying libraries (and, optionally, versions) of libraries that you want to be included with your app.
135
+
136
+
Modify the `requires` setting so that it reads:
137
+
138
+
```toml
139
+
requires = [
140
+
"faker",
141
+
]
142
+
```
143
+
144
+
By adding this setting, we're telling Briefcase "when you build my app, run `pip install faker` into the application bundle". Anything that would be legal input to `pip install` can be used here - so, you could specify:
145
+
146
+
- A specific library version (e.g., `"faker==37.3.0"`);
147
+
- A range of library versions (e.g., `"faker>=37"`);
148
+
- A path to a git repository (e.g., `"git+https://github.com/joke2k/faker/"`); or
149
+
- A local file path (However - be warned: if you give your code to someone else, this path probably won't exist on their machine!)
150
+
151
+
Further down in `pyproject.toml`, you'll notice other sections that are operating system dependent, like `[tool.briefcase.app.helloworld.macOS]` and `[tool.briefcase.app.helloworld.windows]`. These sections *also* have a `requires` setting. These settings allow you to define additional platform-specific dependencies - so, for example, if you need a platform-specific library to handle some aspect of your app, you can specify that library in the platform-specific `requires` section, and that setting will only be used for that platform. You will notice that the `toga` libraries are all specified in the platform-specific `requires` section - this is because the libraries needed to display a user interface are platform specific.
152
+
153
+
In our case, we want `faker` to be installed on all platforms, so we use the app-level `requires` setting. The app-level dependencies will always be installed; the platform-specific dependencies are installed *in addition* to the app-level ones.
154
+
155
+
Once you'e added the new requirement, save `pyproject.toml`, and run `briefcase dev -r`. The `-r` flag tells Briefcase that requirements have changed, and the development virtual environment needs to be updated:
When you enter a name and press the button, you should see a dialog that looks something like:
@@ -174,11 +244,21 @@ You can't run an iOS app in developer mode - use the instructions for your chose
174
244
175
245
///
176
246
177
-
We've now got a working app, using a third party library, running in development mode!
247
+
/// admonition | Possible errors when running `briefcase dev`
248
+
249
+
If you're still getting an error running briefcase dev, make sure:
250
+
251
+
1. You've added `faker` to the `requires` list in `pyproject.toml`;
252
+
2. You've saved your changes to `pyproject.toml`; and
253
+
3. You included the `-r` argument when running `briefcase dev -r`.
254
+
255
+
///
256
+
257
+
The very first time you run your app using `briefcase dev`, the `-r` argument is automatically added for you - that's why we haven't had to use the `-r` argument until now. The `-r` argument is only needed when you add, remove, or change a requirement, *after* running your application in development mode. If you've only updated code, you can run `briefcase dev` as we have been doing for the rest of this tutorial.
178
258
179
259
## Running the updated app
180
260
181
-
Let's get this updated application code packaged as a standalone app. Since we've made code changes, we need to follow the same steps as in [Tutorial 4](tutorial-4.md):
261
+
We've now got a working app, using a third party library, running in development mode. Let's get this updated application code packaged as a standalone app. Since we've made code changes, we need to follow the same steps as in [Tutorial 4](tutorial-4.md):
182
262
183
263
/// tab | macOS
184
264
@@ -442,50 +522,7 @@ ModuleNotFoundError: No module named 'faker'
442
522
443
523
Once again, the app has failed to start because `faker` has not been installed - but why? Haven't we already installed `faker`?
444
524
445
-
We have - but only in the development environment. Your development environment is entirely local to your machine - and is only enabled when you explicitly activate it. Although Briefcase has a development mode, the main reason you'd use Briefcase is to package up your code so you can give it to someone else.
446
-
447
-
The only way to guarantee that someone else will have a Python environment that contains everything it needs is to build a completely isolated Python environment. This means there's a completely isolated Python install, and a completely isolated set of dependencies. This is what Briefcase is building when you run `briefcase build` - an isolated Python environment. This also explains why `faker` isn't installed - it has been installed in your *development* environment, but not in the packaged app.
448
-
449
-
So - we need to tell Briefcase that our app has an external dependency.
450
-
451
-
## Updating dependencies
452
-
453
-
In the root directory of your app, there is a file named `pyproject.toml`. This file contains all the app configuration details that you provided when you originally ran `briefcase new`.
454
-
455
-
`pyproject.toml` is broken up into sections; one of the sections describes the settings for your app:
456
-
457
-
```toml
458
-
[tool.briefcase.app.helloworld]
459
-
formal_name = "Hello World"
460
-
description = "A Tutorial app"
461
-
long_description = """More details about the app should go here.
462
-
"""
463
-
sources = ["src/helloworld"]
464
-
requires = []
465
-
```
466
-
467
-
The `requires` option describes the dependencies of our application. It is a list of strings, specifying libraries (and, optionally, versions) of libraries that you want to be included with your app.
468
-
469
-
Modify the `requires` setting so that it reads:
470
-
471
-
```toml
472
-
requires = [
473
-
"faker",
474
-
]
475
-
```
476
-
477
-
By adding this setting, we're telling Briefcase "when you build my app, run `pip install faker` into the application bundle". Anything that would be legal input to `pip install` can be used here - so, you could specify:
478
-
479
-
- A specific library version (e.g., `"faker==37.3.0"`);
480
-
- A range of library versions (e.g., `"faker>=37"`);
481
-
- A path to a git repository (e.g., `"git+https://github.com/joke2k/faker/"`); or
482
-
- A local file path (However - be warned: if you give your code to someone else, this path probably won't exist on their machine!)
483
-
484
-
Further down in `pyproject.toml`, you'll notice other sections that are operating system dependent, like `[tool.briefcase.app.helloworld.macOS]` and `[tool.briefcase.app.helloworld.windows]`. These sections *also* have a `requires` setting. These settings allow you to define additional platform-specific dependencies - so, for example, if you need a platform-specific library to handle some aspect of your app, you can specify that library in the platform-specific `requires` section, and that setting will only be used for that platform. You will notice that the `toga` libraries are all specified in the platform-specific `requires` section - this is because the libraries needed to display a user interface are platform specific.
485
-
486
-
In our case, we want `faker` to be installed on all platforms, so we use the app-level `requires` setting. The app-level dependencies will always be installed; the platform-specific dependencies are installed *in addition* to the app-level ones.
487
-
488
-
Now that we've told Briefcase about our additional requirements, we can try packaging our app again. Ensure that you've saved your changes to `pyproject.toml`, and then update your app again - this time, passing in the `-r` flag. This tells Briefcase to update requirements in the packaged app:
525
+
We have - but only in the development environment. Each built application is *also* a standalone environment. This is what Briefcase is building when you run `briefcase build` - an isolated Python environment. When we ran `briefcase dev -r`, we added `faker` to our *development* environment, but not to the packaged app. We also need to run `briefcase update -r` so that Briefcase knows the requirements of the packaged app have changed:
0 commit comments