Skip to content

Manually building an app bundle

Jump to bottom
Hannes Winkler edited this page Apr 5, 2025 · 1 revision

Device Setup

  • Follow the instructions in the flutter-engine-binaries-for-arm repo..

    More Info

    flutter-pi needs flutters icudtl.dat and libflutter_engine.so.{debug,profile,release} at runtime, depending on the runtime mode used. You actually have two options here:

    • you build the engine yourself. takes a lot of time, and it most probably won't work on the first try. But once you have it set up, you have unlimited freedom on which engine version you want to use. You can find some rough guidelines here.
    • you can use the pre-built engine binaries I am providing in the flutter-engine-binaries-for-arm repo.. I will only provide binaries for some engine versions though (most likely the stable ones).

Building the App

  1. Make sure you've installed the flutter SDK. You must use a flutter SDK that's compatible to the installed engine binaries.

    • for the flutter SDK, use flutter stable and keep it up to date.
    • always use the latest available engine binaries

    If you encounter error messages like Invalid kernel binary format version, Invalid SDK hash or Invalid engine hash:

    1. Make sure your flutter SDK is on stable and up to date and your engine binaries are up to date.
    2. If you made sure that's the case and the error still happens, create a new issue.

  2. cd into your app directory and run flutter build bundle

  3. Deploy the asset bundle to the Raspberry Pi using rsync or scp.

    • Using rsync (available on linux and macOS or on Windows when using WSL) 
      rsync -a --info=progress2 ./build/flutter_assets/ pi@raspberrypi:/home/pi/my_apps_flutter_assets
    • Using scp (available on linux, macOS and Windows) 
      scp -r ./build/flutter_assets/ pi@raspberrypi:/home/pi/my_apps_flutter_assets

Example (flutter gallery)

git clone https://github.com/flutter/gallery.git flutter_gallery && cd flutter_gallery
flutter build bundle
rsync -a ./build/flutter_assets/ pi@raspberrypi:/home/pi/flutter_gallery/

Done. You can now run this app in debug-mode using flutter-pi /home/pi/flutter_gallery.

Building the app.so (for running your app in Release/Profile mode)

  • This is done entirely on your development machine as well.
  1. Find out the path to your flutter SDK. For me it's C:\flutter. (I'm on Windows)
  2. Open terminal or commandline and cd into your app directory.
  3. Build the asset bundle. 
    flutter build bundle
  4. Build the kernel snapshot. (Replace my_app_name with the name of your app) 
    C:\flutter\bin\cache\dart-sdk\bin\dart.exe ^
  C:\flutter\bin\cache\dart-sdk\bin\snapshots\frontend_server.dart.snapshot ^
  --sdk-root C:\flutter\bin\cache\artifacts\engine\common\flutter_patched_sdk_product ^
  --target=flutter ^
  --aot ^
  --tfa ^
  -Ddart.vm.product=true ^
  --packages .dart_tool\package_config.json ^
  --output-dill build\kernel_snapshot.dill ^
  --verbose ^
  --depfile build\kernel_snapshot.d ^
  package:my_app_name/main.dart
More information
  • In versions prior to Flutter 3.3.0 the --packages argument should be set to .packages. In versions greater than or equal to 3.3.0 the --packages argument should be set to .dart_tool\package_config.json.
  1. Fetch the latest gen_snapshot_linux_x64_release I provide in the engine binaries repo.
  2. The following steps must be executed on a linux x64 machine. If you're on windows, you can use WSL. If you're on macOS, you can use a linux VM.
  3. Build the app.so. If you're building for arm64, you need to omit the --sim-use-hardfp flag. 
    gen_snapshot_linux_x64_release \
  --deterministic \
  --snapshot_kind=app-aot-elf \
  --elf=build/flutter_assets/app.so \
  --strip \
  --sim-use-hardfp \
  build/kernel_snapshot.dill
  4. Now you can switch to your normal OS again.
  5. Upload the asset bundle and the app.so to your Raspberry Pi. 
    rsync -a --info=progress2 ./build/flutter_assets/ pi@raspberrypi:/home/pi/my_app
    or 
    scp -r ./build/flutter_assets/ pi@raspberrypi:/home/pi/my_app
  6. You can now launch the app in release mode using flutter-pi --release /home/pi/my_app

Complete example on Windows

  1. We'll build the asset bundle for flutter_gallery and deploy it using rsync in this example. 
    git clone https://github.com/flutter/gallery.git flutter_gallery
git clone --depth 1 https://github.com/ardera/flutter-engine-binaries-for-arm.git engine-binaries
cd flutter_gallery
git checkout d77920b4ced4a105ad35659fbe3958800d418fb9
flutter build bundle
C:\flutter\bin\cache\dart-sdk\bin\dart.exe ^
  C:\flutter\bin\cache\dart-sdk\bin\snapshots\frontend_server.dart.snapshot ^
  --sdk-root C:\flutter\bin\cache\artifacts\engine\common\flutter_patched_sdk_product ^
  --target=flutter ^
  --aot ^
  --tfa ^
  -Ddart.vm.product=true ^
  --packages .dart_tool\package_config.json ^
  --output-dill build\kernel_snapshot.dill ^
  --verbose ^
  --depfile build\kernel_snapshot.d ^
  package:gallery/main.dart
wsl
../engine-binaries/arm/gen_snapshot_linux_x64_release \
  --deterministic \
  --snapshot_kind=app-aot-elf \
  --elf=build/flutter_assets/app.so \
  --strip \
  --sim-use-hardfp \
  build/kernel_snapshot.dill
rsync -a --info=progress2 ./build/flutter_assets/ pi@raspberrypi:/home/pi/flutter_gallery/
exit
  2. Done. You can now run this app in release mode using flutter-pi --release /home/pi/flutter_gallery.
Clone this wiki locally