From 9275866e39ebe63018b92c4c97f7869bbf6c68b4 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Mon, 15 Dec 2025 14:45:35 +0800 Subject: [PATCH 1/3] Modify tutorial to reflect isolated development mode. --- docs/en/tutorial/tutorial-0.md | 10 ++- docs/en/tutorial/tutorial-1.md | 18 +++++ docs/en/tutorial/tutorial-7.md | 143 +++++++++++++++++++++------------ 3 files changed, 116 insertions(+), 55 deletions(-) diff --git a/docs/en/tutorial/tutorial-0.md b/docs/en/tutorial/tutorial-0.md index cf99a8e..efe3587 100644 --- a/docs/en/tutorial/tutorial-0.md +++ b/docs/en/tutorial/tutorial-0.md @@ -32,7 +32,7 @@ You should ensure that the system Python is Python 3.10 or newer; if it isn't (e Support for Raspberry Pi is limited at this time. -**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. +**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. /// @@ -69,7 +69,7 @@ $ sudo apt update $ sudo apt install git build-essential pkg-config python3-dev python3-venv libgirepository1.0-dev libcairo2-dev gir1.2-gtk-3.0 libcanberra-gtk3-module ``` -### Fedora +### Red Hat / Fedora ```console $ sudo dnf install git gcc make pkg-config rpm-build python3-devel gobject-introspection-devel cairo-gobject-devel gtk3 libcanberra-gtk3 @@ -87,6 +87,12 @@ $ sudo pacman -Syu git base-devel pkgconf python3 gobject-introspection cairo gt $ sudo zypper install git patterns-devel-base-devel_basis pkgconf-pkg-config python3-devel gobject-introspection-devel cairo-devel gtk3 'typelib(Gtk)=3.0' libcanberra-gtk3-module ``` +/// admonition | Other Linux distributions + +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. + +/// + /// /// tab | Windows diff --git a/docs/en/tutorial/tutorial-1.md b/docs/en/tutorial/tutorial-1.md index 739e32d..16c8a7f 100644 --- a/docs/en/tutorial/tutorial-1.md +++ b/docs/en/tutorial/tutorial-1.md @@ -121,6 +121,10 @@ Move into the `helloworld` project directory and tell briefcase to start the pro (beeware-venv) $ cd helloworld (beeware-venv) $ briefcase dev +[helloworld] Activating dev environment... +... +Creating virtual environment (dev.cpython-313-darwin)... done + [hello-world] Installing requirements... ... @@ -136,6 +140,10 @@ Move into the `helloworld` project directory and tell briefcase to start the pro (beeware-venv) $ cd helloworld (beeware-venv) $ briefcase dev +[helloworld] Activating dev environment... +... +Creating virtual environment (dev.cpython-313-x86_64-linux-gnu)... done + [hello-world] Installing requirements... ... @@ -151,6 +159,10 @@ Move into the `helloworld` project directory and tell briefcase to start the pro (beeware-venv) C:\...>cd helloworld (beeware-venv) C:\...>briefcase dev +[helloworld] Activating dev environment... +... +Creating virtual environment (dev.cp313-win32_amd64)... done + [hello-world] Installing requirements... ... @@ -180,6 +192,12 @@ This should open a GUI window: /// +/// admonition | Possible errors when running `briefcase dev` + +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. + +/// + /// /// tab | Windows diff --git a/docs/en/tutorial/tutorial-7.md b/docs/en/tutorial/tutorial-7.md index 9dcf564..c3e7941 100644 --- a/docs/en/tutorial/tutorial-7.md +++ b/docs/en/tutorial/tutorial-7.md @@ -109,13 +109,65 @@ You can't run an iOS app in developer mode - use the instructions for your chose /// -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`: +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. + +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. + +So how do you add a new requirement to your application? + +## Updating dependencies + +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`. + +`pyproject.toml` is broken up into sections; one of the sections describes the settings for your app: + +```toml +[tool.briefcase.app.helloworld] +formal_name = "Hello World" +description = "A Tutorial app" +long_description = """More details about the app should go here. +""" +sources = ["src/helloworld"] +requires = [] +``` + +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. + +Modify the `requires` setting so that it reads: + +```toml +requires = [ + "faker", +] +``` + +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: + +- A specific library version (e.g., `"faker==37.3.0"`); +- A range of library versions (e.g., `"faker>=37"`); +- A path to a git repository (e.g., `"git+https://github.com/joke2k/faker/"`); or +- A local file path (However - be warned: if you give your code to someone else, this path probably won't exist on their machine!) + +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. + +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. + +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: /// tab | macOS ```console -(beeware-venv) $ python -m pip install faker -(beeware-venv) $ briefcase dev +(beeware-venv) $ briefcase dev -r + +[helloworld] Activating dev environment... +... +Recreating virtual environment (dev.cpython-313-darwin)... done + +[hello-world] Installing requirements... +... + +[helloworld] Starting in dev mode... +=========================================================================== ``` When you enter a name and press the button, you should see a dialog that looks something like: @@ -131,8 +183,17 @@ When you enter a name and press the button, you should see a dialog that looks s /// tab | Linux ```console -(beeware-venv) $ python -m pip install faker -(beeware-venv) $ briefcase dev +(beeware-venv) $ briefcase dev -r + +[helloworld] Activating dev environment... +... +Recreating virtual environment (dev.cpython-313-x86_64-linux-gnu)... done + +[hello-world] Installing requirements... +... + +[helloworld] Starting in dev mode... +=========================================================================== ``` When you enter a name and press the button, you should see a dialog that looks something like: @@ -148,8 +209,17 @@ When you enter a name and press the button, you should see a dialog that looks s /// tab | Windows ```doscon -(beeware-venv) C:\...>python -m pip install faker -(beeware-venv) C:\...>briefcase dev +(beeware-venv) C:\...>briefcase dev -r + +[helloworld] Activating dev environment... +... +Recreating virtual environment (dev.cp313-win32_amd64)... done + +[hello-world] Installing requirements... +... + +[helloworld] Starting in dev mode... +=========================================================================== ``` 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 /// -We've now got a working app, using a third party library, running in development mode! +/// admonition | Possible errors when running `briefcase dev` + +If you're still getting an error running briefcase dev, make sure: + +1. You've added `faker` to the `requires` list in `pyproject.toml`; +2. You've saved your changes to `pyproject.toml`; and +3. You included the `-r` argument when running `briefcase dev -r`. + +/// + +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. ## Running the updated app -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): +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): /// tab | macOS @@ -442,50 +522,7 @@ ModuleNotFoundError: No module named 'faker' Once again, the app has failed to start because `faker` has not been installed - but why? Haven't we already installed `faker`? -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. - -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. - -So - we need to tell Briefcase that our app has an external dependency. - -## Updating dependencies - -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`. - -`pyproject.toml` is broken up into sections; one of the sections describes the settings for your app: - -```toml -[tool.briefcase.app.helloworld] -formal_name = "Hello World" -description = "A Tutorial app" -long_description = """More details about the app should go here. -""" -sources = ["src/helloworld"] -requires = [] -``` - -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. - -Modify the `requires` setting so that it reads: - -```toml -requires = [ - "faker", -] -``` - -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: - -- A specific library version (e.g., `"faker==37.3.0"`); -- A range of library versions (e.g., `"faker>=37"`); -- A path to a git repository (e.g., `"git+https://github.com/joke2k/faker/"`); or -- A local file path (However - be warned: if you give your code to someone else, this path probably won't exist on their machine!) - -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. - -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. - -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: +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: /// tab | macOS From a85351d82b9d241da76645702c3687ed66ec1888 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Tue, 16 Dec 2025 06:18:10 +0800 Subject: [PATCH 2/3] Correct spelling issues. --- docs/en/tutorial/tutorial-7.md | 4 ++-- docs/spelling_wordlist | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/en/tutorial/tutorial-7.md b/docs/en/tutorial/tutorial-7.md index c3e7941..c8d7fdf 100644 --- a/docs/en/tutorial/tutorial-7.md +++ b/docs/en/tutorial/tutorial-7.md @@ -152,7 +152,7 @@ Further down in `pyproject.toml`, you'll notice other sections that are operatin 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. -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: +Once you've 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: /// tab | macOS @@ -246,7 +246,7 @@ You can't run an iOS app in developer mode - use the instructions for your chose /// admonition | Possible errors when running `briefcase dev` -If you're still getting an error running briefcase dev, make sure: +If you're still getting an error running `briefcase dev`, make sure: 1. You've added `faker` to the `requires` list in `pyproject.toml`; 2. You've saved your changes to `pyproject.toml`; and diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index 47fd52c..4c490d9 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -1,4 +1,5 @@ adhoc +AlmaLinux API APIs APK @@ -79,6 +80,7 @@ TextInput unclicked UDID UI +uv verbing Weblate Xcode From a2c1196c276e04cb55ff19aac935610977c0fd60 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Tue, 16 Dec 2025 06:27:51 +0800 Subject: [PATCH 3/3] Apply suggestions from review. --- docs/en/tutorial/tutorial-7.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en/tutorial/tutorial-7.md b/docs/en/tutorial/tutorial-7.md index c8d7fdf..78d8cb7 100644 --- a/docs/en/tutorial/tutorial-7.md +++ b/docs/en/tutorial/tutorial-7.md @@ -111,7 +111,7 @@ You can't run an iOS app in developer mode - use the instructions for your chose 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. -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. +When Briefcase runs an app in development mode, it creates a standalone virtual environment for that application, independent of the environment in which you run `briefcase`. If your app doesn't declare that it needs a particular library, that library won't be installed in the development virtual environment. So how do you add a new requirement to your application? @@ -131,7 +131,7 @@ sources = ["src/helloworld"] requires = [] ``` -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. +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. Modify the `requires` setting so that it reads: @@ -522,7 +522,7 @@ ModuleNotFoundError: No module named 'faker' Once again, the app has failed to start because `faker` has not been installed - but why? Haven't we already installed `faker`? -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: +We have - but only in the development environment. Each built application also has its own standalone environment, which is one of the things Briefcase produces when you run `briefcase build`. 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: /// tab | macOS