diff --git a/README.md b/README.md index ace42bc..230e587 100644 --- a/README.md +++ b/README.md @@ -5,282 +5,294 @@ Workspace Automation that supports embedded Flutter development We developed a Python script, `flutter_workspace.py` to automate embedded flutter setup. This script reads a configuration folder of JSON files, or a single JSON configuration file and sets up a Flutter Workspace. -#### Discord Server https://discord.gg/VKcpSHgjGQ +**Discord Server https://discord.gg/VKcpSHgjGQ** -### Minimum requirements +## System Setup -* Ubuntu +### Ubuntu - sudo apt install -y apt-utils python3 +Install required packages: -* Windows - -- Install Visual Studio -- Install CMake -- Install python3 from the Windows Store - enable for cmd.exe +```sh +sudo apt install -y apt-utils python3 +``` --Install the python virtualenv module +### Windows - python3 -m pip install virtualenv +1. **Install Visual Studio** + - Include Desktop development with C++ workload. --Requirements to build `filament-windows/flutter-engine-windows` - - -Enable long path support for git +2. **Install CMake** + - Download from [cmake.org](https://cmake.org/download/). - git config --global core.longpaths true +3. **Install Python 3** + - Use the Windows Store or download from [python.org](https://www.python.org/downloads/windows/). + - Enable Python for `cmd.exe` during installation. - -Enable Developer Mode to allow symlink creation without Admin rights +4. **Install the Python virtualenv module**: - On Windows 10/11, enabling Developer Mode allows non-admin users to create symlinks + ```sh + python3 -m pip install virtualenv + ``` - Go to Settings > Search for developer settings - Turn on Developer Mode - Restart your terminal +5. **Requirements to build `filament-windows/flutter-engine-windows`:** - -Install Windows 10 SDK from Visual Studio installer + - **Enable long path support for git:** - if ARM64 Windows machine copy `C:\Program Files (x86)\Windows Kits\10\Debuggers\arm64` to `C:\Program Files (x86)\Windows Kits\10\Debuggers\arm64` to appease flutter/tools/gen.bat + ```sh + git config --global core.longpaths true + ``` - -Install ninja and add to path after depot_tools + - **Enable Developer Mode to allow symlink creation without Admin rights:** + - Go to *Settings* > search for *Developer settings*. + - Turn on *Developer Mode*. + - Restart your terminal. - -Optional install WinDgb - AKA Wind-Bag - - winget install Microsoft.WinDbg + - **Install Windows 10 SDK** + - Use the Visual Studio Installer to add the Windows 10 SDK. - -Running + - **For ARM64 Windows machines:** + - Copy `C:\Program Files (x86)\Windows Kits\10\Debuggers\arm64` to `C:\Program Files (x86)\Windows Kits\10\Debuggers\arm64` to appease `flutter/tools/gen.bat`. - Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser - .\flutter_workspace.ps1 --enable "filament-windows,flutter-engine-windows" + - **Install ninja and add to PATH after depot_tools.** - -Running setup_env.ps1 + - **Optional: Install WinDbg:** - Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser - .\setup_env.ps1 + ```sh + winget install Microsoft.WinDbg + ``` -### create_aot.py +6. **Running scripts:** -create AOT is used to create libapp.so for use on a device. It requires an active FLUTTER_WORKSPACE. + - **PowerShell:** + Set execution policy and run workspace automation: -Example use: + ```powershell + Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + .\flutter_workspace.ps1 --enable "filament-windows,flutter-engine-windows" + ``` - source ./setup_env.sh - ./create_aot --path + - **Setup environment:** -#### Environmental variables used by script + ```powershell + Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + .\setup_env.ps1 + ``` -* GEN_SNAPSHOT - (Required) Set GEN_SNAPSHOT to location of executable gen_snapshot +## `create_aot.py` -* PUB_CACHE - Set using `source ./setup_env.sh` +The `create_aot.py` script generates a `libapp.so` file for deployment on a device. It requires an active `FLUTTER_WORKSPACE` environment. -* FLUTTER_WORKSPACE - Set using `source ./setup_env.sh` +**Example usage:** -* FLUTTER_BUILD_ARGS - Defaults to 'bundle' +```sh +source ./setup_env.sh +./create_aot --path +``` -* LOCAL_ENGINE_HOST - Defaults to f'{flutter_sdk}/bin/cache/artifacts/engine/common' +**Environment variables used:** -* APP_GEN_SNAPSHOT_FLAGS +- `GEN_SNAPSHOT` (required): Path to the `gen_snapshot` executable. +- `PUB_CACHE`: Set by sourcing `./setup_env.sh`. +- `FLUTTER_WORKSPACE`: Set by sourcing `./setup_env.sh`. +- `FLUTTER_BUILD_ARGS`: Defaults to `bundle`. +- `LOCAL_ENGINE_HOST`: Defaults to `${flutter_sdk}/bin/cache/artifacts/engine/common`. +- `APP_GEN_SNAPSHOT_FLAGS`: Additional flags for `gen_snapshot`. +- `APP_GEN_SNAPSHOT_AOT_FILENAME`: Defaults to `libapp.so.{runtime_mode}`. +- `FLUTTER_PREBUILD_CMD`: Optional pre-build command. -* APP_GEN_SNAPSHOT_AOT_FILENAME - Defaults to 'libapp.so.{runtime_mode}' +--- -* FLUTTER_PREBUILD_CMD +## `flutter_workspace.py` -### flutter_workspace.py +The `flutter_workspace.py` script automates the setup and management of a Flutter workspace for embedded development. -flutter_workspace.py does the following tasks automatically for you +**Key features:** -* Establishes a workspace of known state -* Sync repos into app folder -* .vscode debug launcher file -* Flutter SDK -* Flutter runtime=debug engine -* Loads platform types - * QEMU, Docker, Remote, Host, Generic - * Each type uses a specific configuration -* Create setup_env.sh -* -* Tested on Linux, Mac, and Windows - * Ubuntu 20/22/24 (x86_64, aarch64) - * Fedora 40/41/42 (x86_64) - * macOS 13/14/15 (x86_64, arm64) - Mac M1/M2 - * Windows 10 (AMD64) - * Windows 11 (AMD64, ARM64) - Windows Surface Elite X +- Initializes a workspace in a known state. +- Syncs repositories into the `app` folder. +- Generates a `.vscode` debug launcher file. +- Manages the Flutter SDK and runtime engine. +- Loads platform types (QEMU, Docker, Remote, Host, Generic) with specific configurations. +- Creates `setup_env.sh` for environment setup. +- Tested on Linux, macOS, and Windows (see supported versions below). -#### Environmental Variables +**Supported platforms:** -* PREFER_LLVM - (optional) set the LLVM version to use. If not found, defaults to using `llvm-config`. +- Ubuntu 20/22/24 (x86_64, aarch64) +- Fedora 40/41/42 (x86_64) +- macOS 13/14/15 (x86_64, arm64) - Mac M1/M2 +- Windows 10 (AMD64) +- Windows 11 (AMD64, ARM64) - Windows Surface Elite X -* HARDWARE_THREADS - (optional) set the maximum hardware thread count used in building and fetching. Used for low RAM machines. +**Environment variables:** -### Flutter Workspace +- `PREFER_LLVM` (optional): Specify the LLVM version to use. Defaults to `llvm-config` if not set. +- `HARDWARE_THREADS` (optional): Limit hardware thread usage for building/fetching (useful for low RAM systems). -A Flutter workspace contains +--- -* Flutter SDK - * flutter -* Development Repositories (app) - * app -* Host Runtime images - * .config/flutter_workspace/ -* flutter-auto binary - * app/ivi-homescreen/build -* QEMU image - * .config/flutter_workspace//) -* Versioned x86_64 libflutter_engine.so and icudtl.dat - * ./config/flutter_workspace/flutter-engine -* Custom-device configurations - * ./config/flutter_workspace/ -* Public Cache - * .config/flutter_workspace/pub_cache +## Flutter Workspace Structure +A Flutter workspace typically contains: -### JSON Configuration +- **Flutter SDK** (`flutter`) +- **Development repositories** (`app`) +- **Host runtime images** (`.config/flutter_workspace/`) +- **flutter-auto binary** (`app/ivi-homescreen/build`) +- **QEMU images** (`.config/flutter_workspace//`) +- **Versioned engine files** (`./config/flutter_workspace/flutter-engine`) +- **Custom device configurations** (`./config/flutter_workspace/`) +- **Pub cache** (`.config/flutter_workspace/pub_cache`) -flutter_workspace_config.json contains the following components +--- -* globals - * cookie_file - * netrc - * github_api - * -* repos - * git -* platform definition +## JSON Configuration +The `flutter_workspace_config.json` file includes: -### Platform configuration environmental variables +- **globals**: General settings (e.g., `cookie_file`, `netrc`, `github_api`) +- **repos**: Repository definitions (e.g., `git`) +- **platform**: Platform-specific configuration -* `FLUTTER_WORKSPACE_)_LOAD=[ON,OFF]` - This environmental variable is generated for each platform config. The initial value is determined by the platform config `load` key value. It will be overriden to `OFF` via the `--plex=` command line option. +--- +## Platform Configuration Environment Variables -### Installation +For each platform config, an environment variable is generated: ``` -git clone https://github.com/meta-flutter/workspace_automation.git -./flutter_workspace.py +FLUTTER_WORKSPACE__LOAD=[ON|OFF] ``` -### Options - -#### --clean - -Wipes workspace before creating - -#### --config= - -Pass configuration folder path. - - -#### --flutter-version=x.x.x - -Override config/_globals.json key "flutter_version" - -#### --fetch-engine - -Fetch libflutter_engine.so and update bundle cache - -#### --version-files= - -Pass folder for storing dart and engine json files. - -#### --plex="..." - -Platform Load Exceptions. Pass platform-id values. Select multiple platform ids by seperating with `,`. - -e.g. `--plex=filament,firebase-cpp-sdk` - -This option also has the impact of forcing the environmental variable `FLUTTER_WORKSPACE_)_LOAD=OFF`. This variable can be used reliably in a configuration type other than `dependency`. - -#### --enable="..." - -Enable Platform Configuration(s). Pass platform-id values. Select multiple platform ids by seperating with `,`. +- The initial value is set by the platform config's `load` key. +- Can be overridden with the `--plex=` command-line option. -e.g. `--enable=filament` - -This option also has the impact of forcing the environmental variable `FLUTTER_WORKSPACE_)_LOAD=ON`. This variable can be used reliably in a configuration type other than `dependency`. - -#### --disable="..." - -Alias to --plex. See `--plex` description - - -#### --stdin-file - -Use for debugging - - -### Run flutter app with desktop-auto - -* Login via GDM Wayland Session -* Open Terminal and type -* `source ${FLUTTER_WORKSPACE}/setup_env.sh` -* Navigate to your favorite app -* `flutter run -d desktop-auto` - - -### Run flutter app with QEMU - -* Open Terminal and type -* `source ${FLUTTER_WORKSPACE}/setup_env.sh` -* Type `qemu_run` -* Wait until QEMU image reaches login prompt -* Run `ssh –p 2222 root@localhost who` to add remote host to ~/.ssh/known_hosts -* Navigate to your favorite app -* `flutter run -run-qemu-master` +Example: +```sh +./flutter_workspace.py --enable=filament --disable=rive-text +``` -### Create hello_world flutter example +--- -* Login to Ubuntu desktop via Wayland Session -* Open Terminal and type -* `source ${FLUTTER_WORKSPACE}/setup_env.sh` -* `cd ${FLUTTER_WORKSPACE}/app` -* `flutter create hello_world -t app` -* `cd hello_world` -* `flutter run -d desktop-auto` +## Installation +```sh +git clone https://github.com/meta-flutter/workspace_automation.git +./flutter_workspace.py +``` -### Running `dart_pdf` demo +--- + +## Command-Line Options + +- `--clean`: Wipe workspace before creating. +- `--config=`: Specify configuration folder path. +- `--flutter-version=x.x.x`: Override Flutter version in config. +- `--fetch-engine`: Fetch `libflutter_engine.so` and update bundle cache. +- `--version-files=`: Specify folder for Dart and engine JSON files. +- `--plex="..."`: Platform Load Exceptions. Comma-separated platform IDs (e.g., `--plex=filament,firebase-cpp-sdk`). Forces `FLUTTER_WORKSPACE__LOAD=OFF`. +- `--enable="..."`: Enable platform configurations. Comma-separated platform IDs (e.g., `--enable=filament`). Forces `FLUTTER_WORKSPACE__LOAD=ON`. +- `--disable="..."`: Alias for `--plex`. +- `--stdin-file`: Use for debugging. + +--- + +## Running Flutter Apps + +### On Desktop + +1. Log in via GDM Wayland Session. +2. Open a terminal: + ```sh + source ${FLUTTER_WORKSPACE}/setup_env.sh + ``` +3. Navigate to your app directory. +4. Run: + ```sh + flutter run -d desktop-auto + ``` + +### With QEMU + +1. Open a terminal: + ```sh + source ${FLUTTER_WORKSPACE}/setup_env.sh + qemu_run + ``` +2. Wait for the QEMU image to reach the login prompt. +3. Add the remote host to `~/.ssh/known_hosts`: + ```sh + ssh -p 2222 root@localhost who + ``` +4. Navigate to your app directory and run: + ```sh + flutter run -run-qemu-master + ``` + +--- + +## Creating a Hello World Flutter Example + +1. Log in to Ubuntu desktop via Wayland Session. +2. Open a terminal: + ```sh + source ${FLUTTER_WORKSPACE}/setup_env.sh + cd ${FLUTTER_WORKSPACE}/app + flutter create hello_world -t app + cd hello_world + flutter run -d desktop-auto + ``` + +--- + +## Running the `dart_pdf` Demo + +```sh +./flutter_workspace.py --enable=pdfium +source ./setup_env.sh +export LD_LIBRARY_PATH=${FLUTTER_WORKSPACE}/app/pdfium/pdfium/out/Linux-Release/ +pushd app/dart_pdf/demo +flutter run -d desktop-homescreen +``` - ./flutter_workspace.py --enable=pdfium - source ./setup_env.sh - export LD_LIBRARY_PATH=${FLUTTER_WORKSPACE}/app/pdfium/pdfium/out/Linux-Release/ - pushd app/dart_pdf/demo - flutter run -d desktop-homescreen +--- +## Working with LLVM -### Working with LLVM +### Set the Preferred LLVM Toolchain -#### Set the preferred LLVM toolchain +To specify the LLVM toolchain version: -To change the toolchain version used by flutter_workspace use the `PREFER_LLVM` variable -``` +```sh PREFER_LLVM=10 ./flutter_workspace.py ``` -If the `PREFER_LLVM` key is set it overrides `clang-stable`. +- If `PREFER_LLVM` is set, it overrides `clang-stable`. +- The first matching `llvm-config-` in `/usr` is selected. -If you have multiple instances of the same llvm-config- file present in `/usr`, the first ocurring will be selected. This could be an Android NDK toolchain. +### List Available LLVM Installs -Refer to listing available LLVM installs for debugging toolchain selection problems. - -#### List available LLVM installs -``` +```sh find /usr -type f -executable -name 'llvm-config*' ``` -### Visual Studio Code +--- -#### Launching on Ubuntu +## Visual Studio Code Integration +### Launching on Ubuntu + +```sh +cd +source ./setup_env.sh +code . ``` - cd - source ./setup_env.sh - code . -``` -#### Debugging with VS Code +### Debugging with VS Code + +- `flutter_workspace.py` creates a `.vscode/launch.json` if not present. +- Uses the `pubspec_path` key from repo JSON to add entries to `launch.json`. +- Supports debugging for configured repositories. -`flutter_workspace.py` creates a `.vscode/launch.json` file if one is not present. -It uses the repo json key `pubspec_path`. If this key is present in the repo -json, then it will add entry to `.vscode/launch.json`.