meta-agl-flutter/README.md

   1 # meta-agl-flutter
   2
   3 _This documentation is expecting user to be running Ubuntu 20.04_
   4
   5 ## Steps to build `agl-ivi-demo-platform-flutter` image
   6
   7 ```
   8     export AGL_TOP=$HOME/workspace_agl
   9     mkdir -p $AGL_TOP && cd $AGL_TOP
  10     repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -b master
  11     repo sync -j $(nproc)
  12     source meta-agl/scripts/aglsetup.sh -m qemux86-64 agl-demo
  13     bitbake agl-ivi-demo-platform-flutter
  14 ```
  15
  16 This builds AGL demo image that includes Flutter runtime=release.
  17
  18
  19 ## Steps to build a minimal flutter image
  20
  21 ```
  22     export AGL_TOP=$HOME/workspace_agl
  23     mkdir -p $AGL_TOP && cd $AGL_TOP
  24     repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -b master
  25     repo sync -j `grep -c ^processor /proc/cpuinfo`
  26     source meta-agl/scripts/aglsetup.sh -m qemux86-64 agl-devel agl-flutter
  27 ```
  28
  29 Build one of the minimal Flutter images below using `bitbake`
  30
  31 1. `agl-image-flutter-runtimedebug`
  32   * includes Flutter Engine SDK
  33   * includes SSH server
  34   * live debugging with target via host
  35
  36 2. `agl-image-flutter-runtimeprofile`
  37   * includes Flutter Engine SDK
  38   * includes SSH server
  39   * runs only Flutter Applications built as AOT profile images
  40   * live profiling with target via host
  41
  42 3. `agl-image-flutter-runtimerelease`
  43   * includes Flutter Engine SDK
  44   * runs only Flutter Applications built as AOT release images
  45   * Does not include SSH server
  46
  47
  48 ## Flutter Engine SDK
  49
  50 If recipe `flutter-engine-runtime<variant>-sdk-dev` is included in your AGL image, `engine_sdk.zip` will be present in `/usr/share/flutter/`.
  51
  52 engine_sdk.zip contains
  53 * sdk/flutter_sdk.version - The Flutter SDK version
  54 * sdk/engine.version - The git commit of the Flutter Engine
  55 * sdk/clang_x64/gen_snapshot - used for creating release/profile AOT image
  56
  57 This recipe should be excluded from image in a production release.
  58
  59
  60 ## Flutter Workspace Automation
  61
  62 ```
  63     mkdir -p <path to my workspace> && cd <path to my workspace>
  64     curl --proto '=https' --tlsv1.2 -sSf https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl-devel.git;a=blob_plain;f=meta-agl-flutter/tools/flutter_workspace_config.json;hb=HEAD -o flutter_workspace_config.json
  65     curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/meta-flutter/meta-flutter/kirkstone/tools/setup_flutter_workspace.py | python3
  66 ```
  67
  68 Additional documentation available [here](https://github.com/meta-flutter/meta-flutter/tree/kirkstone/tools#flutter-workspace-automation)
  69
  70
  71 ## Startup Service
  72
  73 If you include `flutter-gallery-runtime<variant>-init` it will install a systemd user service, which starts the Flutter Gallery on boot.  This is not included in the minimal images.
  74
  75 At runtime you can edit `/usr/share/flutter/default.json` to point to any Flutter bundle.
  76
  77
  78 ## `/usr/share/flutter/default.json`
  79
  80 For more JSON key value options see [here](https://github.com/toyota-connected/ivi-homescreen/blob/agl/README.md#json-configuration-keys)
  81
  82
  83 ## Custom Devices
  84
  85 ### desktop-auto
  86
  87 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`.
  88
  89 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.
  90
  91 Append `--device-id=desktop-auto` to `flutter <cmd>` to select this device.
  92
  93 ### QEMU-agl
  94
  95 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.
  96
  97 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.
  98
  99 Append `--device-id=AGL-qemu` to `flutter <cmd>` to select this device.
 100
 101
 102 ## Steps to Test Flutter Images
 103
 104 ### Debug
 105
 106 1. Set up Flutter Workspace per [Flutter Workspace Automation](#flutter-workspace-automation).
 107
 108 2. Run the following commands on the host's terminal, a QEMU window and a new terminal for AGL will be brought up.
 109
 110 ```
 111     cd $FLUTTER_WORKSPACE
 112     source ./setup_env.sh
 113     qemu_run
 114 ```
 115
 116 3. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
 117
 118 4. Wait for QEMU image to boot to idle the run
 119 ```
 120     ssh -p 2222 root@localhost who
 121 ```
 122 _Answering with `y` appends QEMU connection to `~/.ssh/known_hosts`_
 123
 124 5.  From the same host terminal open Visual Studio Code Select
 125    * **Run and Debug**
 126    * **gallery(AGL-qemu)** from the drop down combo box
 127    * **run** - this launches the Flutter gallery app in the QEMU window
 128
 129 6.  Or run from the same terminal as qemu_run was executed via
 130 ```
 131     cd $FLUTTER_WORKSPACE/app/gallery
 132     flutter run --device-id=AGL-qemu
 133 ```
 134
 135
 136 ### Release
 137
 138 1.  Change AGL-qemu flutter_runtime value in $AGL_TOP/sources/meta-agl-devel/meta-agl-flutter/tools/flutter_workspace_config.json to `release`.
 139
 140 ```
 141     {
 142         "id": "AGL-qemu",
 143         "type": "qemu",
 144         "arch": "x86_64",
 145         "flutter_runtime": "release",
 146         "runtime": {
 147 ```
 148
 149 This enables download of QEMU `release` variant.
 150
 151 2. Run the flutter workspace script
 152
 153 3. Run  the following commands on the host's terminal, a QEMU window and a new terminal for AGL will be brought up.
 154
 155 ```
 156     cd $FLUTTER_WORKSPACE
 157     unset QEMU_IMAGE
 158     source ./setup_env.sh
 159     qemu_run
 160 ```
 161
 162 4.  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.
 163
 164 ```
 165         flutter-auto --window-type="BG" --b=/usr/share/flutter/gallery --f
 166 ```
 167
 168
 169 ### Profile
 170
 171 1.  Change AGL-qemu flutter_runtime value in $AGL_TOP/sources/meta-agl-devel/meta-agl-flutter/tools/flutter_workspace_config.json to `profile`.
 172
 173 ```
 174     {
 175         "id": "AGL-qemu",
 176         "type": "qemu",
 177         "arch": "x86_64",
 178         "flutter_runtime": "profile",
 179         "runtime": {
 180 ```
 181
 182 This enables download of QEMU `profile` variant.
 183
 184 2. Run the flutter workspace script
 185
 186 3. Run  the following commands on the host's terminal, a QEMU window and a new terminal for AGL will be brought up.
 187
 188 ```
 189     cd $FLUTTER_WORKSPACE
 190     unset QEMU_IMAGE
 191     source ./setup_env.sh
 192     qemu_run
 193 ```
 194
 195 4. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
 196
 197 5. After waiting for QEMU image to boot to idle issue
 198 ```
 199     ssh -p 2222 root@localhost who
 200 ```
 201 Answering with `y` appends QEMU connection to `~/.ssh/known_hosts`
 202
 203 6.  Login AGL as `agl-driver`, and issue the following command
 204 ```
 205         flutter-auto --window-type="BG" --b=/usr/share/flutter/gallery --f --observatory-host=0.0.0.0 --observatory-port=1234
 206 ```
 207
 208 The last line of the output message should look similar to this:
 209 ```
 210     flutter: The Dart VM service is listening on http://0.0.0.0:1234/xxxxxxxxxxx=/
 211 ```
 212
 213 7. Run the following command in the host terminal, using the correct hash suffix.
 214 ```
 215         flutter attach --device-id=AGL-qemu --debug-url=http://127.0.0.1:1234/xxxxxxxxxxx=/
 216 ```
 217
 218 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.
 219 `An Observatory debugger and profiler on AGL x86_64 QEMU Image is available at: http://127.0.0.1:37383/xxxxxxxxxxx=/`
 220
 221 9. in the terminal type `v` to launch the debugger.