From f10f8399a7516852d935b2cd3b371540809ba2c3 Mon Sep 17 00:00:00 2001 From: ndonkoHenri Date: Fri, 23 Jan 2026 20:27:50 +0100 Subject: [PATCH 01/43] initial commit --- .../src/flet_cli/commands/build_base.py | 14 +- .../packages/flet/docs/publish/index.md | 331 +++++++++--------- 2 files changed, 178 insertions(+), 167 deletions(-) diff --git a/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py b/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py index e44aef089..b4bcb6951 100644 --- a/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py +++ b/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py @@ -76,7 +76,7 @@ def __init__(self, parser: argparse.ArgumentParser) -> None: "config_platform": "macos", "flutter_build_command": "macos", "status_text": "macOS bundle", - "outputs": ["build/macos/Build/Products/Release/{product_name}.app"], + "outputs": ["build/macos/Build/Products/Release/{project_name}.app"], "dist": "macos", "can_be_run_on": ["Darwin"], }, @@ -241,8 +241,7 @@ def add_arguments(self, parser: argparse.ArgumentParser) -> None: "--project", dest="project_name", required=False, - help="Project name for the executable/bundle. " - "It is used in metadata and bundle IDs", + help="Project name for the executable/bundle and bundle IDs.", ) parser.add_argument( "--description", @@ -254,8 +253,8 @@ def add_arguments(self, parser: argparse.ArgumentParser) -> None: "--product", dest="product_name", required=False, - help="Display name of the app that is shown in window titles " - "and about app dialogs", + help="Display name shown in app launchers, window titles, " + "and about dialogs.", ) parser.add_argument( "--org", @@ -706,6 +705,7 @@ def setup_template_data(self): ) project_name_orig = ( self.options.project_name + or self.get_pyproject("tool.flet.project") or self.get_pyproject("project.name") or self.get_pyproject("tool.poetry.name") or self.python_app_path.name @@ -715,7 +715,9 @@ def setup_template_data(self): product_name = ( self.options.product_name or self.get_pyproject("tool.flet.product") - or project_name_orig + or self.get_pyproject("project.name") + or self.get_pyproject("tool.poetry.name") + or self.python_app_path.name ) split_per_abi = ( diff --git a/sdk/python/packages/flet/docs/publish/index.md b/sdk/python/packages/flet/docs/publish/index.md index 22505f7a6..5d8795034 100644 --- a/sdk/python/packages/flet/docs/publish/index.md +++ b/sdk/python/packages/flet/docs/publish/index.md @@ -100,20 +100,20 @@ src version = "0.1.0" description = "An Example." readme = "README.md" - requires-python = ">=3.9" + requires-python = ">=3.10" authors = [{ name = "Me", email = "me@example.com" }] dependencies = [ "flet" ] - [tool.flet.app] - path = "src" - [tool.flet] org = "com.mycompany" - product = "Example" + product = "My App" company = "My Company" copyright = "Copyright (C) 2025 by My Company" + + [tool.flet.app] + path = "src" ``` /// @@ -155,15 +155,15 @@ Throughout this documentation, the following placeholders are used: ## How it works -`flet build ` command could be run from the root of Flet app directory: +`flet build ` command could be run from the root of Flet app project directory: -``` +```bash % flet build ``` -When running from a different directory you can provide the path to a directory with Flet app: +When running from a different directory, you can provide the path to a directory with Flet app: -``` +```bash flet build ``` @@ -172,15 +172,15 @@ See [this](#custom-output-directory) to set a custom location for build results. `flet build` uses Flutter SDK and the number of Flutter packages to build a distribution package from your Flet app. -When you run `flet build ` command it: +When you run `flet build `, the following steps are performed (using the default configuration): -* Creates a new Flutter project in `{flet_app_directory}/build/flutter` directory from https://github.com/flet-dev/flet-build-template template. Flutter app will contain a packaged Python app in the assets and use `flet` and `serious_python` packages to run Python app and render its UI respectively. The project is ephemeral and deleted upon completion. -* Copies custom icons and splash images (see below) from `assets` directory into a Flutter project. -* Generates icons for all platforms using [`flutter_launcher_icons`](https://pub.dev/packages/flutter_launcher_icons) package. -* Generates splash screens for web, iOS and Android targets using [`flutter_native_splash`](https://pub.dev/packages/flutter_native_splash) package. -* Packages Python app using `package` command of [`serious_python`](https://pub.dev/packages/serious_python) package. `package` command installs pure and binary Python packages from https://pypi.org and https://pypi.flet.dev for selected platform. If configured, `.py` files of installed packages and/or application will be compiled to `.pyc` files. All files, except `build` directory will be added to a package asset. -* Runs `flutter build ` command to produce an executable or an installable package. -* Copies build results to `{flet_app_directory}/build/` directory. +* A new Flutter project is created in `{flet_app_directory}/build/flutter` directory from [flet-dev/flet-build-template](https://github.com/flet-dev/flet-build-template) template. Flutter app will contain a packaged Python app in the assets and use `flet` and `serious_python` packages to run Python app and render its UI respectively. The project is ephemeral and deleted upon completion. +* Custom icons and splash images are copied from `assets` directory into a Flutter project. +* Icons are generated for all platforms using [`flutter_launcher_icons`](https://pub.dev/packages/flutter_launcher_icons) package. +* Splash screens are generated for web, iOS and Android targets using [`flutter_native_splash`](https://pub.dev/packages/flutter_native_splash) package. +* Python app is packaged using `package` command of [`serious_python`](https://pub.dev/packages/serious_python), which installs pure and binary Python packages from [pypi.org](https://pypi.org) and [pypi.flet.dev](https://pypi.flet.dev) for the selected platform. If configured, `.py` files of installed packages and/or application will be compiled to `.pyc` files. All files, except `build` directory will be added to a package asset. +* `flutter build ` command is executed to produce an executable or an installable package. +* Build results are copied to `{flet_app_directory}/build/` directory. ## Including Extensions @@ -216,8 +216,10 @@ Example of extensions can be found here. ## Product Name -The display name shown in window titles, about dialogs, and app launchers. -This is the user-facing name of your application. +The display (user-facing) name shown in window titles, launcher labels, and about dialogs. + +The product name does **not** control the on-disk executable or bundle +name. Use the [project name](#project-name) for artifact naming. **Default:** Derived from `project.name`, `tool.poetry.name` in `pyproject.toml`, or the name of your Flet app directory. @@ -238,13 +240,25 @@ product = "My Awesome App" /// -## Company Name +## Project name -The company name displayed in about app dialogs and metadata. +The project name in C-style identifier format (lowercase alphanumerics with underscores). +It is mainly used as name for executables, bundles, and identifiers. +It is also used to build [bundle ID](#bundle-id) and as the name for the executable/bundle. + +Its value is internally slugified (e.g., `my-app` becomes `my_app`) to keep artifact names safe. + +/// admonition | Resolution order +- `--project` CLI option +- `tool.flet.project` +- `project.name` +- `tool.poetry.name` +- project directory name +/// /// tab | `flet build` ```bash -flet build --company "My Company Inc." +flet build --project my_app ``` /// /// tab | `pyproject.toml` @@ -252,19 +266,25 @@ flet build --company "My Company Inc." /// tab | `[tool.flet]` ```toml [tool.flet] -company = "My Company Inc." +project = "my_app" ``` /// /// -## Copyright +## Organization name -Copyright text displayed in about app dialogs and metadata. +The organization name in reverse domain name notation, typically in the form `com.mycompany`. + +If you do not provide an explicit value for the organization name, but specify the [bundle ID](#bundle-id), +the organization name will be automatically generated by taking the part of the bundle ID before the last dot. +For example, with a bundle ID of `com.mycompany.myapp`, the organization name becomes `com.mycompany`. + +**Default:** `"com.flet"` /// tab | `flet build` ```bash -flet build --copyright "Copyright © 2025 My Company Inc." +flet build --org com.mycompany ``` /// /// tab | `pyproject.toml` @@ -272,19 +292,19 @@ flet build --copyright "Copyright © 2025 My Company Inc." /// tab | `[tool.flet]` ```toml [tool.flet] -copyright = "Copyright © 2025 My Company Inc." +org = "com.mycompany" ``` /// /// -## Flutter dependencies +## Company Name -Adding a Flutter package can be done in the `pyproject.toml` as follows: +The company name displayed in about app dialogs and metadata. /// tab | `flet build` ```bash -flet build +flet build --company "My Company Inc." ``` /// /// tab | `pyproject.toml` @@ -292,37 +312,104 @@ flet build /// tab | `[tool.flet]` ```toml [tool.flet] -flutter.dependencies = [ - "package_1", - "package_2", -] +company = "My Company Inc." ``` /// -/// tab | `[tool.flet.flutter.dependencies]` + +/// + +## Bundle ID + +The bundle ID for the application, typically in the form `"com.mycompany.app-name"`. + +If not explicitly specified, it is formed by combining the [organization name](#organization-name) +and the [project name](#project-name). + +**Default:** `"[organization-name].[project-name]"` + +/// tab | `flet build` +```bash +flet build --bundle-id com.mycompany.example-app +``` +/// +/// tab | `pyproject.toml` + +/// tab | `[tool.flet]` ```toml -[tool.flet.flutter.dependencies] -package_1 = "x.y.z" -package_2 = "x.y.z" +[tool.flet] +bundle_id = "com.mycompany.example-app" ``` /// -/// tab | `[tool.flet.flutter.dependencies.LOCAL_PACKAGE]` +/// tab | `[tool.flet.PLATFORM]` ```toml -[tool.flet.flutter.dependencies.LOCAL_PACKAGE] -path = "/path/to/LOCAL_PACKAGE" +[tool.flet.PLATFORM] +bundle_id = "com.mycompany.example-app-platform" ``` /// /// -## Custom output directory +## Versioning -By default, the build output is saved in the `/build/` directory. +### Build Number -This can be customized as follows: +An integer identifier (defaults to `1`) used internally to distinguish one build from another. +Each new build must have a unique, incrementing number; higher numbers indicate more recent builds. -/// tab | CLI +It's value can be set as follows: + +/// tab | `pyproject.toml` + +/// tab | `[tool.flet]` +```toml +[tool.flet] +build_number = 1 +``` +/// + +/// +/// tab | `flet build` ```bash -flet build --output +flet build --build-number 1 +``` +/// + +### Build Version + +A user‑facing version string in `x.y.z` format (defaults to `1.0.0`). +Increment this for each new release to differentiate it from previous versions. + +It's value can be set as follows: + +/// tab | `pyproject.toml` + +/// tab | `[project]` +```toml +[project] +version = "1.0.0" +``` +/// +/// tab | `[tool.poetry]` +```toml +[tool.poetry] +version = "1.0.0" +``` +/// + +/// +/// tab | `flet build` +```bash +flet build --build-version 1.0.0 +``` +/// + +## Copyright + +Copyright text displayed in about app dialogs and metadata. + +/// tab | `flet build` +```bash +flet build --copyright "Copyright © 2025 My Company Inc." ``` /// /// tab | `pyproject.toml` @@ -330,7 +417,7 @@ flet build --output /// tab | `[tool.flet]` ```toml [tool.flet] -output = "" +copyright = "Copyright © 2025 My Company Inc." ``` /// @@ -528,6 +615,28 @@ flet build --module-name start.py ``` /// +## Custom output directory + +By default, the build output is saved in the `/build/` directory. + +This can be customized as follows: + +/// tab | CLI +```bash +flet build --output +``` +/// +/// tab | `pyproject.toml` + +/// tab | `[tool.flet]` +```toml +[tool.flet] +output = "" +``` +/// + +/// + ## Compilation and cleanup By default, Flet does **not** compile your app files during packaging. @@ -654,60 +763,6 @@ Supported permissions: * permissions: * `android.permission.READ_MEDIA_VISUAL_USER_SELECTED": True` -## Versioning - -### Build Number - -An integer identifier (defaults to `1`) used internally to distinguish one build from another. -Each new build must have a unique, incrementing number; higher numbers indicate more recent builds. - -It's value can be set as follows: - -/// tab | `pyproject.toml` - -/// tab | `[tool.flet]` -```toml -[tool.flet] -build_number = 1 -``` -/// - -/// -/// tab | `flet build` -```bash -flet build --build-number 1 -``` -/// - -### Build Version - -A user‑facing version string in `x.y.z` format (defaults to `1.0.0`). -Increment this for each new release to differentiate it from previous versions. - -It's value can be set as follows: - -/// tab | `pyproject.toml` - -/// tab | `[project]` -```toml -[project] -version = "1.0.0" -``` -/// -/// tab | `[tool.poetry]` -```toml -[tool.poetry] -version = "1.0.0" -``` -/// - -/// -/// tab | `flet build` -```bash -flet build --build-version 1.0.0 -``` -/// - ## Customizing build template By default, `flet build` creates a temporary Flutter project using a @@ -836,44 +891,13 @@ host = "mydomain.com" /// +## Flutter dependencies - -### Project name - -The project name in C-style identifier format (lowercase alphanumerics with underscores). -It is used to build [bundle ID](#bundle-id) and as a name for bundle executable. - -**Default:** the name of your Flet project directory - -/// tab | `flet build` -```bash -flet build --project my-app -``` -/// -/// tab | `pyproject.toml` - -/// tab | `[tool.flet]` -```toml -[tool.flet] -project = "my-app" -``` -/// - -/// - -### Organization name - -The organization name in reverse domain name notation, typically in the form `com.mycompany`. - -If you do not provide an explicit value for the organization name, but specify the [bundle ID](#bundle-id), -the organization name will be automatically generated by taking the part of the bundle ID before the last dot. -For example, with a bundle ID of `com.mycompany.myapp`, the organization name becomes `com.mycompany`. - -**Default:** `"com.flet"` +Adding a Flutter package can be done in the `pyproject.toml` as follows: /// tab | `flet build` ```bash -flet build --org com.mycompany +flet build ``` /// /// tab | `pyproject.toml` @@ -881,38 +905,23 @@ flet build --org com.mycompany /// tab | `[tool.flet]` ```toml [tool.flet] -org = "com.mycompany" -``` -/// - -/// - -## Bundle ID - -The bundle ID for the application, typically in the form `"com.mycompany.app-name"`. - -If not explicitly specified, it is formed by combining the [organization name](#organization-name) -and the [project name](#project-name). - -**Default:** `"[organization-name].[project-name]"` - -/// tab | `flet build` -```bash -flet build --bundle-id com.mycompany.example-app +flutter.dependencies = [ + "package_1", + "package_2", +] ``` /// -/// tab | `pyproject.toml` - -/// tab | `[tool.flet]` +/// tab | `[tool.flet.flutter.dependencies]` ```toml -[tool.flet] -bundle_id = "com.mycompany.example-app" +[tool.flet.flutter.dependencies] +package_1 = "x.y.z" +package_2 = "x.y.z" ``` /// -/// tab | `[tool.flet.PLATFORM]` +/// tab | `[tool.flet.flutter.dependencies.LOCAL_PACKAGE]` ```toml -[tool.flet.PLATFORM] -bundle_id = "com.mycompany.example-app-platform" +[tool.flet.flutter.dependencies.LOCAL_PACKAGE] +path = "/path/to/LOCAL_PACKAGE" ``` /// From 2750093f0b7354d7fad38d704ca341ca17784249 Mon Sep 17 00:00:00 2001 From: ndonkoHenri Date: Sat, 24 Jan 2026 09:09:27 +0100 Subject: [PATCH 02/43] Add support for artifact name in build configuration and CLI arguments --- .../src/flet_cli/commands/build_base.py | 28 ++++++--- .../packages/flet/docs/publish/index.md | 59 +++++++++++++++---- 2 files changed, 69 insertions(+), 18 deletions(-) diff --git a/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py b/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py index b4bcb6951..d0c12aca5 100644 --- a/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py +++ b/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py @@ -76,7 +76,7 @@ def __init__(self, parser: argparse.ArgumentParser) -> None: "config_platform": "macos", "flutter_build_command": "macos", "status_text": "macOS bundle", - "outputs": ["build/macos/Build/Products/Release/{project_name}.app"], + "outputs": ["build/macos/Build/Products/Release/{artifact_name}.app"], "dist": "macos", "can_be_run_on": ["Darwin"], }, @@ -241,7 +241,14 @@ def add_arguments(self, parser: argparse.ArgumentParser) -> None: "--project", dest="project_name", required=False, - help="Project name for the executable/bundle and bundle IDs.", + help="Project name for bundle IDs and identifiers; used as the default " + "for artifact and product names", + ) + parser.add_argument( + "--artifact", + dest="artifact_name", + required=False, + help="Executable or bundle name on disk", ) parser.add_argument( "--description", @@ -703,20 +710,25 @@ def setup_template_data(self): .strip("/") .strip() ) - project_name_orig = ( + project_name_raw = ( self.options.project_name - or self.get_pyproject("tool.flet.project") or self.get_pyproject("project.name") - or self.get_pyproject("tool.poetry.name") or self.python_app_path.name ) - project_name_slug = slugify(cast(str, project_name_orig)) + project_name_slug = slugify(cast(str, project_name_raw)) project_name = project_name_slug.replace("-", "_") + artifact_name = ( + self.options.artifact_name + or self.get_pyproject("tool.flet.artifact") + or self.options.project_name + or self.get_pyproject("project.name") + or self.python_app_path.name + ) product_name = ( self.options.product_name or self.get_pyproject("tool.flet.product") + or self.options.project_name or self.get_pyproject("project.name") - or self.get_pyproject("tool.poetry.name") or self.python_app_path.name ) @@ -949,6 +961,7 @@ def setup_template_data(self): "split_per_abi": split_per_abi, "project_name": project_name, "project_name_slug": project_name_slug, + "artifact_name": artifact_name, "product_name": product_name, "description": ( self.options.description @@ -1880,6 +1893,7 @@ def ignore(path, names): build_output_dir = ( str(self.flutter_dir.joinpath(build_output)) .replace("{arch}", arch) + .replace("{artifact_name}", self.template_data["artifact_name"]) .replace("{project_name}", self.template_data["project_name"]) .replace("{product_name}", self.template_data["product_name"]) ) diff --git a/sdk/python/packages/flet/docs/publish/index.md b/sdk/python/packages/flet/docs/publish/index.md index 5d8795034..ce3b8c245 100644 --- a/sdk/python/packages/flet/docs/publish/index.md +++ b/sdk/python/packages/flet/docs/publish/index.md @@ -219,10 +219,18 @@ Example of extensions can be found here. The display (user-facing) name shown in window titles, launcher labels, and about dialogs. The product name does **not** control the on-disk executable or bundle -name. Use the [project name](#project-name) for artifact naming. +name. Use the [artifact name](#artifact-name) for artifact naming. -**Default:** Derived from `project.name`, `tool.poetry.name` in `pyproject.toml`, -or the name of your Flet app directory. +**Default:** Derived from `project.name` in `pyproject.toml` or the name of your +Flet app directory. + +/// admonition | Resolution order +- `--product` CLI option +- `tool.flet.product` +- `--project` CLI option +- `project.name` +- project directory name +/// /// tab | `flet build` ```bash @@ -240,19 +248,48 @@ product = "My Awesome App" /// +## Artifact name + +The on-disk name for executables and app bundles. +It does **not** affect bundle IDs or package identifiers. + +Its value is used as-is (no slugification), so it can include spaces or accents. + +/// admonition | Resolution order +- `--artifact` CLI option +- `tool.flet.artifact` +- `--project` CLI option +- `project.name` +- project directory name +/// + +/// tab | `flet build` +```bash +flet build --artifact "My Awesome App" +``` +/// +/// tab | `pyproject.toml` + +/// tab | `[tool.flet]` +```toml +[tool.flet] +artifact = "My Awesome App" +``` +/// + +/// + ## Project name The project name in C-style identifier format (lowercase alphanumerics with underscores). -It is mainly used as name for executables, bundles, and identifiers. -It is also used to build [bundle ID](#bundle-id) and as the name for the executable/bundle. +It is used for bundle IDs and other internal identifiers. -Its value is internally slugified (e.g., `my-app` becomes `my_app`) to keep artifact names safe. +Its value is internally slugified (e.g., `my-app` becomes `my_app`) to keep +identifier names safe. /// admonition | Resolution order - `--project` CLI option -- `tool.flet.project` - `project.name` -- `tool.poetry.name` - project directory name /// @@ -263,10 +300,10 @@ flet build --project my_app /// /// tab | `pyproject.toml` -/// tab | `[tool.flet]` +/// tab | `[project]` ```toml -[tool.flet] -project = "my_app" +[project] +name = "my_app" ``` /// From 0c71a922be74a21b1669705c51167d145e2c92d6 Mon Sep 17 00:00:00 2001 From: ndonkoHenri Date: Sat, 24 Jan 2026 09:09:54 +0100 Subject: [PATCH 03/43] flet-webview: Add troubleshooting section for NET::ERR_CLEARTEXT_NOT_PERMITTED error in Android --- .../packages/flet/docs/webview/index.md | 35 +++++++++++++------ 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/sdk/python/packages/flet/docs/webview/index.md b/sdk/python/packages/flet/docs/webview/index.md index e9c15be50..6156aaa8e 100644 --- a/sdk/python/packages/flet/docs/webview/index.md +++ b/sdk/python/packages/flet/docs/webview/index.md @@ -9,9 +9,9 @@ Display web content inside your [Flet](https://flet.dev) app using the `flet-web ## Platform Support -| Platform | Windows | macOS | Linux | iOS | Android | Web | -|----------|---------|-------|-------|-----|---------|-----| -| Supported| ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | +| Platform | Windows | macOS | Linux | iOS | Android | Web | +|-----------|---------|-------|-------|-----|---------|-----| +| Supported | ❌ | ✅ | ❌ | ✅ | ✅ | ✅ | ## Usage @@ -37,13 +37,28 @@ pip install flet-webview # (1)! --8<-- "{{ examples }}/example_1.py" ``` +## Troubleshooting + +### NET::ERR_CLEARTEXT_NOT_PERMITTED Error + +If you run into the NET::ERR_CLEARTEXT_NOT_PERMITTED error in Android, +then the app you’re using is trying to access a web page that wants to +transmit cleartext or unsecured information. Android blocks apps from +doing this in order to avoid compromising user data. + +For more details, see [this](https://developer.android.com/privacy-and-security/security-config#CleartextTraffic) +and [this](https://kinsta.com/blog/net-err_cleartext_not_permitted/). + +To fix it, the `AndroidManifest.xml` file needs to be modified, to include the `android:usesCleartextTraffic=”true”`. +This can be done through one of the following methods: + +/// tab | `pyproject.toml` +```toml +[tool.flet.android.manifest_application] +usesCleartextTraffic = "true" +``` +/// + ## Description {{ class_all_options(class_name) }} - -See also types: -- [`RequestMethod`](types/request_method.md) -- [`LogLevelSeverity`](types/log_level_severity.md) -- [`WebViewConsoleMessageEvent`](types/webview_console_message_event.md) -- [`WebViewJavaScriptEvent`](types/webview_javascript_event.md) -- [`WebViewScrollEvent`](types/webview_scroll_event.md) From 7c975a9bae56b7f52f9c7cbf18b5c8eba4cd89ec Mon Sep 17 00:00:00 2001 From: ndonkoHenri Date: Sat, 24 Jan 2026 09:44:24 +0100 Subject: [PATCH 04/43] Refactor output handling to check for string type before logging in build and flutter scripts --- .../flet-cli/src/flet_cli/commands/build_base.py | 16 ++++++++-------- .../src/flet_cli/commands/flutter_base.py | 12 +++++++----- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py b/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py index d0c12aca5..100357f2e 100644 --- a/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py +++ b/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py @@ -1279,9 +1279,9 @@ def customize_icons(self): capture_output=self.verbose < 1, ) if icons_result.returncode != 0: - if icons_result.stdout: + if isinstance(icons_result.stdout, str): console.log(icons_result.stdout, style=verbose1_style) - if icons_result.stderr: + if isinstance(icons_result.stderr, str): console.log(icons_result.stderr, style=error_style) self.cleanup(icons_result.returncode) console.log(f"Generated app icons {self.emojis['checkmark']}") @@ -1529,9 +1529,9 @@ def customize_splash_images(self): capture_output=self.verbose < 1, ) if splash_result.returncode != 0: - if splash_result.stdout: + if isinstance(splash_result.stdout, str): console.log(splash_result.stdout, style=verbose1_style) - if splash_result.stderr: + if isinstance(splash_result.stderr, str): console.log(splash_result.stderr, style=error_style) self.cleanup(splash_result.returncode) console.log(f"Generated splash screens {self.emojis['checkmark']}") @@ -1743,9 +1743,9 @@ def package_python_app(self): ) if package_result.returncode != 0: - if package_result.stdout: + if isinstance(package_result.stdout, str): console.log(package_result.stdout, style=verbose1_style) - if package_result.stderr: + if isinstance(package_result.stderr, str): console.log(package_result.stderr, style=error_style) self.cleanup(package_result.returncode) @@ -1858,9 +1858,9 @@ def _run_flutter_command(self): build_result.returncode != 0 or "Encountered error while creating the IPA" in str(build_result.stderr) ): - if build_result.stdout: + if isinstance(build_result.stdout, str): console.log(build_result.stdout, style=verbose1_style) - if build_result.stderr: + if isinstance(build_result.stderr, str): console.log(build_result.stderr, style=error_style) self.cleanup(build_result.returncode if build_result.returncode else 1) diff --git a/sdk/python/packages/flet-cli/src/flet_cli/commands/flutter_base.py b/sdk/python/packages/flet-cli/src/flet_cli/commands/flutter_base.py index aca0ea5a6..f2561556f 100644 --- a/sdk/python/packages/flet-cli/src/flet_cli/commands/flutter_base.py +++ b/sdk/python/packages/flet-cli/src/flet_cli/commands/flutter_base.py @@ -223,9 +223,9 @@ def install_flutter(self): capture_output=self.verbose < 1, ) if config_result.returncode != 0: - if config_result.stdout: + if isinstance(config_result.stdout, str): console.log(config_result.stdout, style=verbose1_style) - if config_result.stderr: + if isinstance(config_result.stderr, str): console.log(config_result.stderr, style=error_style) self.cleanup(config_result.returncode) @@ -260,9 +260,9 @@ def install_jdk(self): capture_output=self.verbose < 1, ) if config_result.returncode != 0: - if config_result.stdout: + if isinstance(config_result.stdout, str): console.log(config_result.stdout, style=verbose1_style) - if config_result.stderr: + if isinstance(config_result.stderr, str): console.log(config_result.stderr, style=error_style) self.cleanup(config_result.returncode) @@ -375,8 +375,10 @@ def run_flutter_doctor(self): cwd=os.getcwd(), capture_output=True, ) - if flutter_doctor.returncode == 0 and flutter_doctor.stdout: + if flutter_doctor.stdout: console.log(flutter_doctor.stdout, style=verbose1_style) + if flutter_doctor.stderr: + console.log(flutter_doctor.stderr, style=error_style) def update_status(self, status): if self.no_rich_output: From a323c9aca87621eebd1233c001ee7930045cb43f Mon Sep 17 00:00:00 2001 From: ndonkoHenri Date: Sat, 24 Jan 2026 17:01:00 +0100 Subject: [PATCH 05/43] improve publish docs --- .../src/flet_cli/commands/flutter_base.py | 6 +- .../packages/flet/docs/controls/page.md | 9 + .../packages/flet/docs/publish/index.md | 826 +++++++++--------- 3 files changed, 445 insertions(+), 396 deletions(-) diff --git a/sdk/python/packages/flet-cli/src/flet_cli/commands/flutter_base.py b/sdk/python/packages/flet-cli/src/flet_cli/commands/flutter_base.py index f2561556f..839d7b6f8 100644 --- a/sdk/python/packages/flet-cli/src/flet_cli/commands/flutter_base.py +++ b/sdk/python/packages/flet-cli/src/flet_cli/commands/flutter_base.py @@ -71,7 +71,8 @@ def add_arguments(self, parser: argparse.ArgumentParser) -> None: "--no-rich-output", action="store_true", default=False, - help="Disable rich output and prefer plain text. Useful on Windows builds", + help="Disable rich output and prefer plain text. Useful on Windows builds" + "[env: FLET_CLI_NO_RICH_OUTPUT=]", ) parser.add_argument( "--yes", @@ -85,7 +86,8 @@ def add_arguments(self, parser: argparse.ArgumentParser) -> None: "--skip-flutter-doctor", action="store_true", default=False, - help="Skip running Flutter doctor upon failed builds", + help="Skip running Flutter doctor upon failed builds" + "[env: FLET_CLI_SKIP_FLUTTER_DOCTOR=]", ) def handle(self, options: argparse.Namespace) -> None: diff --git a/sdk/python/packages/flet/docs/controls/page.md b/sdk/python/packages/flet/docs/controls/page.md index a83a777bf..2cbe5d586 100644 --- a/sdk/python/packages/flet/docs/controls/page.md +++ b/sdk/python/packages/flet/docs/controls/page.md @@ -31,10 +31,19 @@ Shows how to lock your app to specific device orientations ### Hidden app window on startup +A Flet desktop app (Windows, macOS, or Linux) can start with its window hidden. +This lets your app perform initial setup (for example, add content, resize +or position the window) before showing it to the user. + +In the example below, the window is resized and centered before becoming visible: + ```python --8<-- "{{ examples }}/window_hidden_on_start.py" ``` +If you need this feature when packaging a desktop app using +[`flet build`](../cli/flet-build.md), see [this](../publish/index.md#hidden-app-window-on-startup). + ### Toggle semantics debugger ```python diff --git a/sdk/python/packages/flet/docs/publish/index.md b/sdk/python/packages/flet/docs/publish/index.md index ce3b8c245..f38632b27 100644 --- a/sdk/python/packages/flet/docs/publish/index.md +++ b/sdk/python/packages/flet/docs/publish/index.md @@ -118,22 +118,11 @@ src /// 2. An optional directory that contains application assets - (images, sound, text and other files required by your app) as well as images + (images, sound, text, and other files required by your app) as well as images used for package [icons](#icons) and [splash screens](#splash-screen). 3. The main [entry point](#entry-point) of your Flet app. It usually contains the call to `ft.run()`. -/// admonition | Using `requirements.txt` instead of `pyproject.toml` -Instead of a `pyproject.toml` file, you can also use `requirements.txt` file to specify dependencies. - -In this case, two things to keep in mind: - -- if both files are present, `flet build` will ignore `requirements.txt`. -- don't use `pip freeze > requirements.txt` to generate this file or fill it with dependencies, - as it may include packages incompatible with the target platform. Instead, hand-pick and include - only the direct dependencies required by your app, including `flet`. -/// - /// admonition | Tip type: tip To quickly set up a project with the correct structure, use the [`flet create`](../cli/flet-create.md) command: @@ -145,12 +134,15 @@ flet create Where `` is the name for your project directory. /// -/// admonition | Note -Throughout this documentation, the following placeholders are used: +/// admonition | Using `requirements.txt` instead of `pyproject.toml` +Instead of a `pyproject.toml` file, you can also use `requirements.txt` file to specify dependencies. -- `` - one of the following: `apk`, `aab`, `ipa`, `web`, `macos`, `windows`, `linux`. -- `` - the path to the directory containing your Flet project/app. -- `PLATFORM` - one of the following: `android`, `ios`, `web`, `macos`, `windows`, `linux`. +In this case, two things to keep in mind: + +- if both files are present, `flet build` will ignore `requirements.txt`. +- don't use `pip freeze > requirements.txt` to generate this file or fill it with dependencies, + as it may include packages incompatible with the target platform. Instead, hand-pick and include + only the direct dependencies required by your app, including `flet`. /// ## How it works @@ -182,55 +174,62 @@ When you run `flet build `, the following steps are performed ( * `flutter build ` command is executed to produce an executable or an installable package. * Build results are copied to `{flet_app_directory}/build/` directory. -## Including Extensions +## Configuration options -If your app uses Flet extensions (third-party packages), -simply add them to your project's dependencies: +/// admonition | Understanding `pyproject.toml` structure +Flet loads `pyproject.toml` as a nested dictionary and looks up settings by +dot-separated paths (for example, `tool.flet.web.base_url`). + +For example, the two forms below are equivalent (will be internally resolved to the same key-value pair): + +- **Form 1** (will be used/preferred throughout this documentation) + ```toml + [tool.flet.section] + key = "value" + ``` + +- **Form 2** + ```toml + [tool.flet] + section.key = "value" + ``` + +But they are different or should not be confused with the +below ("quoted keys" are literals and do not create nesting): -/// tab | PyPI -```toml -dependencies = [ - "flet-extension", - "flet", -] -``` -/// -/// tab | Git Repo -```toml -dependencies = [ -"flet-extension @ git+https://github.com/account/flet-extension.git", -"flet", -] -``` -/// -/// tab | Local Package ```toml -dependencies = [ -"flet-extension @ file:///path/to/flet-extension", -"flet", -] +[tool.flet] +"section.key" = "value" ``` /// -Example of extensions can be found here. +/// admonition | Placeholders +Throughout this documentation, the following placeholders are used: + +- [``](../cli/flet-build.md#target_platform) - one of the following: `apk`, `aab`, `ipa`, `web`, `macos`, `windows`, `linux`. +- `` - one of the following: `android`, `ios`, `web`, `macos`, `windows`, `linux`. +- `` - the path to the directory containing your Flet project/app. +- [``](../cli/flet-build.md#python_app_path) +/// -## Product Name +### Product name The display (user-facing) name shown in window titles, launcher labels, and about dialogs. -The product name does **not** control the on-disk executable or bundle +It does **not** control the on-disk executable or bundle name. Use the [artifact name](#artifact-name) for artifact naming. -**Default:** Derived from `project.name` in `pyproject.toml` or the name of your -Flet app directory. +#### Resolution order -/// admonition | Resolution order -- `--product` CLI option -- `tool.flet.product` -- `--project` CLI option -- `project.name` -- project directory name -/// +Its value is determined in the following order of precedence: + +1. `--product` +2. `[tool.flet].product` +3. `--project` +4. `[project].name` +5. project/app directory name + +#### Example /// tab | `flet build` ```bash @@ -238,30 +237,32 @@ flet build --product "My Awesome App" ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet]` ```toml [tool.flet] product = "My Awesome App" ``` /// -/// +### Artifact name -## Artifact name +The on-disk name for executables and/or app bundles. For example, on Windows it +determines the name of the `.exe` file, and on macOS it sets the name of the `.app` bundle. -The on-disk name for executables and app bundles. -It does **not** affect bundle IDs or package identifiers. +It does **not** affect [bundle ID](#bundle-id)s or package identifiers. -Its value is used as-is (no slugification), so it can include spaces or accents. +It can contain spaces or accents. -/// admonition | Resolution order -- `--artifact` CLI option -- `tool.flet.artifact` -- `--project` CLI option -- `project.name` -- project directory name -/// +#### Resolution order + +Its value is determined in the following order of precedence: + +1. `--artifact` +2. `[tool.flet].artifact` +3. `--project` +4. `[project].name` +5. project/app directory name + +#### Example /// tab | `flet build` ```bash @@ -269,29 +270,29 @@ flet build --artifact "My Awesome App" ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet]` ```toml [tool.flet] artifact = "My Awesome App" ``` /// -/// - -## Project name +### Project name The project name in C-style identifier format (lowercase alphanumerics with underscores). -It is used for bundle IDs and other internal identifiers. +It is used for [bundle IDs](#bundle-id) and other internal identifiers. -Its value is internally slugified (e.g., `my-app` becomes `my_app`) to keep -identifier names safe. +Its value is internally slugified and hyphens become underscores +(e.g., `my-app` becomes `my_app`) to keep identifier names safe. -/// admonition | Resolution order -- `--project` CLI option -- `project.name` -- project directory name -/// +#### Resolution order + +Its value is determined in the following order of precedence: + +1. `--project` +2. `[project].name` +3. project/app directory name + +#### Example /// tab | `flet build` ```bash @@ -299,25 +300,32 @@ flet build --project my_app ``` /// /// tab | `pyproject.toml` - -/// tab | `[project]` ```toml [project] name = "my_app" ``` /// -/// - -## Organization name +### Organization name The organization name in reverse domain name notation, typically in the form `com.mycompany`. -If you do not provide an explicit value for the organization name, but specify the [bundle ID](#bundle-id), -the organization name will be automatically generated by taking the part of the bundle ID before the last dot. -For example, with a bundle ID of `com.mycompany.myapp`, the organization name becomes `com.mycompany`. +If you do not provide an explicit value for the organization name, +but specify the [bundle ID](#bundle-id), the organization name will be +internally constructed by taking the part of this [bundle ID](#bundle-id) +before the last dot. For example, with a bundle ID of `com.mycompany.myapp`, +the organization name becomes `com.mycompany`. -**Default:** `"com.flet"` +#### Resolution order + +Its value is determined in the following order of precedence: + +1. `--org` +2. `[tool.flet.].org` +3. `[tool.flet].org` +4. Default: `"com.flet"` + +#### Example /// tab | `flet build` ```bash @@ -325,142 +333,180 @@ flet build --org com.mycompany ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet]` ```toml -[tool.flet] +[tool.flet] # or [tool.flet.] org = "com.mycompany" ``` /// -/// - -## Company Name +### Company Name The company name displayed in about app dialogs and metadata. +#### Resolution order + +Its value is determined in the following order of precedence: + +1. `--company` +2. `[tool.flet].company` + +#### Example + /// tab | `flet build` ```bash flet build --company "My Company Inc." ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet]` ```toml [tool.flet] company = "My Company Inc." ``` /// -/// - -## Bundle ID +### Bundle ID -The bundle ID for the application, typically in the form `"com.mycompany.app-name"`. +The bundle ID for the application, typically in the form `"com.mycompany.my_app"`. If not explicitly specified, it is formed by combining the [organization name](#organization-name) and the [project name](#project-name). -**Default:** `"[organization-name].[project-name]"` +#### Resolution order + +Its value is determined in the following order of precedence: + +1. `--bundle-id` +2. `[tool.flet.].bundle_id` +3. `[tool.flet].bundle_id` +4. Default: `"[organization-name].[project-name]"` + +#### Example /// tab | `flet build` ```bash -flet build --bundle-id com.mycompany.example-app +flet build --bundle-id com.mycompany.my_app ``` /// /// tab | `pyproject.toml` +```toml +[tool.flet] # or [tool.flet.] +bundle_id = "com.mycompany.my_app" +``` +/// + +### Including Extensions + +If your app uses Flet extensions (third-party packages), +they must equally be part of your app's dependencies. -/// tab | `[tool.flet]` +/// tab | PyPI ```toml -[tool.flet] -bundle_id = "com.mycompany.example-app" +dependencies = [ + "flet-extension", + "flet", +] ``` /// -/// tab | `[tool.flet.PLATFORM]` +/// tab | Git Repo ```toml -[tool.flet.PLATFORM] -bundle_id = "com.mycompany.example-app-platform" +dependencies = [ +"flet-extension @ git+https://github.com/account/flet-extension.git", +"flet", +] ``` /// - +/// tab | Local Package +```toml +dependencies = [ +"flet-extension @ file:///path/to/flet-extension", +"flet", +] +``` /// -## Versioning +Example of extensions can be found [here](../extend/built-in-extensions.md). -### Build Number +### Versioning + +#### Build Number An integer identifier (defaults to `1`) used internally to distinguish one build from another. Each new build must have a unique, incrementing number; higher numbers indicate more recent builds. -It's value can be set as follows: +##### Resolution order -/// tab | `pyproject.toml` +Its value is determined in the following order of precedence: -/// tab | `[tool.flet]` -```toml -[tool.flet] -build_number = 1 -``` -/// +1. `--build-number` +2. `[tool.flet].build_number` + +##### Example -/// /// tab | `flet build` ```bash flet build --build-number 1 ``` /// +/// tab | `pyproject.toml` +```toml +[tool.flet] +build_number = 1 +``` +/// -### Build Version +#### Build Version A user‑facing version string in `x.y.z` format (defaults to `1.0.0`). Increment this for each new release to differentiate it from previous versions. -It's value can be set as follows: +##### Resolution order -/// tab | `pyproject.toml` +Its value is determined in the following order of precedence: -/// tab | `[project]` -```toml -[project] -version = "1.0.0" -``` -/// -/// tab | `[tool.poetry]` -```toml -[tool.poetry] -version = "1.0.0" -``` -/// +1. `--build-version` +2. `[project].version` +3. `[tool.poetry].version` + +##### Example -/// /// tab | `flet build` ```bash flet build --build-version 1.0.0 ``` /// +/// tab | `pyproject.toml` +```toml +[project] +version = "1.0.0" +``` +/// -## Copyright +### Copyright Copyright text displayed in about app dialogs and metadata. +#### Resolution order + +Its value is determined in the following order of precedence: + +1. `--copyright` +2. `[tool.flet].copyright` + +#### Example + /// tab | `flet build` ```bash -flet build --copyright "Copyright © 2025 My Company Inc." +flet build --copyright "Copyright © 2026 My Company Inc." ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet]` ```toml [tool.flet] -copyright = "Copyright © 2025 My Company Inc." +copyright = "Copyright © 2026 My Company Inc." ``` /// -/// - -## Icons +### Icons You can customize app icons for all platforms (except Linux) using image files placed in the `assets` directory of your Flet app. @@ -474,11 +520,11 @@ For the iOS platform, transparency (alpha channel) will be automatically removed | iOS | `icon_ios.png` | ≥ 1024×1024 px | Transparency (alpha channel) is not supported and will be automatically removed if present. | | Android | `icon_android.png` | ≥ 192×192 px | | | Web | `icon_web.png` | ≥ 512×512 px | | -| Windows | `icon_windows.ico` or `icon_windows.png` | 256×256 px | `.png` file will be internally converted to a 256×256 px `.ico` icon. | +| Windows | `icon_windows.ico` or `icon_windows.png` | 256×256 px | `.png` file will be internally converted to a 256×256 px `.ico` icon. | | macOS | `icon_macos.png` | ≥ 1024×1024 px | | -## Splash screen +### Splash screen A splash screen is a visual element displayed when an app is launching, typically showing a logo or image while the app loads. @@ -489,7 +535,7 @@ the `assets` directory of your Flet app. If platform-specific splash images are not provided, Flet will fall back to `splash.png`. If that is also missing, it will use `icon.png` or any supported format such as `.bmp`, `.jpg`, or `.webp`. -### Splash images +#### Splash images | Platform | Dark Fallback Order | Light Fallback Order | |----------|--------------------------------------------------------------------------------------------------|--------------------------------------------------| @@ -497,23 +543,30 @@ If that is also missing, it will use `icon.png` or any supported format such as | Android | `splash_dark_android.png` → `splash_android.png` → `splash_dark.png` → `splash.png` → `icon.png` | `splash_android.png` → `splash.png` → `icon.png` | | Web | `splash_dark_web.png` → `splash_web.png` → `splash_dark.png` → `splash.png` → `icon.png` | `splash_web.png` → `splash.png` → `icon.png` | -### Splash Background Colors +#### Splash Background Colors You can customize splash background colors using the following options: -- **Splash Color:** Background color for light mode splash screens (defaults to `#ffffff`) -- **Splash Dark Color:** Background color for dark mode splash screens (defaults to `#333333`) +- **Splash Color**: Background color for light mode splash screens. +- **Splash Dark Color**: Background color for dark mode splash screens. -/// tab | `pyproject.toml` +##### Resolution order -/// tab | `[tool.flet]` -```toml -[tool.flet] -splash.color = "#ffffff" -splash.dark_color = "#333333" +Their values are respectively determined in the following order of precedence: + +1. `--splash-color` / `--splash-dark-color` +2. `[tool.flet..splash].color` / `[tool.flet..splash].dark_color` +3. `[tool.flet.splash].color` / `[tool.flet.splash].dark_color` +4. `#ffffff` / `#333333` + +##### Example + +/// tab | `flet build` +``` +flet build --splash-color #ffffff --splash-dark-color #333333 ``` /// -/// tab | `[tool.flet.splash]` +/// tab | `pyproject.toml` ```toml [tool.flet.splash] color = "#ffffff" @@ -521,227 +574,240 @@ dark_color = "#333333" ``` /// -/// -/// tab | `flet build` -```bash -flet build --splash-color #ffffff --splash-dark-color #333333 -``` -/// - -### Disabling Splash Screens - -Splash screens are enabled by default. - -See the respective platform docs for more information: [iOS](ios.md#disable-splash-screen), -[Android](android.md#disable-splash-screen), and [Web](web/static-website/index.md#disable-splash-screen). +#### Disabling Splash Screens -## Boot screen +Splash screens are enabled by default. To disable it for a particular platform, +see the corresponding documentation: [iOS](ios.md#disable-splash-screen),[Android](android.md#disable-splash-screen), and [Web](web/static-website/index.md#disable-splash-screen). -The boot screen is shown while the archive with Python app is being unpacked to a device file system. -It is shown after splash screen and before startup screen. App archive does not include 3rd-party site packages. -If the archive is small and its unpacking is fast you could leave this screen disabled (default). +### Boot screen -Below are its customizable properties and respective defaults: +The boot screen is shown while the archive with Python app is being unpacked to a +device file system. It is shown after the [splash screen](#splash-screen) and +before the [startup screen](#startup-screen). App archive does not include +3rd-party site packages. If the archive is small and its +unpacking is fast you could leave this screen disabled (default). -/// tab | `[tool.flet.app.boot_screen]` -```toml -[tool.flet.app.boot_screen] -show = false -message = "Preparing the app for its first launch…" -``` -/// -/// tab | `[tool.flet.PLATFORM.app.boot_screen]` -Its values can be set platform-specific too: +#### Example +/// tab | `pyproject.toml` ```toml -[tool.flet.android.app.boot_screen] +[tool.flet.app.boot_screen] # or [tool.flet..app.boot_screen] show = false message = "Preparing the app for its first launch…" ``` /// -## Startup screen +### Startup screen -The startup screen is shown while the archive (`app.zip`), which contains the 3rd-party site packages (Android only), +The startup screen is shown while the archive (`app.zip`), +which contains the 3rd-party site packages (Android only), is being unpacked and the Python app is starting. -/// admonition | Note -Startup screen is shown after the [boot screen](#boot-screen). -/// +It is shown after the [boot screen](#boot-screen). -Below are its customizable properties and respective defaults: +#### Example -/// tab | `[tool.flet.app.startup_screen]` +/// tab | `pyproject.toml` ```toml -[tool.flet.app.startup_screen] +[tool.flet.app.startup_screen] # or [tool.flet..app.startup_screen] show = false message = "Starting up the app…" ``` /// -/// tab | `[tool.flet.PLATFORM.app.startup_screen]` -Its values can be set platform-specific too: +### Hidden app window on startup + +A Flet desktop app (Windows, macOS, or Linux) can start with its window hidden. +This lets your app perform initial setup (for example, add content, resize or +position the window) before showing it to the user. + +See this [code example](../controls/page.md#hidden-app-window-on-startup). + +#### Example + +/// tab | `pyproject.toml` ```toml -[tool.flet.android.app.startup_screen] -show = false -message = "Starting up the app…" +[tool.flet.app] +hide_window_on_start = true ``` /// -## Launch an app with a hidden window +### Entry point -A Flet desktop app on Windows, macOS, or Linux can start with its window hidden. This allows you to add initial content, resize the window, and position it on the screen before revealing it to the user. +This is where the execution of your Flet app begins. It is the Python file that +contains the call to `flet.run()` or `flet.render()`. +If provided without the Python file extension (`.py`), it will be appended internally. -In the example below, the window is resized and centered before becoming visible: +[//]: # (Also, it must exist in the `package_app_path`.) -```py -import flet as ft +#### Resolution order -async def main(page: ft.Page): - page.add(ft.Text("Hello!")) - page.window.width = 300 - page.window.height = 200 - page.update() - await page.window.center() - await asyncio.sleep(3) - page.window.visible = True - page.update() +Its value is determined in the following order of precedence: -ft.run(main) -``` +1. `--module-name` +2. `[tool.flet.app].module` +3. `"main.py"` -To enable hidden window during development use `flet run` with `-n` option: +#### Example +/// tab | `flet build` +```bash +flet build --module-name app.py ``` -flet run -n your_app.py -``` - -To start an app with hidden window packaged with `flet build` add the following to your `pyproject.toml`: - +/// +/// tab | `pyproject.toml` ```toml [tool.flet.app] -hide_window_on_start = true +module = "app.py" ``` +/// -## Entry point +### Source packages -The Flet application entry (or starting) point refers to the file that contains the call to `ft.run()`. +If one or more of your app dependencies do not provide a pre-built binary distribution (wheels), +they must be built from source distribution and packaged as `.whl` files. +A source distribution is a source archive (usually .tar.gz or .zip) that contains: +the package's Python source code, package metadata, and instructions on how to build and install the package. -By default, Flet assumes this file is named `main.py`. -However, if your entry point is different (for example, `start.py`), you can specify it as follows: +#### Resolution order -/// tab | `pyproject.toml` +Its value is determined in the following order of precedence: -/// tab | `[tool.flet]` -```toml -[tool.flet] -app.module = "start.py" +1. `--source-packages` +2. `[tool.flet.].source_packages` +3. `[tool.flet].source_packages` +4. `SERIOUS_PYTHON_ALLOW_SOURCE_DISTRIBUTIONS` (environment variable; comma-separated packages) + +#### Example + +/// tab | `flet build` +```bash +flet build --source-packages package1 package2 ``` /// -/// tab | `[tool.flet.app]` +/// tab | `pyproject.toml` ```toml -[tool.flet.app] -module = "start.py" +[tool.flet] +source_packages = ["package1", "package2"] ``` /// - -/// -/// tab | `flet build` -```bash -flet build --module-name start.py +/// tab | `.env` +```dotenv +SERIOUS_PYTHON_ALLOW_SOURCE_DISTRIBUTIONS="package1,package2" ``` /// -## Custom output directory +### Output directory + +The directory where the build output is saved. -By default, the build output is saved in the `/build/` directory. +#### Resolution order -This can be customized as follows: +Its value is determined in the following order of precedence: -/// tab | CLI +1. `--output` or `-o` +2. `[tool.flet].output` +3. `/build/` + +#### Example + +/// tab | `flet build` ```bash flet build --output ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet]` ```toml [tool.flet] output = "" ``` /// -/// +### Compilation and cleanup -## Compilation and cleanup +Flet can compile your app's `.py` files and/or installed packages' `.py` files into +`.pyc` files during the packaging process. Additionally, it can remove/cleanup +unnecessary package files upon successful compilation. + +- Compilation: + * `compile-app`: compile app's `.py` files + * `compile-packages`: compile site/installed packages' `.py` files + +- Cleanup: + * `cleanup-app`: + * `cleanup-app-files`: + * `cleanup-packages-files`: + * `cleanup-packages`: remove unnecessary package files upon successful compilation By default, Flet does **not** compile your app files during packaging. This allows the build process to complete even if there are syntax errors, which can be useful for debugging or rapid iteration. -* `compile-app`: compile app's `.py` files -* `compile-packages`: compile site/installed packages' `.py` files -* `cleanup-packages`: remove unnecessary package files upon successful compilation +#### Resolution order -Enable one or more of them as follows: +The values of `compile-app` and `cleanup-app` are respectively determined in the following order of precedence: -/// tab | `pyproject.toml` +1. `--compile-app` / `--cleanup-app` +2. `[tool.flet..compile].app` / `[tool.flet..cleanup].app` +3. `[tool.flet.compile].app` / `[tool.flet.cleanup].app` +4. `False` / `False` -/// tab | `[tool.flet]` -```toml -[tool.flet] -compile.app = true -compile.packages = true -compile.cleanup = true +The values of `compile-packages` and `cleanup-packages` are respectively determined in the following order of precedence: + +1. `--compile-packages` / `--cleanup-packages` +2. `[tool.flet..compile].packages` / `[tool.flet..cleanup].packages` +3. `[tool.flet.compile].packages` / `[tool.flet.cleanup].packages` +4. `False` / `True` + +The values of `cleanup-app-files` and `cleanup-packages-files` are respectively determined in the following order of precedence: + +1. `--cleanup-app-files` / `--cleanup-package-files` +2. `[tool.flet..cleanup].app_files` / `[tool.flet..cleanup].package_files` +3. `[tool.flet.cleanup].app_files` / `[tool.flet.cleanup].package_files` +4. `False` / `False` + +#### Example + +/// tab | `flet build` +```bash +flet build --compile-app --compile-packages --cleanup-packages ``` /// -/// tab | `[tool.flet.compile]` +/// tab | `pyproject.toml` ```toml -[tool.flet.compile] +[tool.flet.compile] # or [tool.flet..compile] app = true packages = true cleanup = true ``` /// -/// -/// tab | `flet build` -```bash -flet build --compile-app --compile-packages --cleanup-packages -``` -/// - -## Permissions +### Permissions -`flet build` command allows granular control over permissions, features and entitlements +`flet build` command allows granular control over permissions, features, and entitlements embedded into `AndroidManifest.xml`, `Info.plist` and `.entitlements` files. See platform guides for setting specific [iOS](ios.md), [Android](android.md) and [macOS](macos.md) permissions. -### Cross-platform permissions +#### Cross-platform permissions There are pre-defined permissions that mapped to `Info.plist`, `*.entitlements` and `AndroidManifest.xml` for respective platforms. Setting permissions can be done as follows: +/// tab | `flet build` +```bash +flet build --permissions camera microphone +``` +/// /// tab | `pyproject.toml` - -/// tab | `[tool.flet]` ```toml [tool.flet] permissions = ["camera", "microphone"] ``` /// -/// -/// tab | `flet build` -```bash -flet build --permissions camera microphone -``` -/// - Supported permissions: * `location` @@ -749,7 +815,7 @@ Supported permissions: * `microphone` * `photo_library` -#### iOS mapping to `Info.plist` entries +##### iOS mapping to `Info.plist` entries * `location` * `NSLocationWhenInUseUsageDescription = This app uses location service when in use.` @@ -761,7 +827,7 @@ Supported permissions: * `photo_library` * `NSPhotoLibraryUsageDescription = This app saves photos and videos to the photo library.` -#### macOS mapping to entitlements +##### macOS mapping to entitlements * `location` * `com.apple.security.personal-information.location = True` @@ -772,7 +838,7 @@ Supported permissions: * `photo_library` * `com.apple.security.personal-information.photos-library = True` -#### Android mappings +##### Android mappings * `location` * permissions: @@ -800,7 +866,7 @@ Supported permissions: * permissions: * `android.permission.READ_MEDIA_VISUAL_USER_SELECTED": True` -## Customizing build template +### Customizing build template By default, `flet build` creates a temporary Flutter project using a [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) template from the flet-dev/flet-build-template @@ -809,7 +875,7 @@ which defaults to the current Flet version. You can customize this behavior by specifying your own template source, reference, and subdirectory. -### Template Source +#### Template Source Defines the location of the template to be used. Defaults to `gh:flet-dev/flet-build-template`, the [official Flet template](https://github.com/flet-dev/flet-build-template). @@ -820,53 +886,53 @@ Valid values include: - A full Git URL (e.g., `https://github.com/org/template.git`) - A local directory path -It's value can be set in either of the following ways: +Its value can be set in either of the following ways: -- via Command Line: - ```bash - flet build apk --template gh:flet-dev/flet-build-template - ``` - -- via `pyproject.toml`: - ```toml - [tool.flet.template] - url = "gh:flet-dev/flet-build-template" - ``` +/// tab | `flet build` +```bash +flet build apk --template gh:flet-dev/flet-build-template +``` +/// +/// tab | `pyproject.toml` +```toml +[tool.flet.template] +url = "gh:flet-dev/flet-build-template" +``` +/// -### Template Reference +#### Template Reference Defines the branch, tag, or commit to check out from the [template source](#template-source). Defaults to the version of Flet installed. -It's value can be set as follows: +Its value can be set in either of the following ways: +/// tab | `flet build` +```bash +flet build --template-ref main +``` +/// /// tab | `pyproject.toml` - -/// tab | `[tool.flet.template]` ```toml [tool.flet.template] ref = "main" ``` /// -/// -/// tab | `flet build` -```bash -flet build --template-ref main -``` -/// - -### Template Directory +#### Template Directory Defines the relative path to the cookiecutter template. If [template source](#template-source) is set, the path is treated as a subdirectory within its root; otherwise, it is relative to`/.cookiecutters/flet-build-template`. -It's value can be set as follows: +Its value can be set in either of the following ways: +/// tab | `flet build` +```bash +flet build --template gh:org/template --template-dir sub/directory +``` +/// /// tab | `pyproject.toml` - -/// tab | `[tool.flet.template]` ```toml [tool.flet.template] url = "gh:org/template" @@ -874,17 +940,9 @@ dir = "sub/directory" ``` /// -/// -/// tab | `flet build` -```bash -flet build --template gh:org/template --template-dir sub/directory -``` -/// - -## Deep linking +### Deep linking -[Deep linking](https://en.wikipedia.org/wiki/Mobile_deep_linking) allows users to -navigate directly to specific content within a mobile app +[Deep linking](https://en.wikipedia.org/wiki/Mobile_deep_linking) allows users to navigate directly to specific content within a mobile app using a URI (Uniform Resource Identifier). Instead of opening the app's homepage, deep links direct users to a specific page, feature, or content within the app, enhancing user experience and engagement. @@ -892,43 +950,32 @@ user experience and engagement. - **Scheme**: deep linking URL scheme, e.g. `"https"` or `"myapp"`. - **Host**: deep linking URL host. -See [this](https://docs.flutter.dev/ui/navigation/deep-linking) Flutter guide for more information. +See [this](https://docs.flutter.dev/ui/navigation/deep-linking) guide for more information. + +#### Resolution order -It can be configured as follows: +Its value is determined in the following order of precedence: + +1. `--deep-linking-scheme` / `--deep-linking-host` +2. `[tool.flet..deep_linking].scheme` / `[tool.flet..deep_linking].host`, where `` can be android or ios +3. `[tool.flet.deep_linking].scheme` / `[tool.flet.deep_linking].host` + +#### Example /// tab | `flet build` ```bash -flet build ipa --deep-linking-scheme "https" --deep-linking-host "mydomain.com" +flet build --deep-linking-scheme "https" --deep-linking-host "mydomain.com" ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet]` -```toml -[tool.flet] -deep_linking.scheme = "https" -deep_linking.host = "mydomain.com" -``` -/// -/// tab | `[tool.flet.deep_linking]` -```toml -[tool.flet.deep_linking] -scheme = "https" -host = "mydomain.com" -``` -/// -/// tab | `[tool.flet.PLATFORM.deep_linking]` -`PLATFORM` can be `android` or `ios`. ```toml -[tool.flet.PLATFORM.deep_linking] +[tool.flet.deep_linking] # or [tool.flet..deep_linking] scheme = "https" host = "mydomain.com" ``` /// -/// - -## Flutter dependencies +### Flutter dependencies Adding a Flutter package can be done in the `pyproject.toml` as follows: @@ -938,51 +985,36 @@ flet build ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet]` -```toml -[tool.flet] -flutter.dependencies = [ - "package_1", - "package_2", -] -``` -/// -/// tab | `[tool.flet.flutter.dependencies]` ```toml [tool.flet.flutter.dependencies] package_1 = "x.y.z" -package_2 = "x.y.z" -``` -/// -/// tab | `[tool.flet.flutter.dependencies.LOCAL_PACKAGE]` -```toml -[tool.flet.flutter.dependencies.LOCAL_PACKAGE] + +# or + +[tool.flet.flutter.dependencies.] path = "/path/to/LOCAL_PACKAGE" ``` /// -/// - -## Additional `flutter build` Arguments +### Additional `flutter build` Arguments During the `flet build` process, `flutter build` command gets called internally to -package your app for the specified platform. +package your app for the specified platform. Not all `flutter build` arguments are exposed or usable throgh `flet build` command. -It's value can be set in either of the following ways: +Passing additional arguments to `flutter build` can be done as follows: -/// tab | `pyproject.toml` +/// tab | `flet build` +```bash +flet build --flutter-build-args=--no-tree-shake-icons # (1)! -/// tab | `[tool.flet]` -```toml -[tool.flet] -flutter.build_args = [ - "--no-tree-shake-icons", - "--export-method", "development" -] +# or as key-value + +flet build --flutter-build-args=--export-method --flutter-build-args=development ``` + +1. `--flutter-build-args` can be used multiple times. /// -/// tab | `[tool.flet.flutter]` +/// tab | `pyproject.toml` ```toml [tool.flet.flutter] build_args = [ @@ -992,19 +1024,7 @@ build_args = [ ``` /// -/// tab | `flet build` -```bash -flet build --flutter-build-args=--no-tree-shake-icons # (1)! - -# OR as key-value - -flet build --flutter-build-args=--export-method --flutter-build-args=development -``` - -1. `--flutter-build-args` can be used multiple times. -/// - -## Verbose logging +### Verbose logging The `-v` (or `--verbose`) and `-vv` flags enables detailed output from all commands during the flet build process. Use `-v` for standard/basic verbose logging, or `-vv` for even more detailed output (higher verbosity level). @@ -1013,19 +1033,29 @@ If you need support, we may ask you to share this verbose log. ## Console output All output from Flet apps—such as `print()` statements, `sys.stdout.write()` calls, and messages from the Python -logging module—is now redirected to a `console.log` file. The full path to this file is available via the +logging module is redirected to a `console.log` file. The full path to this file is available via +[`StoragePaths.get_console_log_filename()`][flet.StoragePaths.get_console_log_filename] or the `FLET_APP_CONSOLE` environment variable. The log file is written in an unbuffered manner, allowing you to read it at any point in your Python program using: ```python -with open(os.getenv("FLET_APP_CONSOLE"), "r") as f: - log = f.read() -``` +import os +import flet as ft + +async def main(page: ft.Page): + log_file = await ft.StoragePaths().get_console_log_filename() + # or + # log_file = os.getenv("FLET_APP_CONSOLE") -You can then display the `log` content using an `AlertDialog` or any other Flet control. + with open(log_file, "r") as f: + logs = f.read() + page.add(ft.Text(logs)) # display on UI -If your program calls sys.exit(100), the complete log will automatically be shown in a scrollable window. +ft.run(main) +``` + +If your program calls `sys.exit(100)`, the complete log will automatically be shown in a scrollable window. This is a special “magic” exit code for debugging purposes: ```python @@ -1034,3 +1064,11 @@ sys.exit(100) ``` Calling `sys.exit()` with any other code will terminate the app without displaying the log. + +## Continuous Integration/Continuous Deployment (CI/CD) + +You can use `flet build` command in your CI/CD pipelines to automate the build and release process of your Flet apps. + +### GitHub Actions + +TBA From 9c8c886ea57c4e0b6b58ccb964eb499033f79a8b Mon Sep 17 00:00:00 2001 From: ndonkoHenri Date: Sat, 24 Jan 2026 18:23:54 +0100 Subject: [PATCH 06/43] improve publish docs --- .../src/flet_cli/commands/build_base.py | 24 +++- .../packages/flet/docs/publish/index.md | 123 +++++++++++++++--- 2 files changed, 121 insertions(+), 26 deletions(-) diff --git a/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py b/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py index 100357f2e..e392a9d66 100644 --- a/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py +++ b/sdk/python/packages/flet-cli/src/flet_cli/commands/build_base.py @@ -535,23 +535,26 @@ def add_arguments(self, parser: argparse.ArgumentParser) -> None: parser.add_argument( "--android-signing-key-store", dest="android_signing_key_store", - help="path to an upload keystore `.jks` file for Android apps", + help="path to an upload keystore `.jks` file for Android apps " + "[env: FLET_ANDROID_SIGNING_KEY_STORE=]", ) parser.add_argument( "--android-signing-key-store-password", dest="android_signing_key_store_password", - help="Android signing store password", + help="Android signing store password " + "[env: FLET_ANDROID_SIGNING_KEY_STORE_PASSWORD=]", ) parser.add_argument( "--android-signing-key-password", dest="android_signing_key_password", - help="Android signing key password", + help="Android signing key password " + "[env: FLET_ANDROID_SIGNING_KEY_PASSWORD=]", ) parser.add_argument( "--android-signing-key-alias", dest="android_signing_key_alias", default="upload", - help="Android signing key alias", + help="Android signing key alias [env: FLET_ANDROID_SIGNING_KEY_ALIAS=]", ) parser.add_argument( "--build-number", @@ -1840,9 +1843,16 @@ def _run_flutter_command(self): if android_signing_key_alias: build_env["FLET_ANDROID_SIGNING_KEY_ALIAS"] = android_signing_key_alias - if self.options.flutter_build_args: - for flutter_build_arg_arr in self.options.flutter_build_args: - build_args.extend(flutter_build_arg_arr) + flutter_build_args = ( + self.options.flutter_build_args + or self.get_pyproject( + f"tool.flet.{self.config_platform}.flutter.build_args" + ) + or self.get_pyproject("tool.flet.flutter.build_args") + ) + if flutter_build_args: + for arg in self.options.flutter_build_args: + build_args.extend(arg) if self.verbose > 1: build_args.append("--verbose") diff --git a/sdk/python/packages/flet/docs/publish/index.md b/sdk/python/packages/flet/docs/publish/index.md index f38632b27..d3a1a731b 100644 --- a/sdk/python/packages/flet/docs/publish/index.md +++ b/sdk/python/packages/flet/docs/publish/index.md @@ -210,6 +210,7 @@ Throughout this documentation, the following placeholders are used: - `` - one of the following: `android`, `ios`, `web`, `macos`, `windows`, `linux`. - `` - the path to the directory containing your Flet project/app. - [``](../cli/flet-build.md#python_app_path) +- `` - the version of Flet in use. Can be known by running `flet --version` or `uv run python -c "import flet; print(flet.__version__)"` in the terminal. /// ### Product name @@ -323,7 +324,7 @@ Its value is determined in the following order of precedence: 1. `--org` 2. `[tool.flet.].org` 3. `[tool.flet].org` -4. Default: `"com.flet"` +4. `"com.flet"` #### Example @@ -349,6 +350,7 @@ Its value is determined in the following order of precedence: 1. `--company` 2. `[tool.flet].company` +3. `"Your Company"` #### Example @@ -491,6 +493,7 @@ Its value is determined in the following order of precedence: 1. `--copyright` 2. `[tool.flet].copyright` +3. `"Copyright (c) 2023 Your Company"` #### Example @@ -886,7 +889,15 @@ Valid values include: - A full Git URL (e.g., `https://github.com/org/template.git`) - A local directory path -Its value can be set in either of the following ways: +#### Resolution order + +Its value is determined in the following order of precedence: + +1. `--template` (can be used multiple times) +2. `[tool.flet.template].url` +3. [`"gh:flet-dev/flet-build-template"`](https://github.com/flet-dev/flet-build-template) + +#### Example /// tab | `flet build` ```bash @@ -905,7 +916,15 @@ url = "gh:flet-dev/flet-build-template" Defines the branch, tag, or commit to check out from the [template source](#template-source). Defaults to the version of Flet installed. -Its value can be set in either of the following ways: +#### Resolution order + +Its value is determined in the following order of precedence: + +1. `--template-ref` (can be used multiple times) +2. `[tool.flet.template].ref` +3. `` + +#### Example /// tab | `flet build` ```bash @@ -925,7 +944,15 @@ Defines the relative path to the cookiecutter template. If [template source](#template-source) is set, the path is treated as a subdirectory within its root; otherwise, it is relative to`/.cookiecutters/flet-build-template`. -Its value can be set in either of the following ways: +#### Resolution order + +Its value is determined in the following order of precedence: + +1. `--template-dir` (can be used multiple times) +2. `[tool.flet.template].dir` +3. root of the [template source](#template-source) + +#### Example /// tab | `flet build` ```bash @@ -999,36 +1026,94 @@ path = "/path/to/LOCAL_PACKAGE" ### Additional `flutter build` Arguments During the `flet build` process, `flutter build` command gets called internally to -package your app for the specified platform. Not all `flutter build` arguments are exposed or usable throgh `flet build` command. +package your app for the specified platform. However, not all `flutter build` +arguments are exposed or usable through the `flet build` command directly. -Passing additional arguments to `flutter build` can be done as follows: +For possible `flutter build` arguments, see [Flutter docs](https://docs.flutter.dev/deployment) +guide, or run `flutter build --help`. -/// tab | `flet build` -```bash -flet build --flutter-build-args=--no-tree-shake-icons # (1)! +/// admonition | Note +Passing additional `flutter build` arguments might cause unexpected behavior. +Use at your own risk, and only if you fully know what you're doing! +/// -# or as key-value +#### Resolution order -flet build --flutter-build-args=--export-method --flutter-build-args=development -``` +Its value is determined in the following order of precedence: + +1. `--flutter-build-args` (can be used multiple times) +2. `[tool.flet..flutter].build_args` +3. `[tool.flet.flutter].build_args` -1. `--flutter-build-args` can be used multiple times. +#### Example + +/// tab | `flet build` +```bash +flet build apk \ + --flutter-build-args=--obfuscate \ + --flutter-build-args=--export-method=development + --flutter-build-args=--dart-define=API_URL=https://api.example.com +``` /// /// tab | `pyproject.toml` ```toml -[tool.flet.flutter] +[tool.flet.flutter] # or [tool.flet..flutter] build_args = [ - "--no-tree-shake-icons", - "--export-method", "development" + "--obfuscate", + "--export-method=development", + "--dart-define=API_URL=https://api.example.com", ] ``` /// +### Target Architecture + +By default, Flet packages your app for all supported +CPU architectures for the target platform. It is, however, +possible to limit the build to one or more specific architecture(s). + + + +#### Supported architectures + +The following architectures are supported for each platform: + +- Android: `arm64-v8a`, `armeabi-v7a`, `x86_64`, `x86` +- macOS: `arm64`, `x86_64` + +- [//]: # (- iOS: `iphoneos.arm64`, `iphonesimulator.arm64`, `iphonesimulator.x86_64`) + +#### Resolution order + +Its value is determined in the following order of precedence: + +1. `--arch` +2. `[tool.flet.].target_arch`, where `` can be `android` or `ios` +3. `[tool.flet].target_arch` +4. All supported architectures for the `` + +#### Example + +/// tab | `flet build` +```bash +flet build macos --arch arm64 x86_64 +``` +/// +/// tab | `pyproject.toml` +```toml +[tool.flet.macos] # or [tool.flet].target_arch +target_arch = ["arm64", "x86_64"] +``` +/// + ### Verbose logging -The `-v` (or `--verbose`) and `-vv` flags enables detailed output from all commands during the flet build process. -Use `-v` for standard/basic verbose logging, or `-vv` for even more detailed output (higher verbosity level). -If you need support, we may ask you to share this verbose log. +The [`-v`](../cli/flet-build.md/#-verbose) (or `--verbose`) and `-vv` flags +enables detailed output from all commands during the flet build process. + +Use `-v` for standard/basic verbose logging, or `-vv` for even more detailed +output (higher verbosity level). If you need support, +we may ask you to share this verbose log. ## Console output From 5ea32e7957693daa95b36fb92813ab1289f5c5b3 Mon Sep 17 00:00:00 2001 From: ndonkoHenri Date: Sun, 25 Jan 2026 23:19:30 +0100 Subject: [PATCH 07/43] improve publish docs --- .../packages/flet/docs/publish/android.md | 124 +++++------- .../packages/flet/docs/publish/index.md | 188 ++++++++++++------ .../docs/publish/web/static-website/index.md | 128 ++++++------ 3 files changed, 240 insertions(+), 200 deletions(-) diff --git a/sdk/python/packages/flet/docs/publish/android.md b/sdk/python/packages/flet/docs/publish/android.md index b276a1b1f..985c1bdf2 100644 --- a/sdk/python/packages/flet/docs/publish/android.md +++ b/sdk/python/packages/flet/docs/publish/android.md @@ -30,7 +30,7 @@ written in C, Rust or other languages producing native code. Example packages ar Make sure all non-pure (binary) packages used in your Flet app have [pre-built wheels for Android](../reference/binary-packages-android-ios.md). -## `flet build apk` +## `flet build apk` /// admonition | Note This command can be run on a **macOS**, **Linux**, or **Windows**. @@ -53,31 +53,50 @@ Each combination of CPU and instruction set has its own [Application Binary Inte By default, Flet will build a "fat" APK which includes binaries for both [`arm64-v8a`](https://developer.android.com/ndk/guides/abis#arm64-v8a) and -[`armeabi-v7a`](https://developer.android.com/ndk/guides/abis#v7a) architectures. +[`armeabi-v7a`](https://developer.android.com/ndk/guides/abis#v7a) architectures. This can be useful when +deploying to a wide range of devices, but it can also result in a large APK file. -You can split fat APK into smaller APKs for each platform as follows: +Splitting the APK allows you to build separate APKs for each target architecture. +The resulting APKs will be individually smaller. -/// tab | `pyproject.toml` +When targeting specific architectures, make sure to distribute the correct +resulting executable/bundle to users based on their device's CPU architecture, +as installing an incompatible one will result in errors. -/// tab | `[tool.flet.android]` -```toml -[tool.flet.android] -split_per_abi = true -``` -/// +The following target architectures are supported: + +- [`arm64-v8a`](https://developer.android.com/ndk/guides/abis#v7a) +- [`armeabi-v7a`](https://developer.android.com/ndk/guides/abis#v7a) +- [`x86_64`](https://developer.android.com/ndk/guides/abis#86-64) +- [`x86`](https://developer.android.com/ndk/guides/abis#x86) + +#### Resolution order + +Its value is determined in the following order of precedence: + +1. `--split-per-abi` +2. `[tool.flet.android].split_per_abi` +3. `false` + +When enabled, it will, by default, produce the following ABIs: +[`arm64-v8a`](https://developer.android.com/ndk/guides/abis#v7a), +[`armeabi-v7a`](https://developer.android.com/ndk/guides/abis#v7a) and +[`x86_64`](https://developer.android.com/ndk/guides/abis#86-64). +More information on how to customize the target architecture(s) can be +found [here](index.md#target-architecture). + +#### Example -/// /// tab | `flet build` ```bash flet build apk --split-per-abi ``` /// - -/// admonition | Note - type: caution -Splitting APKs per ABI will generate multiple APK files, each targeting a specific architecture. -Make sure to distribute the correct APK to users based on their device's CPU architecture, -as installing an incompatible APK will result in installation failure. +/// tab | `pyproject.toml` +```toml +[tool.flet.android] +split_per_abi = true +``` /// ### Installing APK to a device @@ -94,14 +113,14 @@ more information about installing and using `adb` on various platforms. To install an APK to a device run the following command: -``` +```bash adb install ``` If more than one device is connected to your computer (say, emulator and a physical phone) you can use `-s` option to specify which device you want to install `.apk` on: -``` +```bash adb -s install ``` @@ -195,23 +214,13 @@ flet build aab --android-signing-key-alias value ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet.android]` -```toml -[tool.flet.android] -signing.key_alias = "value" -``` -/// -/// tab | `[tool.flet.android.signing]` ```toml [tool.flet.android.signing] key_alias = "value" ``` /// - -/// -/// tab | Environment Variable -```bash +/// tab | `.env` +```dotenv FLET_ANDROID_SIGNING_KEY_ALIAS="value" ``` /// @@ -229,22 +238,12 @@ flet build aab --android-signing-key-store path/to/store.jks ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet.android]` -```toml -[tool.flet.android] -signing.key_store = "path/to/store.jks" -``` -/// -/// tab | `[tool.flet.android.signing]` ```toml [tool.flet.android.signing] key_store = "path/to/store.jks" ``` /// -/// - #### Key store password A password to unlock the keystore file (can contain multiple key entries). @@ -303,22 +302,12 @@ flet build apk --no-android-splash ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet]` -```toml -[tool.flet] -splash.android = false -``` -/// -/// tab | `[tool.flet.splash]` ```toml [tool.flet.splash] android = false ``` /// -/// - ## Android Manifest The [Android Manifest](https://developer.android.com/guide/topics/manifest/manifest-intro) describes @@ -348,14 +337,6 @@ flet build apk --android-meta-data name_1=value_1 name_2=value_2 ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet.android]` -```toml -[tool.flet.android] -meta_data."name_1" = value_1 -meta_data."name_2" = value_2 -``` -/// /// tab | `[tool.flet.android.meta_data]` ```toml [tool.flet.android.meta_data] @@ -364,8 +345,6 @@ meta_data."name_2" = value_2 ``` /// -/// - And it will be translated accordingly into this in the `AndroidManifest.xml`: ```xml @@ -393,15 +372,6 @@ flet build apk --android-features name_1=required_1 name_2=required_2 ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet.android]` -```toml -[tool.flet.android] -feature."name_1" = required_1 -feature."name_2" = required_2 -``` -/// -/// tab | `[tool.flet.android.feature]` ```toml [tool.flet.android.meta_data] "name_1" = required_1 @@ -409,8 +379,6 @@ feature."name_2" = required_2 ``` /// -/// - And it will be translated accordingly into this in the `AndroidManifest.xml`: ```xml @@ -431,13 +399,13 @@ Below are default/pre-configured features: Configuring Android permissions and features to be written into `AndroidManifest.xml`: -``` +```bash flet build --android-permissions permission=True|False ... --android-features feature_name=True|False ``` For example: -``` +```bash flet build \ --android-permissions android.permission.READ_EXTERNAL_STORAGE=True \ android.permission.WRITE_EXTERNAL_STORAGE=True \ @@ -450,7 +418,7 @@ Default Android permissions: Default permissions can be disabled with `--android-permissions` option and `False` value, for example: -``` +```bash flet build --android-permissions android.permission.INTERNET=False ``` @@ -474,18 +442,18 @@ Configuring permissions and features in `pyproject.toml` (notice quotes `"` arou To run interactive commands inside simulator or device: -``` +```bash adb shell ``` To overcome "permissions denied" error while trying to browse file system in interactive Android shell: -``` +```bash su ``` To download a file from a device to your local computer: -``` +```bash adb pull ``` diff --git a/sdk/python/packages/flet/docs/publish/index.md b/sdk/python/packages/flet/docs/publish/index.md index d3a1a731b..9570bec98 100644 --- a/sdk/python/packages/flet/docs/publish/index.md +++ b/sdk/python/packages/flet/docs/publish/index.md @@ -70,7 +70,10 @@ order to build a package for specific platform: [Flutter](https://flutter.dev) is required to build Flet apps for any platform. -If the minimum required version of the Flutter SDK is not already available in the system `PATH`, it will be automatically downloaded and installed (in the `$HOME/flutter/{version}` directory) during the first build process. +If the minimum required version of the Flutter SDK is not already +available in the system `PATH`, it will be automatically downloaded +and installed (in the `$HOME/flutter/{version}` directory) during +the first build process. @@ -176,6 +179,16 @@ When you run `flet build `, the following steps are performed ( ## Configuration options +/// admonition | Placeholders +Throughout this documentation, the following placeholders are used: + +- [``](../cli/flet-build.md#target_platform) - one of the following: `apk`, `aab`, `ipa`, `web`, `macos`, `windows`, `linux`. +- `` - one of the following: `android`, `ios`, `web`, `macos`, `windows`, `linux`. +- `` - the path to the directory containing your Flet project/app. +- [``](../cli/flet-build.md#python_app_path) +- `` - the version of Flet in use. Can be known by running `flet --version` or `uv run python -c "import flet; print(flet.__version__)"` in the terminal. +/// + /// admonition | Understanding `pyproject.toml` structure Flet loads `pyproject.toml` as a nested dictionary and looks up settings by dot-separated paths (for example, `tool.flet.web.base_url`). @@ -203,16 +216,6 @@ below ("quoted keys" are literals and do not create nesting): ``` /// -/// admonition | Placeholders -Throughout this documentation, the following placeholders are used: - -- [``](../cli/flet-build.md#target_platform) - one of the following: `apk`, `aab`, `ipa`, `web`, `macos`, `windows`, `linux`. -- `` - one of the following: `android`, `ios`, `web`, `macos`, `windows`, `linux`. -- `` - the path to the directory containing your Flet project/app. -- [``](../cli/flet-build.md#python_app_path) -- `` - the version of Flet in use. Can be known by running `flet --version` or `uv run python -c "import flet; print(flet.__version__)"` in the terminal. -/// - ### Product name The display (user-facing) name shown in window titles, launcher labels, and about dialogs. @@ -224,9 +227,9 @@ name. Use the [artifact name](#artifact-name) for artifact naming. Its value is determined in the following order of precedence: -1. `--product` +1. [`--product`](../cli/flet-build.md#-product) 2. `[tool.flet].product` -3. `--project` +3. [`--project`](../cli/flet-build.md#-project) 4. `[project].name` 5. project/app directory name @@ -257,9 +260,9 @@ It can contain spaces or accents. Its value is determined in the following order of precedence: -1. `--artifact` +1. [`--artifact`](../cli/flet-build.md#-artifact) 2. `[tool.flet].artifact` -3. `--project` +3. [`--project`](../cli/flet-build.md#-project) 4. `[project].name` 5. project/app directory name @@ -289,7 +292,7 @@ Its value is internally slugified and hyphens become underscores Its value is determined in the following order of precedence: -1. `--project` +1. [`--project`](../cli/flet-build.md#-project) 2. `[project].name` 3. project/app directory name @@ -321,7 +324,7 @@ the organization name becomes `com.mycompany`. Its value is determined in the following order of precedence: -1. `--org` +1. [`--org`](../cli/flet-build.md#-org) 2. `[tool.flet.].org` 3. `[tool.flet].org` 4. `"com.flet"` @@ -348,7 +351,7 @@ The company name displayed in about app dialogs and metadata. Its value is determined in the following order of precedence: -1. `--company` +1. [`--company`](../cli/flet-build.md#-company) 2. `[tool.flet].company` 3. `"Your Company"` @@ -377,7 +380,7 @@ and the [project name](#project-name). Its value is determined in the following order of precedence: -1. `--bundle-id` +1. [`--bundle-id`](../cli/flet-build.md#-bundle-id) 2. `[tool.flet.].bundle_id` 3. `[tool.flet].bundle_id` 4. Default: `"[organization-name].[project-name]"` @@ -439,7 +442,7 @@ Each new build must have a unique, incrementing number; higher numbers indicate Its value is determined in the following order of precedence: -1. `--build-number` +1. [`--build-number`](../cli/flet-build.md#-build-number) 2. `[tool.flet].build_number` ##### Example @@ -491,7 +494,7 @@ Copyright text displayed in about app dialogs and metadata. Its value is determined in the following order of precedence: -1. `--copyright` +1. [`--copyright`](../cli/flet-build.md#-copyright) 2. `[tool.flet].copyright` 3. `"Copyright (c) 2023 Your Company"` @@ -532,8 +535,8 @@ For the iOS platform, transparency (alpha channel) will be automatically removed A splash screen is a visual element displayed when an app is launching, typically showing a logo or image while the app loads. -You can customize splash screens for iOS, Android, and Web platforms by placing image files in -the `assets` directory of your Flet app. +You can customize splash screens for iOS, Android, and Web platforms by +placing image files in the `assets` directory of your Flet app. If platform-specific splash images are not provided, Flet will fall back to `splash.png`. If that is also missing, it will use `icon.png` or any supported format such as `.bmp`, `.jpg`, or `.webp`. @@ -557,7 +560,7 @@ You can customize splash background colors using the following options: Their values are respectively determined in the following order of precedence: -1. `--splash-color` / `--splash-dark-color` +1. [`--splash-color`](../cli/flet-build.md#-splash-color) / [`--splash-dark-color`](../cli/flet-build.md#-splash-dark-color) 2. `[tool.flet..splash].color` / `[tool.flet..splash].dark_color` 3. `[tool.flet.splash].color` / `[tool.flet.splash].dark_color` 4. `#ffffff` / `#333333` @@ -647,7 +650,7 @@ If provided without the Python file extension (`.py`), it will be appended inter Its value is determined in the following order of precedence: -1. `--module-name` +1. [`--module-name`](../cli/flet-build.md#-module-name) 2. `[tool.flet.app].module` 3. `"main.py"` @@ -665,18 +668,54 @@ module = "app.py" ``` /// +### App dependencies + +These are the Python packages that your Flet app depends on to function correctly. + +#### Resolution order + +Its value is determined in the following order of precedence: + +- `[project].dependencies` (PEP 621) or `[tool.poetry].dependencies` +- If `[tool.flet.].dependencies` is set, its values are appended to the above list. +- If the result of all above is empty and `requirements.txt` exists in ``, it is used. +- If the result of all the above is empty, `flet==` is used. + +#### Example + +/// tab | `pyproject.toml` +```toml +[project] +dependencies = [ + "flet", + "requests", +] + +[tool.flet.] +dependencies = [ + "dep1", + "dep2", +] +``` +/// + ### Source packages If one or more of your app dependencies do not provide a pre-built binary distribution (wheels), they must be built from source distribution and packaged as `.whl` files. -A source distribution is a source archive (usually .tar.gz or .zip) that contains: -the package's Python source code, package metadata, and instructions on how to build and install the package. + +A source distribution is a source archive (usually `.tar.gz` or `.zip`) that contains: +the package's Python source code, package metadata, and instructions on how to build +and install the package. + +To know which packages require source distributions, you can run `pipdeptree` and look for +packages with a `No binaries` column. #### Resolution order Its value is determined in the following order of precedence: -1. `--source-packages` +1. [`--source-packages`](../cli/flet-build.md#-source-packages) 2. `[tool.flet.].source_packages` 3. `[tool.flet].source_packages` 4. `SERIOUS_PYTHON_ALLOW_SOURCE_DISTRIBUTIONS` (environment variable; comma-separated packages) @@ -708,7 +747,7 @@ The directory where the build output is saved. Its value is determined in the following order of precedence: -1. `--output` or `-o` +1. [`--output`](../cli/flet-build.md#-output) (or `-o`) 2. `[tool.flet].output` 3. `/build/` @@ -750,21 +789,21 @@ which can be useful for debugging or rapid iteration. The values of `compile-app` and `cleanup-app` are respectively determined in the following order of precedence: -1. `--compile-app` / `--cleanup-app` +1. [`--compile-app`](../cli/flet-build.md#-compile-app) / [`--cleanup-app`](../cli/flet-build.md#-cleanup-app) 2. `[tool.flet..compile].app` / `[tool.flet..cleanup].app` 3. `[tool.flet.compile].app` / `[tool.flet.cleanup].app` 4. `False` / `False` The values of `compile-packages` and `cleanup-packages` are respectively determined in the following order of precedence: -1. `--compile-packages` / `--cleanup-packages` +1. [`--compile-packages`](../cli/flet-build.md#-compile-packages) / [`--cleanup-packages`](../cli/flet-build.md#-cleanup-packages) 2. `[tool.flet..compile].packages` / `[tool.flet..cleanup].packages` 3. `[tool.flet.compile].packages` / `[tool.flet.cleanup].packages` 4. `False` / `True` The values of `cleanup-app-files` and `cleanup-packages-files` are respectively determined in the following order of precedence: -1. `--cleanup-app-files` / `--cleanup-package-files` +1. [`--cleanup-app-files`](../cli/flet-build.md#-cleanup-app-files) / [`--cleanup-package-files`](../cli/flet-build.md#-cleanup-package-files) 2. `[tool.flet..cleanup].app_files` / `[tool.flet..cleanup].package_files` 3. `[tool.flet.cleanup].app_files` / `[tool.flet.cleanup].package_files` 4. `False` / `False` @@ -873,17 +912,17 @@ Supported permissions: By default, `flet build` creates a temporary Flutter project using a [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) template from the flet-dev/flet-build-template -repository. The version of the template used is determined by the [template reference](#template-reference) option, -which defaults to the current Flet version. +repository. The version of the template used is determined by the [template reference](#template-reference) +option, which defaults to the current Flet version. -You can customize this behavior by specifying your own template source, reference, and subdirectory. +You can customize this behavior by specifying your own template +source, reference, and subdirectory. #### Template Source -Defines the location of the template to be used. Defaults to `gh:flet-dev/flet-build-template`, -the [official Flet template](https://github.com/flet-dev/flet-build-template). +Defines the location of the cookiecutter build-template to be used. -Valid values include: +Supported values include: - A GitHub repository using the `gh:` prefix (e.g., `gh:org/template`) - A full Git URL (e.g., `https://github.com/org/template.git`) @@ -893,7 +932,7 @@ Valid values include: Its value is determined in the following order of precedence: -1. `--template` (can be used multiple times) +1. [`--template`](../cli/flet-build.md#-template) (can be used multiple times) 2. `[tool.flet.template].url` 3. [`"gh:flet-dev/flet-build-template"`](https://github.com/flet-dev/flet-build-template) @@ -914,15 +953,14 @@ url = "gh:flet-dev/flet-build-template" #### Template Reference Defines the branch, tag, or commit to check out from the [template source](#template-source). -Defaults to the version of Flet installed. #### Resolution order Its value is determined in the following order of precedence: -1. `--template-ref` (can be used multiple times) +1. [`--template-ref`](../cli/flet-build.md#-template-ref) (can be used multiple times) 2. `[tool.flet.template].ref` -3. `` +3. [``](#configuration-options) #### Example @@ -942,13 +980,14 @@ ref = "main" Defines the relative path to the cookiecutter template. If [template source](#template-source) is set, the path is treated as a -subdirectory within its root; otherwise, it is relative to`/.cookiecutters/flet-build-template`. +subdirectory within its root; otherwise, it is relative to +`/.cookiecutters/flet-build-template`. #### Resolution order Its value is determined in the following order of precedence: -1. `--template-dir` (can be used multiple times) +1. [`--template-dir`](../cli/flet-build.md#-template-dir) (can be used multiple times) 2. `[tool.flet.template].dir` 3. root of the [template source](#template-source) @@ -983,7 +1022,7 @@ See [this](https://docs.flutter.dev/ui/navigation/deep-linking) guide for more i Its value is determined in the following order of precedence: -1. `--deep-linking-scheme` / `--deep-linking-host` +1. [`--deep-linking-scheme`](../cli/flet-build.md#-deep-linking-scheme) / [`--deep-linking-host`](../cli/flet-build.md#-deep-linking-host) 2. `[tool.flet..deep_linking].scheme` / `[tool.flet..deep_linking].host`, where `` can be android or ios 3. `[tool.flet.deep_linking].scheme` / `[tool.flet.deep_linking].host` @@ -1068,27 +1107,22 @@ build_args = [ ### Target Architecture -By default, Flet packages your app for all supported -CPU architectures for the target platform. It is, however, -possible to limit the build to one or more specific architecture(s). +A target platform can have different CPUs architectures, +which in turn support different instruction sets. +It is possible to build your app for specific CPU architectures. +This is useful for reducing the size of the resulting binary or package, +or for targeting specific devices. - -#### Supported architectures - -The following architectures are supported for each platform: - -- Android: `arm64-v8a`, `armeabi-v7a`, `x86_64`, `x86` -- macOS: `arm64`, `x86_64` - -- [//]: # (- iOS: `iphoneos.arm64`, `iphonesimulator.arm64`, `iphonesimulator.x86_64`) +For more/complementary information on supported architectures, see the specific platform guides: +[Android](android.md#split-apk-per-abi), [macOS](macos.md#target-architecture). #### Resolution order Its value is determined in the following order of precedence: -1. `--arch` -2. `[tool.flet.].target_arch`, where `` can be `android` or `ios` +1. [`--arch`](../cli/flet-build.md#-arch) +2. `[tool.flet.].target_arch`, where `` can be `android` or `macos` 3. `[tool.flet].target_arch` 4. All supported architectures for the `` @@ -1101,11 +1135,45 @@ flet build macos --arch arm64 x86_64 /// /// tab | `pyproject.toml` ```toml -[tool.flet.macos] # or [tool.flet].target_arch +[tool.flet.macos] # or [tool.flet] target_arch = ["arm64", "x86_64"] ``` /// +### Excluding files and directories + +Files and/or directories can be excluded from the build process. +This can be useful for reducing the size of the resulting binary or package. + +#### Resolution order + +Its value is determined in the following order of precedence: + +1. [`--exclude`](../cli/flet-build.md#-exclude) (can be used multiple times) +2. `[tool.flet..app].exclude` (type: list of strings) +3. `[tool.flet.app].exclude` (type: list of strings) + +The files and/or directories specified should be provided as relative +paths to the app root directory, `python_app_path`. + +By default, the `build` directory is always excluded. +Additionally, when the target_platform is web, the `assets` +directory is always excluded. + +#### Example + +/// tab | `flet build` +```bash +flet build --exclude .git .venv +``` +/// +/// tab | `pyproject.toml` +```toml +[tool.flet.app] # or [tool.flet..app] +exclude = [".git", ".venv"] +``` +/// + ### Verbose logging The [`-v`](../cli/flet-build.md/#-verbose) (or `--verbose`) and `-vv` flags diff --git a/sdk/python/packages/flet/docs/publish/web/static-website/index.md b/sdk/python/packages/flet/docs/publish/web/static-website/index.md index b19a85b31..1b48b1991 100644 --- a/sdk/python/packages/flet/docs/publish/web/static-website/index.md +++ b/sdk/python/packages/flet/docs/publish/web/static-website/index.md @@ -3,13 +3,14 @@ Instructions for publishing Flet app into a standalone static website (SPA) that Pyodide is a port of CPython to WebAssembly (WASM) which is an emerging technology with [some limitations](https://pyodide.org/en/stable/usage/wasm-constraints.html). -::note Native Python packages +/// admonition | Native Python packages + type: caution Native Python packages (vs "pure" Python packages written in Python only) are packages that partially written in C, Rust or other languages producing native code. Example packages are `numpy`, `cryptography`, `lxml`, `pydantic`. -Pyodide comes with a big list of [built-in packages](https://pyodide.org/en/stable/usage/packages-in-pyodide.html). However, to use a Python package from PyPI it must be a +Pyodide comes with a long list of [built-in packages](https://pyodide.org/en/stable/usage/packages-in-pyodide.html). However, to use a Python package from PyPI it must be a pure Python package or provide a wheel with binaries [built for Emscripten](https://pyodide.org/en/stable/development/new-packages.html). -:: +/// ### Async and threading @@ -19,7 +20,7 @@ and all sync and async control event handlers are running in the same thread. If (e.g. calculating Fibonacci 😀) or "sleeps" to make UI prettier it may "hang" UI. Consider moving that logic to a server and calling it via web API. Using `asyncio.sleep` in async methods is OK though. -## `flet build web` +## `flet build web` Publish Flet app as a static website. @@ -27,23 +28,14 @@ This is the recommended publishing method for static website. ### Prerequisites -Flutter SDK [must be installed](../../../publish/index.md#flutter-sdk) on your computer for `flet build web` command to work. - -### Building website - -To publish Flet app as a static website run the following command from the root of your Flet app: - -``` -flet build web -``` - -A static website is published into `./build/web` directory. +Flutter SDK [must be installed](../../../publish/index.md#flutter-sdk) on your +computer for `flet build web` command to work. ### Testing website You can test a published Flet app using [`flet serve`](../../../cli/flet-serve.md) command: -``` +```bash flet serve ``` @@ -51,38 +43,44 @@ Open `http://localhost:8000` in your browser to check the published app. ### Packaging assets -Once the website is published all files from `assets` directory will be copied "as is" to the root of the website. +Once the website is published all files from `assets` directory will be +copied "as is" to the root of the website. -This allows overriding such things as `favicon.png` or ` manifest.json` with your own content. +This allows overriding such things as `favicon.png` or ` manifest.json` +with your own content. ### URL strategy Flet apps support two ways of configuring URL-based routing: -* **path** (default) - paths are read and written without a hash. For example, `fletapp.dev/path/to/view`. -* **hash** - paths are read and written to the [hash fragment](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax). For example, `fletapp.dev/#/path/to/view`. +- **path** (default) - paths are read and written without a hash. For example, `fletapp.dev/path/to/view`. +- **hash** - paths are read and written to the [hash fragment](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax). For example, `fletapp.dev/#/path/to/view`. -If a hosting provider supports [Single-page application (SPA) rendering](https://developers.cloudflare.com/pages/platform/serving-pages/#single-page-application-spa-rendering) you can leave default "path" URL strategy as it gives pretty URLs. +If a hosting provider supports [Single-page application (SPA) rendering](https://developers.cloudflare.com/pages/platform/serving-pages/#single-page-application-spa-rendering) you can +leave default "path" URL strategy as it gives pretty URLs. -However, if a hosting provider (like GitHub Pages) doesn't support SPA mode then you need to publish your app with "hash" URL strategy. +However, if a hosting provider (like GitHub Pages) doesn't support SPA mode, then you +need to publish your app with the "hash" URL strategy. Use `--route-url-strategy` argument to change URL strategy. ### Web renderer -You can change default "canvaskit" web renderer ([more about renderers here](../../../cookbook/fonts.md) to "html" with `--web-renderer` option: +You can change default "canvaskit" web renderer ([more about renderers here](../../../cookbook/fonts.md) +to "html" with `--web-renderer` option: -``` +```bash flet build web --web-renderer html ``` ### Color emojis -To reduce app size default "CanvasKit" renderer does not use colorful emojis, because the font file with color emojies weights around 8 MB. +To reduce app size default "CanvasKit" renderer does not use colorful emojis, +because the font file with color emojies weights around 8 MB. You can, however, opt-in for color emojis with `--use-color-emoji` flag: -``` +```bash flet build web --use-color-emoji ``` @@ -90,15 +88,18 @@ Alternatively, switch to `html` renderer which uses browser fonts. ### Hosting website in a sub-directory -Multiple Flet apps can be hosted on a single domain - each app in it's own sub-directory. +Multiple Flet apps can be hosted on a single domain +- each app in it's own sub-directory. -To make a published Flet app work in a sub-directory you have to publish it with `--base-url` option: +To make a published Flet app work in a sub-directory +you have to publish it with `--base-url` option: -``` +```bash flet build web --base-url ``` -For example, if app's URL is `https://mywebsite.com/myapp` then it must be published with `--base-url myapp`. +For example, if app's URL is `https://mywebsite.com/myapp` then +it must be published with `--base-url myapp`. ## Disable splash screen @@ -112,23 +113,13 @@ flet build apk --no-android-splash ``` /// /// tab | `pyproject.toml` - -/// tab | `[tool.flet]` -```toml -[tool.flet] -splash.android = false -``` -/// -/// tab | `[tool.flet.splash]` ```toml [tool.flet.splash] android = false ``` /// -/// - -## `flet publish` +## `flet publish` An alternative method to publish Flet app as a static website. @@ -143,7 +134,7 @@ and many others, and installs them from Pyodide package registry. Run the following command to publish Flet app to a standalone website: -``` +```bash flet publish ``` @@ -163,7 +154,7 @@ Command optional arguments: You can test a published Flet app using [`flet serve`](../../../cli/flet-serve.md) command: -``` +```bash flet serve dist ``` @@ -171,14 +162,18 @@ Open `http://localhost:8000` in your browser to check the published app. ### Loading packages -You can load custom packages from PyPI during app start by listing them in `requirements.txt`. `requirements.txt` must be created in the same directory with ``. +You can load custom packages from PyPI during app start by listing them +in `requirements.txt`. `requirements.txt` must be created in the same +directory with ``. -Each line of `requirements.txt` contains a package name followed by an optional version specifier. +Each line of `requirements.txt` contains a package name +followed by an optional version specifier. /// admonition | Micropip type: tip -To install custom packages Pyodide uses [micropip](https://pypi.org/project/micropip/) - a lightweight version of `pip` that works in a browser. +To install custom packages Pyodide uses [micropip](https://pypi.org/project/micropip/) +- a lightweight version of `pip` that works in a browser. You can use [Micropip API](https://micropip.pyodide.org/en/stable/project/api.html) directly in your Flet app: @@ -193,23 +188,27 @@ if sys.platform == "emscripten": # check if run in Pyodide environment #### Pre-release Python packages -You can allow loading pre-release versions of PyPI packages, by adding `--pre` option to `flet publish` command: +You can allow loading pre-release versions of PyPI packages, +by adding `--pre` option to `flet publish` command: -``` +```bash flet publish --pre ``` ### Assets -If your app requires assets (images, fonts, etc.) you can copy them into website directory by using `--assets ` option with `flet publish` command: +If your app requires assets (images, fonts, etc.) you can copy them into website d +irectory by using `--assets ` option with `flet publish` command: -``` +```bash flet publish --assets assets ``` -::caution -If you have `assets` directory in your app's directory and don't specify `--assets` option then the contents of `assets` will be packaged along with a Python application rather than copied to `dist`. -:: +/// admonition | Assets directory +If you have `assets` directory in your app's directory and don't specify +`--assets` option then the contents of `assets` will be packaged along with +a Python application rather than copied to `dist`. +/// ### URL strategy @@ -218,31 +217,35 @@ Flet apps support two ways of configuring URL-based routing: * **Path** (default) - paths are read and written without a hash. For example, `fletapp.dev/path/to/view`. * **Hash** - paths are read and written to the [hash fragment](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax). For example, `fletapp.dev/#/path/to/view`. -If a hosting provider supports [Single-page application (SPA) rendering](https://developers.cloudflare.com/pages/platform/serving-pages/#single-page-application-spa-rendering) you can leave default "path" URL strategy as it gives pretty URLs. +If a hosting provider supports [Single-page application (SPA) rendering](https://developers.cloudflare.com/pages/platform/serving-pages/#single-page-application-spa-rendering) +you can leave default "path" URL strategy as it gives pretty URLs. -However, if a hosting provider (like GitHub Pages) doesn't support SPA mode then you need to publish your app with "hash" URL strategy. +However, if a hosting provider (like GitHub Pages) doesn't support SPA mode +then you need to publish your app with "hash" URL strategy. To specify "hash" URL strategy during static app publishing use `--route-url-strategy` option: -``` +```bash flet publish --route-url-strategy hash ``` ### Web renderer -You can change default "canvaskit" web renderer ([more about renderers here][flet.WebRenderer]) to "html" with `--web-renderer` option: +You can change default "canvaskit" web renderer +([more about renderers here][flet.WebRenderer]) to "html" with `--web-renderer` option: -``` +```bash flet publish --web-renderer html ``` ### Color emojis -To reduce app size default "CanvasKit" renderer does not use colorful emojis, because the font file with color emojies weights around 8 MB. +To reduce app size default "CanvasKit" renderer does not use colorful emojis, +because the font file with color emojies weights around 8 MB. You can, however, opt-in for color emojis with `--use-color-emoji` flag: -``` +```bash flet publish --use-color-emoji ``` @@ -254,8 +257,9 @@ Multiple Flet apps can be hosted on a single domain - each app in it's own sub-d To make a published Flet app work in a sub-directory you have to publish it with `--base-url` option: -``` +```bash flet publish --base-url ``` -For example, if app's URL is `https://mywebsite.com/myapp` then it must be published with `--base-url myapp`. +For example, if app's URL is `https://mywebsite.com/myapp` then it +must be published with `--base-url myapp`. From 98f6e9048bb356f716d862ea94bf5b3c969c1bc7 Mon Sep 17 00:00:00 2001 From: ndonkoHenri Date: Mon, 26 Jan 2026 00:03:35 +0100 Subject: [PATCH 08/43] reorganize --- .../packages/flet/docs/publish/index.md | 740 +++++++++--------- 1 file changed, 370 insertions(+), 370 deletions(-) diff --git a/sdk/python/packages/flet/docs/publish/index.md b/sdk/python/packages/flet/docs/publish/index.md index 9570bec98..068a60100 100644 --- a/sdk/python/packages/flet/docs/publish/index.md +++ b/sdk/python/packages/flet/docs/publish/index.md @@ -216,6 +216,66 @@ below ("quoted keys" are literals and do not create nesting): ``` /// +### Entry point + +This is where the execution of your Flet app begins. It is the Python file that +contains the call to `flet.run()` or `flet.render()`. +If provided without the Python file extension (`.py`), it will be appended internally. + +[//]: # (Also, it must exist in the `package_app_path`.) + +#### Resolution order + +Its value is determined in the following order of precedence: + +1. [`--module-name`](../cli/flet-build.md#-module-name) +2. `[tool.flet.app].module` +3. `"main.py"` + +#### Example + +/// tab | `flet build` +```bash +flet build --module-name app.py +``` +/// +/// tab | `pyproject.toml` +```toml +[tool.flet.app] +module = "app.py" +``` +/// + +### Project name + +The project name in C-style identifier format (lowercase alphanumerics with underscores). +It is used for [bundle IDs](#bundle-id) and other internal identifiers. + +Its value is internally slugified and hyphens become underscores +(e.g., `my-app` becomes `my_app`) to keep identifier names safe. + +#### Resolution order + +Its value is determined in the following order of precedence: + +1. [`--project`](../cli/flet-build.md#-project) +2. `[project].name` +3. project/app directory name + +#### Example + +/// tab | `flet build` +```bash +flet build --project my_app +``` +/// +/// tab | `pyproject.toml` +```toml +[project] +name = "my_app" +``` +/// + ### Product name The display (user-facing) name shown in window titles, launcher labels, and about dialogs. @@ -280,66 +340,66 @@ artifact = "My Awesome App" ``` /// -### Project name +### Organization name -The project name in C-style identifier format (lowercase alphanumerics with underscores). -It is used for [bundle IDs](#bundle-id) and other internal identifiers. +The organization name in reverse domain name notation, typically in the form `com.mycompany`. -Its value is internally slugified and hyphens become underscores -(e.g., `my-app` becomes `my_app`) to keep identifier names safe. +If you do not provide an explicit value for the organization name, +but specify the [bundle ID](#bundle-id), the organization name will be +internally constructed by taking the part of this [bundle ID](#bundle-id) +before the last dot. For example, with a bundle ID of `com.mycompany.myapp`, +the organization name becomes `com.mycompany`. #### Resolution order Its value is determined in the following order of precedence: -1. [`--project`](../cli/flet-build.md#-project) -2. `[project].name` -3. project/app directory name +1. [`--org`](../cli/flet-build.md#-org) +2. `[tool.flet.].org` +3. `[tool.flet].org` +4. `"com.flet"` #### Example /// tab | `flet build` ```bash -flet build --project my_app +flet build --org com.mycompany ``` /// /// tab | `pyproject.toml` ```toml -[project] -name = "my_app" +[tool.flet] # or [tool.flet.] +org = "com.mycompany" ``` /// -### Organization name +### Bundle ID -The organization name in reverse domain name notation, typically in the form `com.mycompany`. +The bundle ID for the application, typically in the form `"com.mycompany.my_app"`. -If you do not provide an explicit value for the organization name, -but specify the [bundle ID](#bundle-id), the organization name will be -internally constructed by taking the part of this [bundle ID](#bundle-id) -before the last dot. For example, with a bundle ID of `com.mycompany.myapp`, -the organization name becomes `com.mycompany`. +If not explicitly specified, it is formed by combining the [organization name](#organization-name) +and the [project name](#project-name). #### Resolution order Its value is determined in the following order of precedence: -1. [`--org`](../cli/flet-build.md#-org) -2. `[tool.flet.].org` -3. `[tool.flet].org` -4. `"com.flet"` +1. [`--bundle-id`](../cli/flet-build.md#-bundle-id) +2. `[tool.flet.].bundle_id` +3. `[tool.flet].bundle_id` +4. Default: `"[organization-name].[project-name]"` #### Example /// tab | `flet build` ```bash -flet build --org com.mycompany +flet build --bundle-id com.mycompany.my_app ``` /// /// tab | `pyproject.toml` ```toml -[tool.flet] # or [tool.flet.] -org = "com.mycompany" +[tool.flet] # or [tool.flet.] +bundle_id = "com.mycompany.my_app" ``` /// @@ -369,68 +429,32 @@ company = "My Company Inc." ``` /// -### Bundle ID - -The bundle ID for the application, typically in the form `"com.mycompany.my_app"`. +### Copyright -If not explicitly specified, it is formed by combining the [organization name](#organization-name) -and the [project name](#project-name). +Copyright text displayed in about app dialogs and metadata. #### Resolution order Its value is determined in the following order of precedence: -1. [`--bundle-id`](../cli/flet-build.md#-bundle-id) -2. `[tool.flet.].bundle_id` -3. `[tool.flet].bundle_id` -4. Default: `"[organization-name].[project-name]"` +1. [`--copyright`](../cli/flet-build.md#-copyright) +2. `[tool.flet].copyright` +3. `"Copyright (c) 2023 Your Company"` #### Example /// tab | `flet build` ```bash -flet build --bundle-id com.mycompany.my_app +flet build --copyright "Copyright © 2026 My Company Inc." ``` /// /// tab | `pyproject.toml` ```toml -[tool.flet] # or [tool.flet.] -bundle_id = "com.mycompany.my_app" -``` -/// - -### Including Extensions - -If your app uses Flet extensions (third-party packages), -they must equally be part of your app's dependencies. - -/// tab | PyPI -```toml -dependencies = [ - "flet-extension", - "flet", -] -``` -/// -/// tab | Git Repo -```toml -dependencies = [ -"flet-extension @ git+https://github.com/account/flet-extension.git", -"flet", -] -``` -/// -/// tab | Local Package -```toml -dependencies = [ -"flet-extension @ file:///path/to/flet-extension", -"flet", -] +[tool.flet] +copyright = "Copyright © 2026 My Company Inc." ``` /// -Example of extensions can be found [here](../extend/built-in-extensions.md). - ### Versioning #### Build Number @@ -486,29 +510,153 @@ version = "1.0.0" ``` /// -### Copyright +### Output directory -Copyright text displayed in about app dialogs and metadata. +The directory where the build output is saved. #### Resolution order Its value is determined in the following order of precedence: -1. [`--copyright`](../cli/flet-build.md#-copyright) -2. `[tool.flet].copyright` -3. `"Copyright (c) 2023 Your Company"` +1. [`--output`](../cli/flet-build.md#-output) (or `-o`) +2. `[tool.flet].output` +3. `/build/` #### Example /// tab | `flet build` ```bash -flet build --copyright "Copyright © 2026 My Company Inc." +flet build --output ``` /// /// tab | `pyproject.toml` ```toml [tool.flet] -copyright = "Copyright © 2026 My Company Inc." +output = "" +``` +/// + +### App dependencies + +These are the Python packages that your Flet app depends on to function correctly. + +#### Resolution order + +Its value is determined in the following order of precedence: + +- `[project].dependencies` (PEP 621) or `[tool.poetry].dependencies` +- If `[tool.flet.].dependencies` is set, its values are appended to the above list. +- If the result of all above is empty and `requirements.txt` exists in ``, it is used. +- If the result of all the above is empty, `flet==` is used. + +#### Example + +/// tab | `pyproject.toml` +```toml +[project] +dependencies = [ + "flet", + "requests", +] + +[tool.flet.] +dependencies = [ + "dep1", + "dep2", +] +``` +/// + +### Source packages + +If one or more of your app dependencies do not provide a pre-built binary distribution (wheels), +they must be built from source distribution and packaged as `.whl` files. + +A source distribution is a source archive (usually `.tar.gz` or `.zip`) that contains: +the package's Python source code, package metadata, and instructions on how to build +and install the package. + +To know which packages require source distributions, you can run `pipdeptree` and look for +packages with a `No binaries` column. + +#### Resolution order + +Its value is determined in the following order of precedence: + +1. [`--source-packages`](../cli/flet-build.md#-source-packages) +2. `[tool.flet.].source_packages` +3. `[tool.flet].source_packages` +4. `SERIOUS_PYTHON_ALLOW_SOURCE_DISTRIBUTIONS` (environment variable; comma-separated packages) + +#### Example + +/// tab | `flet build` +```bash +flet build --source-packages package1 package2 +``` +/// +/// tab | `pyproject.toml` +```toml +[tool.flet] +source_packages = ["package1", "package2"] +``` +/// +/// tab | `.env` +```dotenv +SERIOUS_PYTHON_ALLOW_SOURCE_DISTRIBUTIONS="package1,package2" +``` +/// + +### Including Extensions + +If your app uses Flet extensions (third-party packages), +they must equally be part of your app's dependencies. + +/// tab | PyPI +```toml +dependencies = [ + "flet-extension", + "flet", +] +``` +/// +/// tab | Git Repo +```toml +dependencies = [ +"flet-extension @ git+https://github.com/account/flet-extension.git", +"flet", +] +``` +/// +/// tab | Local Package +```toml +dependencies = [ +"flet-extension @ file:///path/to/flet-extension", +"flet", +] +``` +/// + +Example of extensions can be found [here](../extend/built-in-extensions.md). + +### Flutter dependencies + +Adding a Flutter package can be done in the `pyproject.toml` as follows: + +/// tab | `flet build` +```bash +flet build +``` +/// +/// tab | `pyproject.toml` +```toml +[tool.flet.flutter.dependencies] +package_1 = "x.y.z" + +# or + +[tool.flet.flutter.dependencies.] +path = "/path/to/LOCAL_PACKAGE" ``` /// @@ -633,194 +781,8 @@ See this [code example](../controls/page.md#hidden-app-window-on-startup). /// tab | `pyproject.toml` ```toml -[tool.flet.app] -hide_window_on_start = true -``` -/// - -### Entry point - -This is where the execution of your Flet app begins. It is the Python file that -contains the call to `flet.run()` or `flet.render()`. -If provided without the Python file extension (`.py`), it will be appended internally. - -[//]: # (Also, it must exist in the `package_app_path`.) - -#### Resolution order - -Its value is determined in the following order of precedence: - -1. [`--module-name`](../cli/flet-build.md#-module-name) -2. `[tool.flet.app].module` -3. `"main.py"` - -#### Example - -/// tab | `flet build` -```bash -flet build --module-name app.py -``` -/// -/// tab | `pyproject.toml` -```toml -[tool.flet.app] -module = "app.py" -``` -/// - -### App dependencies - -These are the Python packages that your Flet app depends on to function correctly. - -#### Resolution order - -Its value is determined in the following order of precedence: - -- `[project].dependencies` (PEP 621) or `[tool.poetry].dependencies` -- If `[tool.flet.].dependencies` is set, its values are appended to the above list. -- If the result of all above is empty and `requirements.txt` exists in ``, it is used. -- If the result of all the above is empty, `flet==` is used. - -#### Example - -/// tab | `pyproject.toml` -```toml -[project] -dependencies = [ - "flet", - "requests", -] - -[tool.flet.] -dependencies = [ - "dep1", - "dep2", -] -``` -/// - -### Source packages - -If one or more of your app dependencies do not provide a pre-built binary distribution (wheels), -they must be built from source distribution and packaged as `.whl` files. - -A source distribution is a source archive (usually `.tar.gz` or `.zip`) that contains: -the package's Python source code, package metadata, and instructions on how to build -and install the package. - -To know which packages require source distributions, you can run `pipdeptree` and look for -packages with a `No binaries` column. - -#### Resolution order - -Its value is determined in the following order of precedence: - -1. [`--source-packages`](../cli/flet-build.md#-source-packages) -2. `[tool.flet.].source_packages` -3. `[tool.flet].source_packages` -4. `SERIOUS_PYTHON_ALLOW_SOURCE_DISTRIBUTIONS` (environment variable; comma-separated packages) - -#### Example - -/// tab | `flet build` -```bash -flet build --source-packages package1 package2 -``` -/// -/// tab | `pyproject.toml` -```toml -[tool.flet] -source_packages = ["package1", "package2"] -``` -/// -/// tab | `.env` -```dotenv -SERIOUS_PYTHON_ALLOW_SOURCE_DISTRIBUTIONS="package1,package2" -``` -/// - -### Output directory - -The directory where the build output is saved. - -#### Resolution order - -Its value is determined in the following order of precedence: - -1. [`--output`](../cli/flet-build.md#-output) (or `-o`) -2. `[tool.flet].output` -3. `/build/` - -#### Example - -/// tab | `flet build` -```bash -flet build --output -``` -/// -/// tab | `pyproject.toml` -```toml -[tool.flet] -output = "" -``` -/// - -### Compilation and cleanup - -Flet can compile your app's `.py` files and/or installed packages' `.py` files into -`.pyc` files during the packaging process. Additionally, it can remove/cleanup -unnecessary package files upon successful compilation. - -- Compilation: - * `compile-app`: compile app's `.py` files - * `compile-packages`: compile site/installed packages' `.py` files - -- Cleanup: - * `cleanup-app`: - * `cleanup-app-files`: - * `cleanup-packages-files`: - * `cleanup-packages`: remove unnecessary package files upon successful compilation - -By default, Flet does **not** compile your app files during packaging. -This allows the build process to complete even if there are syntax errors, -which can be useful for debugging or rapid iteration. - -#### Resolution order - -The values of `compile-app` and `cleanup-app` are respectively determined in the following order of precedence: - -1. [`--compile-app`](../cli/flet-build.md#-compile-app) / [`--cleanup-app`](../cli/flet-build.md#-cleanup-app) -2. `[tool.flet..compile].app` / `[tool.flet..cleanup].app` -3. `[tool.flet.compile].app` / `[tool.flet.cleanup].app` -4. `False` / `False` - -The values of `compile-packages` and `cleanup-packages` are respectively determined in the following order of precedence: - -1. [`--compile-packages`](../cli/flet-build.md#-compile-packages) / [`--cleanup-packages`](../cli/flet-build.md#-cleanup-packages) -2. `[tool.flet..compile].packages` / `[tool.flet..cleanup].packages` -3. `[tool.flet.compile].packages` / `[tool.flet.cleanup].packages` -4. `False` / `True` - -The values of `cleanup-app-files` and `cleanup-packages-files` are respectively determined in the following order of precedence: - -1. [`--cleanup-app-files`](../cli/flet-build.md#-cleanup-app-files) / [`--cleanup-package-files`](../cli/flet-build.md#-cleanup-package-files) -2. `[tool.flet..cleanup].app_files` / `[tool.flet..cleanup].package_files` -3. `[tool.flet.cleanup].app_files` / `[tool.flet.cleanup].package_files` -4. `False` / `False` - -#### Example - -/// tab | `flet build` -```bash -flet build --compile-app --compile-packages --cleanup-packages -``` -/// -/// tab | `pyproject.toml` -```toml -[tool.flet.compile] # or [tool.flet..compile] -app = true -packages = true -cleanup = true +[tool.flet.app] +hide_window_on_start = true ``` /// @@ -908,157 +870,166 @@ Supported permissions: * permissions: * `android.permission.READ_MEDIA_VISUAL_USER_SELECTED": True` -### Customizing build template - -By default, `flet build` creates a temporary Flutter project using a -[cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) template from the flet-dev/flet-build-template -repository. The version of the template used is determined by the [template reference](#template-reference) -option, which defaults to the current Flet version. - -You can customize this behavior by specifying your own template -source, reference, and subdirectory. - -#### Template Source +### Deep linking -Defines the location of the cookiecutter build-template to be used. +[Deep linking](https://en.wikipedia.org/wiki/Mobile_deep_linking) allows users to navigate directly to specific content within a mobile app +using a URI (Uniform Resource Identifier). Instead of opening the app's homepage, deep +links direct users to a specific page, feature, or content within the app, enhancing +user experience and engagement. -Supported values include: +- **Scheme**: deep linking URL scheme, e.g. `"https"` or `"myapp"`. +- **Host**: deep linking URL host. -- A GitHub repository using the `gh:` prefix (e.g., `gh:org/template`) -- A full Git URL (e.g., `https://github.com/org/template.git`) -- A local directory path +See [this](https://docs.flutter.dev/ui/navigation/deep-linking) guide for more information. #### Resolution order Its value is determined in the following order of precedence: -1. [`--template`](../cli/flet-build.md#-template) (can be used multiple times) -2. `[tool.flet.template].url` -3. [`"gh:flet-dev/flet-build-template"`](https://github.com/flet-dev/flet-build-template) +1. [`--deep-linking-scheme`](../cli/flet-build.md#-deep-linking-scheme) / [`--deep-linking-host`](../cli/flet-build.md#-deep-linking-host) +2. `[tool.flet..deep_linking].scheme` / `[tool.flet..deep_linking].host`, where `` can be android or ios +3. `[tool.flet.deep_linking].scheme` / `[tool.flet.deep_linking].host` #### Example /// tab | `flet build` ```bash -flet build apk --template gh:flet-dev/flet-build-template +flet build --deep-linking-scheme "https" --deep-linking-host "mydomain.com" ``` /// /// tab | `pyproject.toml` ```toml -[tool.flet.template] -url = "gh:flet-dev/flet-build-template" +[tool.flet.deep_linking] # or [tool.flet..deep_linking] +scheme = "https" +host = "mydomain.com" ``` /// -#### Template Reference +### Target Architecture -Defines the branch, tag, or commit to check out from the [template source](#template-source). +A target platform can have different CPUs architectures, +which in turn support different instruction sets. + +It is possible to build your app for specific CPU architectures. +This is useful for reducing the size of the resulting binary or package, +or for targeting specific devices. + +For more/complementary information on supported architectures, see the specific platform guides: +[Android](android.md#split-apk-per-abi), [macOS](macos.md#target-architecture). #### Resolution order Its value is determined in the following order of precedence: -1. [`--template-ref`](../cli/flet-build.md#-template-ref) (can be used multiple times) -2. `[tool.flet.template].ref` -3. [``](#configuration-options) +1. [`--arch`](../cli/flet-build.md#-arch) +2. `[tool.flet.].target_arch`, where `` can be `android` or `macos` +3. `[tool.flet].target_arch` +4. All supported architectures for the `` #### Example /// tab | `flet build` ```bash -flet build --template-ref main +flet build macos --arch arm64 x86_64 ``` /// /// tab | `pyproject.toml` ```toml -[tool.flet.template] -ref = "main" +[tool.flet.macos] # or [tool.flet] +target_arch = ["arm64", "x86_64"] ``` /// -#### Template Directory +### Excluding files and directories -Defines the relative path to the cookiecutter template. -If [template source](#template-source) is set, the path is treated as a -subdirectory within its root; otherwise, it is relative to -`/.cookiecutters/flet-build-template`. +Files and/or directories can be excluded from the build process. +This can be useful for reducing the size of the resulting binary or package. #### Resolution order Its value is determined in the following order of precedence: -1. [`--template-dir`](../cli/flet-build.md#-template-dir) (can be used multiple times) -2. `[tool.flet.template].dir` -3. root of the [template source](#template-source) +1. [`--exclude`](../cli/flet-build.md#-exclude) (can be used multiple times) +2. `[tool.flet..app].exclude` (type: list of strings) +3. `[tool.flet.app].exclude` (type: list of strings) + +The files and/or directories specified should be provided as relative +paths to the app root directory, `python_app_path`. + +By default, the `build` directory is always excluded. +Additionally, when the target_platform is web, the `assets` +directory is always excluded. #### Example /// tab | `flet build` ```bash -flet build --template gh:org/template --template-dir sub/directory +flet build --exclude .git .venv ``` /// /// tab | `pyproject.toml` ```toml -[tool.flet.template] -url = "gh:org/template" -dir = "sub/directory" +[tool.flet.app] # or [tool.flet..app] +exclude = [".git", ".venv"] ``` /// -### Deep linking +### Compilation and cleanup -[Deep linking](https://en.wikipedia.org/wiki/Mobile_deep_linking) allows users to navigate directly to specific content within a mobile app -using a URI (Uniform Resource Identifier). Instead of opening the app's homepage, deep -links direct users to a specific page, feature, or content within the app, enhancing -user experience and engagement. +Flet can compile your app's `.py` files and/or installed packages' `.py` files into +`.pyc` files during the packaging process. Additionally, it can remove/cleanup +unnecessary package files upon successful compilation. -- **Scheme**: deep linking URL scheme, e.g. `"https"` or `"myapp"`. -- **Host**: deep linking URL host. +- Compilation: + * `compile-app`: compile app's `.py` files + * `compile-packages`: compile site/installed packages' `.py` files -See [this](https://docs.flutter.dev/ui/navigation/deep-linking) guide for more information. +- Cleanup: + * `cleanup-app`: + * `cleanup-app-files`: + * `cleanup-packages-files`: + * `cleanup-packages`: remove unnecessary package files upon successful compilation + +By default, Flet does **not** compile your app files during packaging. +This allows the build process to complete even if there are syntax errors, +which can be useful for debugging or rapid iteration. #### Resolution order -Its value is determined in the following order of precedence: +The values of `compile-app` and `cleanup-app` are respectively determined in the following order of precedence: -1. [`--deep-linking-scheme`](../cli/flet-build.md#-deep-linking-scheme) / [`--deep-linking-host`](../cli/flet-build.md#-deep-linking-host) -2. `[tool.flet..deep_linking].scheme` / `[tool.flet..deep_linking].host`, where `` can be android or ios -3. `[tool.flet.deep_linking].scheme` / `[tool.flet.deep_linking].host` +1. [`--compile-app`](../cli/flet-build.md#-compile-app) / [`--cleanup-app`](../cli/flet-build.md#-cleanup-app) +2. `[tool.flet..compile].app` / `[tool.flet..cleanup].app` +3. `[tool.flet.compile].app` / `[tool.flet.cleanup].app` +4. `False` / `False` -#### Example +The values of `compile-packages` and `cleanup-packages` are respectively determined in the following order of precedence: -/// tab | `flet build` -```bash -flet build --deep-linking-scheme "https" --deep-linking-host "mydomain.com" -``` -/// -/// tab | `pyproject.toml` -```toml -[tool.flet.deep_linking] # or [tool.flet..deep_linking] -scheme = "https" -host = "mydomain.com" -``` -/// +1. [`--compile-packages`](../cli/flet-build.md#-compile-packages) / [`--cleanup-packages`](../cli/flet-build.md#-cleanup-packages) +2. `[tool.flet..compile].packages` / `[tool.flet..cleanup].packages` +3. `[tool.flet.compile].packages` / `[tool.flet.cleanup].packages` +4. `False` / `True` -### Flutter dependencies +The values of `cleanup-app-files` and `cleanup-packages-files` are respectively determined in the following order of precedence: -Adding a Flutter package can be done in the `pyproject.toml` as follows: +1. [`--cleanup-app-files`](../cli/flet-build.md#-cleanup-app-files) / [`--cleanup-package-files`](../cli/flet-build.md#-cleanup-package-files) +2. `[tool.flet..cleanup].app_files` / `[tool.flet..cleanup].package_files` +3. `[tool.flet.cleanup].app_files` / `[tool.flet.cleanup].package_files` +4. `False` / `False` + +#### Example /// tab | `flet build` ```bash -flet build +flet build --compile-app --compile-packages --cleanup-packages ``` /// /// tab | `pyproject.toml` ```toml -[tool.flet.flutter.dependencies] -package_1 = "x.y.z" - -# or - -[tool.flet.flutter.dependencies.] -path = "/path/to/LOCAL_PACKAGE" +[tool.flet.compile] # or [tool.flet..compile] +app = true +packages = true +cleanup = true ``` /// @@ -1105,72 +1076,101 @@ build_args = [ ``` /// -### Target Architecture +### Customizing build template -A target platform can have different CPUs architectures, -which in turn support different instruction sets. +By default, `flet build` creates a temporary Flutter project using a +[cookiecutter](https://cookiecutter.readthedocs.io/en/stable/) template from the flet-dev/flet-build-template +repository. The version of the template used is determined by the [template reference](#template-reference) +option, which defaults to the current Flet version. -It is possible to build your app for specific CPU architectures. -This is useful for reducing the size of the resulting binary or package, -or for targeting specific devices. +You can customize this behavior by specifying your own template +source, reference, and subdirectory. -For more/complementary information on supported architectures, see the specific platform guides: -[Android](android.md#split-apk-per-abi), [macOS](macos.md#target-architecture). +#### Template Source + +Defines the location of the cookiecutter build-template to be used. + +Supported values include: + +- A GitHub repository using the `gh:` prefix (e.g., `gh:org/template`) +- A full Git URL (e.g., `https://github.com/org/template.git`) +- A local directory path #### Resolution order Its value is determined in the following order of precedence: -1. [`--arch`](../cli/flet-build.md#-arch) -2. `[tool.flet.].target_arch`, where `` can be `android` or `macos` -3. `[tool.flet].target_arch` -4. All supported architectures for the `` +1. [`--template`](../cli/flet-build.md#-template) (can be used multiple times) +2. `[tool.flet.template].url` +3. [`"gh:flet-dev/flet-build-template"`](https://github.com/flet-dev/flet-build-template) #### Example /// tab | `flet build` ```bash -flet build macos --arch arm64 x86_64 +flet build apk --template gh:flet-dev/flet-build-template ``` /// /// tab | `pyproject.toml` ```toml -[tool.flet.macos] # or [tool.flet] -target_arch = ["arm64", "x86_64"] +[tool.flet.template] +url = "gh:flet-dev/flet-build-template" ``` /// -### Excluding files and directories +#### Template Reference -Files and/or directories can be excluded from the build process. -This can be useful for reducing the size of the resulting binary or package. +Defines the branch, tag, or commit to check out from the [template source](#template-source). #### Resolution order Its value is determined in the following order of precedence: -1. [`--exclude`](../cli/flet-build.md#-exclude) (can be used multiple times) -2. `[tool.flet..app].exclude` (type: list of strings) -3. `[tool.flet.app].exclude` (type: list of strings) +1. [`--template-ref`](../cli/flet-build.md#-template-ref) (can be used multiple times) +2. `[tool.flet.template].ref` +3. [``](#configuration-options) -The files and/or directories specified should be provided as relative -paths to the app root directory, `python_app_path`. +#### Example -By default, the `build` directory is always excluded. -Additionally, when the target_platform is web, the `assets` -directory is always excluded. +/// tab | `flet build` +```bash +flet build --template-ref main +``` +/// +/// tab | `pyproject.toml` +```toml +[tool.flet.template] +ref = "main" +``` +/// + +#### Template Directory + +Defines the relative path to the cookiecutter template. +If [template source](#template-source) is set, the path is treated as a +subdirectory within its root; otherwise, it is relative to +`/.cookiecutters/flet-build-template`. + +#### Resolution order + +Its value is determined in the following order of precedence: + +1. [`--template-dir`](../cli/flet-build.md#-template-dir) (can be used multiple times) +2. `[tool.flet.template].dir` +3. root of the [template source](#template-source) #### Example /// tab | `flet build` ```bash -flet build --exclude .git .venv +flet build --template gh:org/template --template-dir sub/directory ``` /// /// tab | `pyproject.toml` ```toml -[tool.flet.app] # or [tool.flet..app] -exclude = [".git", ".venv"] +[tool.flet.template] +url = "gh:org/template" +dir = "sub/directory" ``` /// From e10c81de5b0d8173e7e8586bb8f9828bd58a9ef8 Mon Sep 17 00:00:00 2001 From: ndonkoHenri Date: Mon, 26 Jan 2026 00:40:23 +0100 Subject: [PATCH 09/43] improve --- .../packages/flet/docs/publish/index.md | 81 +++++++++++++------ 1 file changed, 58 insertions(+), 23 deletions(-) diff --git a/sdk/python/packages/flet/docs/publish/index.md b/sdk/python/packages/flet/docs/publish/index.md index 068a60100..87b8eac54 100644 --- a/sdk/python/packages/flet/docs/publish/index.md +++ b/sdk/python/packages/flet/docs/publish/index.md @@ -1,14 +1,14 @@ -# Publishing Flet app +# Publishing a Flet app -Flet CLI provides [`flet build`](../cli/flet-build.md) command that allows packaging Flet app into a standalone executable -or install package for distribution. +Flet CLI provides the [`flet build`](../cli/flet-build.md) command to package a +Flet app into a standalone executable or installable package for distribution. ## Prerequisites ### Platform matrix -The following matrix shows which OS you should run `flet build` command on in -order to build a package for specific platform: +Use the following matrix to choose which OS to run `flet build` +on for each target platform: