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
  33 ## Flutter Engine SDK
  34
  35 If recipe `flutter-engine-sdk-dev` is included in your AGL image, `engine_sdk.zip` will be present in `/usr/share/flutter/`.
  36
  37 engine_sdk.zip contains
  38 * sdk/flutter_sdk.version - The Flutter SDK version
  39 * sdk/engine.version - The git commit of the Flutter Engine
  40 * sdk/clang_x64/gen_snapshot - used for creating release/profile AOT image
  41
  42 This recipe should be excluded from image in a production release.
  43
  44
  45 ## Flutter Workspace Automation
  46
  47     cd $AGL
  48     cd $AGL_TOP
  49     ln -sf external/workspace-automation/flutter_workspace.py meta-agl-devel/meta-agl-flutter/tools/flutter_workspace.py
  50     cd meta-agl-devel/meta-agl-flutter/tools
  51     export FLUTTER_WORKSPACE=`pwd`
  52     flutter_workspace.py
  53     source setup_env.sh
  54
  55 Additional documentation available [here](https://github.com/meta-flutter/meta-flutter/tree/kirkstone/tools#flutter-workspace-automation)
  56
  57
  58 ## Startup Service
  59
  60 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'.
  61
  62
  63 ## `/usr/share/flutter/default.json`
  64
  65 For more JSON key value options see [here](https://github.com/toyota-connected/ivi-homescreen/blob/agl/README.md#json-configuration-keys)
  66
  67
  68 ## Custom Devices
  69
  70 ### desktop-auto
  71
  72 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`.
  73
  74 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.
  75
  76 Append `--device-id=desktop-auto` to `flutter <cmd>` to select this device.
  77
  78 ### QEMU-agl
  79
  80 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.
  81
  82 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.
  83
  84 Append `--device-id=AGL-qemu` to `flutter <cmd>` to select this device.
  85
  86 ### Flutter Engine
  87
  88 To enable local build of Flutter Engine set `tools/configs/flutter-engine.json` load key to true.
  89
  90 This enables debugging as custom engine development.
  91
  92 ## Steps to Test Flutter Images
  93
  94 ### Debug
  95
  96 1. Set up Flutter Workspace per [Flutter Workspace Automation](#flutter-workspace-automation).
  97
  98 2. Run the following commands on the host's terminal, a QEMU window and a new terminal for AGL will be brought up.
  99
 100 ```
 101     cd $FLUTTER_WORKSPACE
 102     source ./setup_env.sh
 103     qemu_run
 104 ```
 105
 106 3. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
 107
 108 4. Wait for QEMU image to boot to idle the run
 109 ```
 110     ssh -p 2222 root@localhost who
 111 ```
 112 _Answering with `y` appends QEMU connection to `~/.ssh/known_hosts`_
 113
 114 5.  From the same host terminal open Visual Studio Code Select
 115    * **Run and Debug**
 116    * **gallery(AGL-qemu)** from the drop down combo box
 117    * **run** - this launches the Flutter gallery app in the QEMU window
 118
 119 6.  Or run from the same terminal as qemu_run was executed via
 120 ```
 121     cd $FLUTTER_WORKSPACE/app/gallery
 122     flutter run --device-id=AGL-qemu
 123 ```
 124
 125
 126 ### Working with QEMU images
 127
 128 1.  Setup the flutter workspace.
 129
 130     source ${FLUTTER_WORKSPACE}/setup_env.sh
 131
 132 The stdout tail should look similar to:
 133
 134     ********************************************
 135     * Type 'run-agl-qemu-master' to start
 136     ********************************************
 137     ********************************************
 138     * Type 'run-agl-qemu-octopus' to start
 139     ********************************************
 140
 141 3. Select image to run using one of above commands.
 142
 143 ```
 144     run-agl-qemu-octopus
 145 ```
 146
 147 4. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
 148
 149 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.
 150
 151 ```
 152         cd $FLUTTER_WORKSPACE/app/gallery
 153     flutter run -d agl-qemu-octopus
 154 ```
 155
 156
 157 ### Profile
 158
 159 1.  Setup the flutter workspace.
 160
 161     source ${FLUTTER_WORKSPACE}/setup_env.sh
 162
 163 The stdout tail should look similar to:
 164
 165     ********************************************
 166     * Type 'run-agl-qemu-master' to start
 167     ********************************************
 168     ********************************************
 169     * Type 'run-agl-qemu-octopus' to start
 170     ********************************************
 171
 172 3. Select image to run using one of above commands.
 173
 174 ```
 175     run-agl-qemu-octopus
 176 ```
 177
 178 4. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
 179
 180 5. After waiting for QEMU image to boot to idle issue
 181 ```
 182     ssh -p 2222 root@localhost who
 183 ```
 184 Answering with `y` appends QEMU connection to `~/.ssh/known_hosts`
 185
 186 6.  Login AGL as `agl-driver`, and issue the following command
 187 ```
 188         flutter-auto --window-type="BG" --b=/usr/share/flutter/gallery/3.3.7/profile --f --observatory-host=0.0.0.0 --observatory-port=1234
 189 ```
 190
 191 The last line of the output message should look similar to this:
 192 ```
 193     flutter: The Dart VM service is listening on http://0.0.0.0:1234/xxxxxxxxxxx=/
 194 ```
 195
 196 7. Run the following command in the host terminal, using the correct hash suffix.
 197 ```
 198         flutter attach --device-id=AGL-qemu --debug-url=http://127.0.0.1:1234/xxxxxxxxxxx=/
 199 ```
 200
 201 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.
 202 `An Observatory debugger and profiler on AGL x86_64 QEMU Image is available at: http://127.0.0.1:37383/xxxxxxxxxxx=/`
 203
 204 9. in the terminal type `v` to launch the debugger.