LwFlutter

Linwood's lightweight Flutter patch distribution.

This repository does not ship a full Flutter SDK. It ships:

• a base Flutter version in flutter.version
• patch files in patches/
• optional prebuilt local-engine artifacts for platforms that need engine patches
• a reusable setup action in action.yml
• local preparation and launcher scripts that do not depend on GitHub Actions

Layout

LwFlutter/
├─ flutter.version
├─ patches/
│  ├─ common/
│  │  └─ *.patch
│  ├─ windows/
│  │  └─ *.patch
│  └─ linux/
│     └─ *.patch
├─ scripts/
│  ├─ lw_flutter.sh
│  ├─ verify_engine_build.sh
│  └─ configure_engine_build.sh
├─ action.yml
└─ .github/workflows/
   ├─ release.yml
   ├─ test-patches.yml
   └─ update-flutter-stable.yml

Patch folders

• patches/common/: patches that should be applied for every platform and usually do not require a local engine artifact.
• patches/windows/: Windows-specific patches. If files exist here, the release workflow can build windows_release_x64 and windows_release_arm64.
• patches/linux/: Linux-specific patches. If files exist here, the release workflow can build linux_release_x64 and linux_release_arm64.

All materialized patch files are applied to the official Flutter checkout in sorted order.

Patch files

You can commit patch files:

patches/windows/0001-my-change.patch

The workflows run scripts/materialize_patches.sh to copy all .patch files into a real patch set before applying or publishing them.

Using LwFlutter locally

The local CI command defaults to the newest matching GitHub Release. It creates a persistent Flutter checkout under .build/, applies the published patch archive, and downloads the published engine without compiling it:

scripts/lw_flutter.sh ci --platform linux --arch x64

Then run Flutter commands through the same launcher so the correct --local-engine-src-path and --local-engine options are always supplied:

scripts/lw_flutter.sh run -- build linux --release
scripts/lw_flutter.sh run -- run --release -d linux

The generated engine configuration is a release engine, so use --release for commands that select a Flutter build mode.

On Windows, run the scripts from Git Bash:

scripts/lw_flutter.sh ci --platform windows --arch x64
scripts/lw_flutter.sh run --platform windows --arch x64 -- build windows --release

To build the engine yourself from the patches in this checkout, select the source explicitly. This needs the normal Flutter engine platform toolchain and substantial free disk space:

scripts/lw_flutter.sh ci \
  --engine-source build \
  --platform linux \
  --arch x64

scripts/lw_flutter.sh build remains an alias for the source-build mode. Use --skip-sync when its engine dependencies are already synchronized.

You can keep either checkout on another volume:

scripts/lw_flutter.sh ci \
  --platform linux \
  --arch x64 \
  --build-root /path/with/more/space/lwflutter

scripts/lw_flutter.sh run \
  --build-root /path/with/more/space/lwflutter \
  --platform linux \
  --arch x64 \
  -- build linux --release

To inspect the paths without running Flutter:

scripts/lw_flutter.sh info --platform linux --arch x64

Testing patches

The Test patches workflow validates all repository scripts, checks out the Flutter version from flutter.version, and applies the complete patch series.

You can run the same locally:

scripts/test_scripts.sh
scripts/test_patches_locally.sh

To check a patch series against an existing checkout without modifying it:

scripts/apply_patches.sh /path/to/flutter patches '' check

Reporting issues

Please only open issues in this repository for problems that are related to the LwFlutter patches or the LwFlutter release/setup infrastructure.

Before opening an issue, test the same project with the matching official Flutter version from flutter.version and without any LwFlutter patches. If the problem also happens on official Flutter, please report it to Flutter or the affected application instead.

Good LwFlutter issues are things like:

• a patch no longer applies to the configured Flutter version
• a LwFlutter release asset is missing or broken
• Butterfly behaves differently with LwFlutter than with the same official Flutter version
• the setup action downloads or applies the wrong patch/engine artifact

Please include the LwFlutter release tag, the Flutter version, the platform, and the result of your official-Flutter comparison.

