meta-agl-flutter/README.md

   1 # meta-agl-flutter
   2
   3 ## Steps to build `agl-ivi-demo-platform-flutter` image
   4
   5 ```
   6     export AGL_TOP=$HOME/workspace_agl
   7     mkdir -p $AGL_TOP && cd $AGL_TOP
   8     repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -b master
   9     repo sync -j $(nproc)
  10     source meta-agl/scripts/aglsetup.sh -m qemux86-64 agl-demo
  11     bitbake agl-ivi-demo-platform-flutter
  12 ```
  13
  14 This builds AGL demo image that includes Flutter runtime={debug,profile,release}.
  15
  16
  17 ## Steps to build a minimal flutter image
  18
  19 ```
  20     export AGL_TOP=$HOME/workspace_agl
  21     mkdir -p $AGL_TOP && cd $AGL_TOP
  22     repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -b master
  23     repo sync -j `grep -c ^processor /proc/cpuinfo`
  24     source meta-agl/scripts/aglsetup.sh -m qemux86-64 agl-devel agl-flutter
  25     bitbake agl-image-flutter
  26 ```
  27   * includes Flutter engine runtime={debug,release,profile}
  28   * includes Flutter Engine SDK
  29   * includes SSH server
  30   * live debugging/profiling with target via host
  31
  32 ## Useful Notes
  33
  34 flutter-auto runs as user `agl-driver`.  After logging in as root you can delete password for `agl-driver`:
  35 ```
  36 # passwd -d agl-driver
  37 ```
  38
  39 To track flutter-auto output:
  40 ```
  41 # journalctl -ex -u flutter-homescreen -f
  42 ```
  43
  44 To view available Flutter programs in OS image:
  45 ```
  46 ls -la /usr/share/flutter
  47 ```
  48
  49 To change Flutter program that runs on boot edit this file:
  50 ```
  51 # vi /usr/lib/systemd/system/flutter-homescreen.service
  52 ```
  53
  54 To change device to run Gallery on reboot edit flutter-homescreen.service to:
  55 ```
  56 ExecStart=/usr/bin/flutter-auto --b=/usr/share/flutter/gallery/${FLUTTER_VERSION}/${FLUTTER_RUNTIME} --j=/usr/share/flutter/flutter-homescreen.json --xdg-shell-app-id=homescreen
  57 ```
  58 To enable experimental impeller support edit flutter-homescreen.service adding --enable-impeller:
  59 ```
  60 ExecStart=/usr/bin/flutter-auto --b=/usr/share/flutter/gallery/${FLUTTER_VERSION}/${FLUTTER_RUNTIME} --j=/usr/share/flutter/flutter-homescreen.json --xdg-shell-app-id=homescreen --enable-impeller
  61 ```
  62
  63 After edits either run:
  64 ```
  65 # systemctl daemon-reload
  66 # systemctl restart flutter-homescreen
  67 ```
  68 or
  69 ```
  70 # reboot
  71 ```
  72
  73 Collecting a stack trace for flutter-auto
  74 ```
  75 # systemctl stop flutter-auto
  76 # export SPDLOG_LEVEL=trace
  77 # export XDG_RUNTIME_DIR=/run/user/1001/
  78 # gdb --args flutter-auto --b=/usr/share/flutter/gallery/<flutter version>/release/ --j=/usr/share/flutter/flutter-homescreen.json --xdg-shell-app-id=homescreen
  79 ```
  80
  81 ## Flutter Engine SDK
  82
  83 If recipe `flutter-engine-sdk-dev` is included in your AGL image, `engine_sdk.zip` will be present in `/usr/share/flutter/`.
  84
  85 engine_sdk.zip contains
  86 * sdk/flutter_sdk.version - The Flutter SDK version
  87 * sdk/engine.version - The git commit of the Flutter Engine
  88 * sdk/clang_x64/gen_snapshot - used for creating release/profile AOT image
  89
  90 This recipe should be excluded from image in a production release.
  91
  92
  93 ## Flutter Workspace Automation
  94
  95     cd $AGL
  96     cd $AGL_TOP
  97     ln -sf external/workspace-automation/flutter_workspace.py meta-agl-devel/meta-agl-flutter/tools/flutter_workspace.py
  98     cd meta-agl-devel/meta-agl-flutter/tools
  99     export FLUTTER_WORKSPACE=`pwd`
 100     flutter_workspace.py
 101     source setup_env.sh
 102
 103 Additional documentation available [here](https://github.com/meta-flutter/meta-flutter/tree/kirkstone/tools#flutter-workspace-automation)
 104
 105
 106 ## Startup Service
 107
 108 This layer includes an example systemd user service for the Flutter Gallery application which is disabled by default.  It can be used to start the application in the minimal image by doing 'systemctl start flutter-gallery'.
 109
 110
 111 ## `/usr/share/flutter/default.json`
 112
 113 For more JSON key value options see [here](https://github.com/toyota-connected/ivi-homescreen/blob/agl/README.md#json-configuration-keys)
 114
 115
 116 ## Custom Devices
 117
 118 ### desktop-auto
 119
 120 This is a desktop build of flutter-auto.  The default configuration for backend is set to `egl` backend.  To change this to use the `vulkan` backend, change the `backend` key value in `meta-agl-flutter/tools/flutter_workspace_config.json` from `egl` to `vulkan`.  If you use the workspace configuration from meta-flutter it defaults to `vulkan`.
 121
 122 If you are running a Gnome Display Manager (GDM) Wayland session, then it will be an available custom-device platform.  To enable a Wayland session, you select the gear icon at the login window.  If you don't have a gear icon available on your login screen, then you will need to adjust your system settings to enable a Wayland session.
 123
 124 Append `--device-id=desktop-auto` to `flutter <cmd>` to select this device.
 125
 126 ### QEMU-agl
 127
 128 This is a QEMU minimal Flutter image as referenced [here](#steps-to-build-a-minimal-flutter-image).  The required runtime packages are installed as part of setup_flutter_workspace.py.
 129
 130 If qemu_run was sucessfully invoked, then this platform will be an available `custom-device`.  If QEMU instance is not running on port 2222, then this custom-device platform will not be available.
 131
 132 Append `--device-id=AGL-qemu` to `flutter <cmd>` to select this device.
 133
 134 ### Flutter Engine
 135
 136 To enable local build of Flutter Engine set `tools/configs/flutter-engine.json` load key to true.
 137
 138 This enables debugging as custom engine development.
 139
 140 ## Steps to Test Flutter Images
 141
 142 ### Debug
 143
 144 1. Set up Flutter Workspace per [Flutter Workspace Automation](#flutter-workspace-automation).
 145
 146 2. Run the following commands on the host's terminal, a QEMU window and a new terminal for AGL will be brought up.
 147
 148 ```
 149     cd $FLUTTER_WORKSPACE
 150     source ./setup_env.sh
 151     qemu_run
 152 ```
 153
 154 3. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
 155
 156 4. Wait for QEMU image to boot to idle the run
 157 ```
 158     ssh -p 2222 root@localhost who
 159 ```
 160 _Answering with `y` appends QEMU connection to `~/.ssh/known_hosts`_
 161
 162 5.  From the same host terminal open Visual Studio Code Select
 163    * **Run and Debug**
 164    * **gallery(AGL-qemu)** from the drop down combo box
 165    * **run** - this launches the Flutter gallery app in the QEMU window
 166
 167 6.  Or run from the same terminal as qemu_run was executed via
 168 ```
 169     cd $FLUTTER_WORKSPACE/app/gallery
 170     flutter run --device-id=AGL-qemu
 171 ```
 172
 173
 174 ### Working with QEMU images
 175
 176 1.  Setup the flutter workspace.
 177
 178     source ${FLUTTER_WORKSPACE}/setup_env.sh
 179
 180 The stdout tail should look similar to:
 181
 182     ********************************************
 183     * Type 'run-agl-qemu-master' to start
 184     ********************************************
 185     ********************************************
 186     * Type 'run-agl-qemu-octopus' to start
 187     ********************************************
 188
 189 3. Select image to run using one of above commands.
 190
 191 ```
 192     run-agl-qemu-octopus
 193 ```
 194
 195 4. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
 196
 197 5.  Login AGL as `root`, and execute `passwd -d agl-driver`.  Type `exit` and login as `agl-driver`.  Run the Flutter Gallery example with the command in AGL's terminal.
 198
 199 ```
 200         cd $FLUTTER_WORKSPACE/app/gallery
 201     flutter run -d agl-qemu-octopus
 202 ```
 203
 204
 205 ### Profile
 206
 207 1.  Setup the flutter workspace.
 208
 209     source ${FLUTTER_WORKSPACE}/setup_env.sh
 210
 211 The stdout tail should look similar to:
 212
 213     ********************************************
 214     * Type 'run-agl-qemu-master' to start
 215     ********************************************
 216     ********************************************
 217     * Type 'run-agl-qemu-octopus' to start
 218     ********************************************
 219
 220 3. Select image to run using one of above commands.
 221
 222 ```
 223     run-agl-qemu-octopus
 224 ```
 225
 226 4. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
 227
 228 5. After waiting for QEMU image to boot to idle issue
 229 ```
 230     ssh -p 2222 root@localhost who
 231 ```
 232 Answering with `y` appends QEMU connection to `~/.ssh/known_hosts`
 233
 234 6.  Login AGL as `agl-driver`, and issue the following command
 235 ```
 236         flutter-auto --window-type="BG" --b=/usr/share/flutter/gallery/3.3.7/profile --f --observatory-host=0.0.0.0 --observatory-port=1234
 237 ```
 238
 239 The last line of the output message should look similar to this:
 240 ```
 241     flutter: The Dart VM service is listening on http://0.0.0.0:1234/xxxxxxxxxxx=/
 242 ```
 243
 244 7. Run the following command in the host terminal, using the correct hash suffix.
 245 ```
 246         flutter attach --device-id=AGL-qemu --debug-url=http://127.0.0.1:1234/xxxxxxxxxxx=/
 247 ```
 248
 249 8. Then you should see the output as below. It tells us the URL of the Flutter DevTools debugger and profiler on AGL x86_64 QEMU Image.
 250 `An Observatory debugger and profiler on AGL x86_64 QEMU Image is available at: http://127.0.0.1:37383/xxxxxxxxxxx=/`
 251
 252 9. in the terminal type `v` to launch the debugger.