meta-agl-flutter/README.md

   1 # meta-agl-flutter
   2
   3 ## Steps to build `agl-demo-platform` 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 agl-flutter
  11     bitbake agl-demo-platform
  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   * include 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 If you include `flutter-gallery-init` it will install a systemd user service, which starts the Flutter Gallery on boot.  This is not included in the minimal images.
  61
  62 At runtime you can edit `/usr/share/flutter/default.json` to point to any Flutter bundle.
  63
  64
  65 ## `/usr/share/flutter/default.json`
  66
  67 For more JSON key value options see [here](https://github.com/toyota-connected/ivi-homescreen/blob/agl/README.md#json-configuration-keys)
  68
  69
  70 ## Custom Devices
  71
  72 ### desktop-auto
  73
  74 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`.
  75
  76 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.
  77
  78 Append `--device-id=desktop-auto` to `flutter <cmd>` to select this device.
  79
  80 ### QEMU-agl
  81
  82 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.
  83
  84 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.
  85
  86 Append `--device-id=AGL-qemu` to `flutter <cmd>` to select this device.
  87
  88
  89 ## Steps to Test Flutter Images
  90
  91 ### Debug
  92
  93 1. Set up Flutter Workspace per [Flutter Workspace Automation](#flutter-workspace-automation).
  94
  95 2. Run the following commands on the host's terminal, a QEMU window and a new terminal for AGL will be brought up.
  96
  97 ```
  98     cd $FLUTTER_WORKSPACE
  99     source ./setup_env.sh
 100     qemu_run
 101 ```
 102
 103 3. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
 104
 105 4. Wait for QEMU image to boot to idle the run
 106 ```
 107     ssh -p 2222 root@localhost who
 108 ```
 109 _Answering with `y` appends QEMU connection to `~/.ssh/known_hosts`_
 110
 111 5.  From the same host terminal open Visual Studio Code Select
 112    * **Run and Debug**
 113    * **gallery(AGL-qemu)** from the drop down combo box
 114    * **run** - this launches the Flutter gallery app in the QEMU window
 115
 116 6.  Or run from the same terminal as qemu_run was executed via
 117 ```
 118     cd $FLUTTER_WORKSPACE/app/gallery
 119     flutter run --device-id=AGL-qemu
 120 ```
 121
 122
 123 ### Working with QEMU images
 124
 125 1.  Setup the flutter workspace.
 126
 127     source ${FLUTTER_WORKSPACE}/setup_env.sh
 128
 129 The stdout tail should look similar to:
 130
 131     ********************************************
 132     * Type 'run-agl-qemu-master' to start
 133     ********************************************
 134     ********************************************
 135     * Type 'run-agl-qemu-octopus' to start
 136     ********************************************
 137
 138 3. Select image to run using one of above commands.
 139
 140 ```
 141     run-agl-qemu-octopus
 142 ```
 143
 144 4. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
 145
 146 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.
 147
 148 ```
 149         cd $FLUTTER_WORKSPACE/app/gallery
 150     flutter run -d agl-qemu-octopus
 151 ```
 152
 153
 154 ### Profile
 155
 156 1.  Setup the flutter workspace.
 157
 158     source ${FLUTTER_WORKSPACE}/setup_env.sh
 159
 160 The stdout tail should look similar to:
 161
 162     ********************************************
 163     * Type 'run-agl-qemu-master' to start
 164     ********************************************
 165     ********************************************
 166     * Type 'run-agl-qemu-octopus' to start
 167     ********************************************
 168
 169 3. Select image to run using one of above commands.
 170
 171 ```
 172     run-agl-qemu-octopus
 173 ```
 174
 175 4. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
 176
 177 5. After waiting for QEMU image to boot to idle issue
 178 ```
 179     ssh -p 2222 root@localhost who
 180 ```
 181 Answering with `y` appends QEMU connection to `~/.ssh/known_hosts`
 182
 183 6.  Login AGL as `agl-driver`, and issue the following command
 184 ```
 185         flutter-auto --window-type="BG" --b=/usr/share/flutter/gallery/3.3.7/profile --f --observatory-host=0.0.0.0 --observatory-port=1234
 186 ```
 187
 188 The last line of the output message should look similar to this:
 189 ```
 190     flutter: The Dart VM service is listening on http://0.0.0.0:1234/xxxxxxxxxxx=/
 191 ```
 192
 193 7. Run the following command in the host terminal, using the correct hash suffix.
 194 ```
 195         flutter attach --device-id=AGL-qemu --debug-url=http://127.0.0.1:1234/xxxxxxxxxxx=/
 196 ```
 197
 198 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.
 199 `An Observatory debugger and profiler on AGL x86_64 QEMU Image is available at: http://127.0.0.1:37383/xxxxxxxxxxx=/`
 200
 201 9. in the terminal type `v` to launch the debugger.