Creating a release

You can create a tag manually:

git tag v3.35.7-lw.0
git push origin v3.35.7-lw.0

Or run the release workflow manually without entering a tag. It will generate the next tag automatically:

v<flutter.version>-lw.N

The release workflow publishes:

lwflutter-patches.zip
lwflutter-manifest.json
lwflutter-engine-windows_release_x64.7z.001   # compressed volumes, each below 2 GiB
lwflutter-engine-windows_release_x64.7z.002
lwflutter-engine-windows_release_arm64.7z.001
lwflutter-engine-linux_release_x64.7z.001     # only when Linux engine patches are present/requested
lwflutter-engine-linux_release_arm64.7z.001

lwflutter-patches.zip contains materialized .patch files. Engine outputs use maximum LZMA2 compression and are split into 1,900 MiB volumes so each release asset stays below GitHub's 2 GiB per-file limit.

Using from Linwood Butterfly

- name: Setup Flutter
  id: flutter
  uses: LinwoodDev/LwFlutter@main
  with:
    flutter-version-file: pubspec.yaml
    platforms: windows,linux

- name: Build Butterfly
  working-directory: app
  shell: pwsh
  run: |
    flutter pub get
    flutter build windows --release ${{ steps.flutter.outputs.local-engine-args }}

If a matching LwFlutter release exists, patches are applied to official Flutter. The setup action defaults platforms from the current runner OS, so on Windows and Linux runners it will automatically look for the matching local-engine artifact for the runner architecture (x64 or arm64). You can also pass a comma-separated list like windows,linux. Otherwise it falls back to official Flutter behavior.

If you already know the exact LwFlutter release tag, you can use lwflutter-version on its own and omit both flutter-version and flutter-version-file. The action will infer the underlying Flutter version from the tag, for example v3.35.7-lw.1 implies Flutter 3.35.7.

If you use flutter-version-file, the Flutter version in that file must be an exact version, just like subosito/flutter-action.

Building the engine in your workflow

The action defaults to engine-source: release, which downloads a matching prebuilt engine from GitHub Releases. To build the patches bundled with the selected action revision instead, set engine-source: build:

- name: Setup source-built LwFlutter
  id: flutter
  uses: LinwoodDev/LwFlutter@main
  with:
    flutter-version: 3.44.8
    engine-source: build
    engine-cache: true

- name: Build application
  run: flutter build linux --release ${{ steps.flutter.outputs.local-engine-args }}

Source mode supports Linux and Windows and requires the installed Flutter version to equal the action revision's flutter.version. Its engine output is cached by default. On a standard Linux runner dedicated to desktop builds, you can opt into removing unused preinstalled SDKs to create more build space:

with:
  flutter-version: 3.44.8
  engine-source: build
  reclaim-disk-space: true

Disk reclamation removes Android, .NET, GHC, and CodeQL installations, so do not enable it when later steps require those toolchains. A larger or self-hosted runner remains preferable for repeated source engine builds.

Local patch testing

Before opening an issue here, please check whether the problem also happens on the matching official Flutter version.

This repository should only be used for issues caused by LwFlutter patches, LwFlutter releases, the setup action, or the patch build workflows. If the same problem also happens on official Flutter without LwFlutter patches, report it upstream to Flutter instead.

You can test whether the patches still apply locally:

scripts/test_patches_locally.sh

To test against a specific Flutter stable version:

scripts/test_patches_locally.sh --flutter-ref 3.35.7

To reuse an existing Flutter checkout instead of cloning Flutter again:

scripts/test_patches_locally.sh --flutter-root ~/dev/flutter --flutter-ref 3.35.7

Updating to the latest Flutter stable

To update flutter.version to the latest official Flutter stable version:

scripts/update_to_latest_stable.sh

To update and immediately test whether the patches still apply:

scripts/update_to_latest_stable.sh --test

There is also a GitHub Actions workflow, Update Flutter stable, that can open a pull request automatically when a newer Flutter stable release is available.