Add meta-agl-flutter

Add meta-agl-flutter layer as it is being moved from meta-agl-devel.
The files are copies of the state in meta-agl-devel as of commit
97310e35, with only a minor change to the feature template to adjust
the location of the layer for bblayers.conf.

Bug-AGL: SPEC-5184

Change-Id: I9a14e4ab3a1b1726b0ccc1dbc112d76864dd106c
Signed-off-by: Scott Murray <scott.murray@konsulko.com>
Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/meta-agl/+/30016
Tested-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>
Reviewed-by: Jan-Simon Moeller <jsmoeller@linuxfoundation.org>

1 files changed, 252 insertions, 0 deletions

diff --git a/meta-agl-flutter/README.md b/meta-agl-flutter/README.md
new file mode 100644
index 000000000..24929ccd0
--- /dev/null
+++ b/meta-agl-flutter/README.md
@@ -0,0 +1,252 @@
+# meta-agl-flutter
+
+## Steps to build `agl-ivi-demo-platform-flutter` image
+
+```
+    export AGL_TOP=$HOME/workspace_agl
+    mkdir -p $AGL_TOP && cd $AGL_TOP
+    repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -b master
+    repo sync -j $(nproc)
+    source meta-agl/scripts/aglsetup.sh -m qemux86-64 agl-demo
+    bitbake agl-ivi-demo-platform-flutter
+```
+
+This builds AGL demo image that includes Flutter runtime={debug,profile,release}.
+
+
+## Steps to build a minimal flutter image
+
+```
+    export AGL_TOP=$HOME/workspace_agl
+    mkdir -p $AGL_TOP && cd $AGL_TOP
+    repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -b master
+    repo sync -j `grep -c ^processor /proc/cpuinfo`
+    source meta-agl/scripts/aglsetup.sh -m qemux86-64 agl-devel agl-flutter
+    bitbake agl-image-flutter
+```
+  * includes Flutter engine runtime={debug,release,profile}
+  * includes Flutter Engine SDK
+  * includes SSH server
+  * live debugging/profiling with target via host
+
+## Useful Notes
+
+flutter-auto runs as user `agl-driver`.  After logging in as root you can delete password for `agl-driver`:
+```
+# passwd -d agl-driver
+```
+
+To track flutter-auto output:
+```
+# journalctl -ex -u flutter-homescreen -f
+```
+
+To view available Flutter programs in OS image:
+```
+ls -la /usr/share/flutter
+```
+
+To change Flutter program that runs on boot edit this file:
+```
+# vi /usr/lib/systemd/system/flutter-homescreen.service
+```
+
+To change device to run Gallery on reboot edit flutter-homescreen.service to:
+```
+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
+```
+To enable experimental impeller support edit flutter-homescreen.service adding --enable-impeller:
+```
+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
+```
+
+After edits either run:
+```
+# systemctl daemon-reload
+# systemctl restart flutter-homescreen
+```
+or
+```
+# reboot
+```
+
+Collecting a stack trace for flutter-auto
+```
+# systemctl stop flutter-auto
+# export SPDLOG_LEVEL=trace
+# export XDG_RUNTIME_DIR=/run/user/1001/
+# gdb --args flutter-auto --b=/usr/share/flutter/gallery/<flutter version>/release/ --j=/usr/share/flutter/flutter-homescreen.json --xdg-shell-app-id=homescreen
+```
+
+## Flutter Engine SDK
+
+If recipe `flutter-engine-sdk-dev` is included in your AGL image, `engine_sdk.zip` will be present in `/usr/share/flutter/`.
+
+engine_sdk.zip contains
+* sdk/flutter_sdk.version - The Flutter SDK version
+* sdk/engine.version - The git commit of the Flutter Engine
+* sdk/clang_x64/gen_snapshot - used for creating release/profile AOT image
+
+This recipe should be excluded from image in a production release.
+
+
+## Flutter Workspace Automation
+
+    cd $AGL
+    cd $AGL_TOP
+    ln -sf external/workspace-automation/flutter_workspace.py meta-agl-devel/meta-agl-flutter/tools/flutter_workspace.py
+    cd meta-agl-devel/meta-agl-flutter/tools
+    export FLUTTER_WORKSPACE=`pwd`
+    flutter_workspace.py
+    source setup_env.sh
+
+Additional documentation available [here](https://github.com/meta-flutter/meta-flutter/tree/kirkstone/tools#flutter-workspace-automation)
+
+
+## Startup Service
+
+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'.
+
+
+## `/usr/share/flutter/default.json`
+
+For more JSON key value options see [here](https://github.com/toyota-connected/ivi-homescreen/blob/agl/README.md#json-configuration-keys)
+
+
+## Custom Devices
+
+### desktop-auto
+
+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`.
+
+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.
+
+Append `--device-id=desktop-auto` to `flutter <cmd>` to select this device.
+
+### QEMU-agl
+
+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.
+
+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.
+
+Append `--device-id=AGL-qemu` to `flutter <cmd>` to select this device.
+
+### Flutter Engine
+
+To enable local build of Flutter Engine set `tools/configs/flutter-engine.json` load key to true.
+
+This enables debugging as custom engine development.
+
+## Steps to Test Flutter Images
+
+### Debug
+
+1. Set up Flutter Workspace per [Flutter Workspace Automation](#flutter-workspace-automation).
+
+2. Run the following commands on the host's terminal, a QEMU window and a new terminal for AGL will be brought up.
+
+```
+    cd $FLUTTER_WORKSPACE
+    source ./setup_env.sh
+    qemu_run
+```
+
+3. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
+
+4. Wait for QEMU image to boot to idle the run
+```
+    ssh -p 2222 root@localhost who
+```
+_Answering with `y` appends QEMU connection to `~/.ssh/known_hosts`_
+
+5.  From the same host terminal open Visual Studio Code Select
+   * **Run and Debug**
+   * **gallery(AGL-qemu)** from the drop down combo box
+   * **run** - this launches the Flutter gallery app in the QEMU window​
+
+6.  Or run from the same terminal as qemu_run was executed via
+```
+    cd $FLUTTER_WORKSPACE/app/gallery
+    flutter run --device-id=AGL-qemu
+```
+
+
+### Working with QEMU images
+
+1.  Setup the flutter workspace.
+
+    source ${FLUTTER_WORKSPACE}/setup_env.sh
+
+The stdout tail should look similar to:
+
+    ********************************************
+    * Type 'run-agl-qemu-master' to start
+    ********************************************
+    ********************************************
+    * Type 'run-agl-qemu-octopus' to start
+    ********************************************
+
+3. Select image to run using one of above commands.
+
+```
+    run-agl-qemu-octopus
+```
+
+4. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
+
+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.
+
+```
+	cd $FLUTTER_WORKSPACE/app/gallery
+    flutter run -d agl-qemu-octopus
+```
+
+
+### Profile
+
+1.  Setup the flutter workspace.
+
+    source ${FLUTTER_WORKSPACE}/setup_env.sh
+
+The stdout tail should look similar to:
+
+    ********************************************
+    * Type 'run-agl-qemu-master' to start
+    ********************************************
+    ********************************************
+    * Type 'run-agl-qemu-octopus' to start
+    ********************************************
+
+3. Select image to run using one of above commands.
+
+```
+    run-agl-qemu-octopus
+```
+
+4. If running an updated QEMU image, edit `~/.ssh/known_hosts` and remove previous connection.
+
+5. After waiting for QEMU image to boot to idle issue
+```
+    ssh -p 2222 root@localhost who
+```
+Answering with `y` appends QEMU connection to `~/.ssh/known_hosts`
+
+6.  Login AGL as `agl-driver`, and issue the following command
+```
+	flutter-auto --window-type="BG" --b=/usr/share/flutter/gallery/3.3.7/profile --f --observatory-host=0.0.0.0 --observatory-port=1234
+```
+
+The last line of the output message should look similar to this:
+```
+    flutter: The Dart VM service is listening on http://0.0.0.0:1234/xxxxxxxxxxx=/
+```
+
+7. Run the following command in the host terminal, using the correct hash suffix.
+```
+	flutter attach --device-id=AGL-qemu --debug-url=http://127.0.0.1:1234/xxxxxxxxxxx=/
+```
+​
+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.
+`An Observatory debugger and profiler on AGL x86_64 QEMU Image is available at: http://127.0.0.1:37383/xxxxxxxxxxx=/`
+​
+9. in the terminal type `v` to launch the debugger.