How to run Flutter apps

1. Run with Wayland backend

Wayland compositor such as Weston must be running before running the program.

$ ./flutter-client -b ./sample/build/linux/x64/release/bundle

Tips: path to the bundle of Flutter apps

It is safer to specify the bundle path as an absolute path. Note that if it is a relative path, it will be a relative path from the executable binary. If the path is specified incorrectly, you will get the following error message.

embedder.cc (982): 'FlutterEngineInitialize' returned 'kInvalidArguments'. Not running in AOT mode but could not resolve the kernel binary.
[ERROR][flutter_elinux_engine.cc(249)] Failed to start Flutter engine: error 2

Tips: Debug on Linux desktop hosts

Wayland compositors don't such as the title bar and close button, so Wayland apps need to create it themselves. In this software, Window decorations are shown by using -d option. Note that this feature is just for debugging on Linux hosts. Generally, in embedded systems, window decorations aren't necessary. Therefore, the window decorations are a very simple theme.

$ ./flutter-client -b ./sample/build/linux/x64/release/bundle -d

Command options

./flutter-client has a few options. See the bellow.

• Recommended to enable --async-vblank option to improve FPS if it works fine on your target platform.

Usage: ./build/flutter-client --bundle=<value> 
Global options:
-b, --bundle=<value>               Path to Flutter project bundle
-n, --no-cursor                    No mouse cursor/pointer
-r, --rotation=<value>             Window rotation(degree) [0(default)|90|180|270]
-x, --text-scaling-factor=<value>  Text scaling factor
-s, --force-scale-factor=<value>   Force a scale factor instead using default value
-v, --async-vblank                 Don't sync to compositor redraw/vblank (eglSwapInterval 0)
-t, --title=<value>                Window title
-a, --app-id=<value>               XDG App ID
-k, --onscreen-keyboard            Enable on-screen keyboard
-d, --window-decoration            Enable window decorations
-f, --fullscreen                   Always full-screen display
-w, --width=<value>                Window width
-h, --height=<value>               Window height

Supplement

You can switch quickly between debug / profile / release modes for the Flutter app without replacing libflutter_engine.so by using LD_LIBRARY_PATH when you run the Flutter app.

$ LD_LIBRARY_PATH=<path_to_engine> ./flutter-client --bundle=<path_to_flutter_project_bundle>

# e.g. Run in debug mode
$ LD_LIBRARY_PATH=/usr/lib/flutter_engine/debug/ ./flutter-client --bundle=./sample/build/linux/x64/debug/bundle

# e.g. Run in profile mode
$ LD_LIBRARY_PATH=/usr/lib/flutter_engine/profile/ ./flutter-client --bundle=./sample/build/linux/x64/profile/bundle

# e.g. Run in release mode
$ LD_LIBRARY_PATH=/usr/lib/flutter_engine/release/ ./flutter-client --bundle=./sample/build/linux/x64/release/bundle

2. Run with DRM backend

You need to switch from GUI which is running X11 or Wayland to the Character User Interface (CUI). In addition, FLUTTER_DRM_DEVICE must be set properly. The default value is /dev/dri/card0.

$ Ctrl + Alt + F3 # Switching to CUI
$ sudo FLUTTER_DRM_DEVICE="/dev/dri/card1" <binary_file_name> --bundle=./sample/build/linux/x64/release/bundle

# You can also specify multi dri cards.
# See also: https://github.com/sony/flutter-elinux/issues/143
$ sudo FLUTTER_DRM_DEVICE="/dev/dri/card0:/dev/dri/card1" <binary_file_name> --bundle=./sample/build/linux/x64/release/bundle

If you want to switch back from CUI to GUI, run Ctrl + Alt + F2 keys in a terminal.

FLUTTER_DRM_CONNECTOR environment variable may be helpful for you. See https://github.com/sony/flutter-embedded-linux/issues/424 for the details.

Note

You need to run this program by a user who has the permission to access the input devices(/dev/input/xxx), if you use the DRM backend. Generally, it is a root user or a user who belongs to an input group.

3. Logging levels

The logging levels of the embedder are controlled by FLUTTER_LOG_LEVELS environment var. If you want to do debugging, set FLUTTER_LOG_LEVELS. The default level is WARNING.

$ FLUTTER_LOG_LEVELS=TRACE ./flutter-client --bundle=<path_to_flutter_project_bundle>
$ FLUTTER_LOG_LEVELS=INFO ./flutter-client --bundle=<path_to_flutter_project_bundle>
$ FLUTTER_LOG_LEVELS=WARNING ./flutter-client --bundle=<path_to_flutter_project_bundle>
$ FLUTTER_LOG_LEVELS=ERROR ./flutter-client --bundle=<path_to_flutter_project_bundle>
$ FLUTTER_LOG_LEVELS=FATAL ./flutter-client --bundle=<path_to_flutter_project_bundle>