[v3,09/10] package/flutter-gallery: fix build options

As the flutter-gallery package is a reference package for users wishing to use
Flutter for their UX with Buildroot, this package must have the correct build
options. Indeed, this package currently starts and runs, but only because of
the 0001-remove-GetStorage.patch. Through testing, flutter-gallery fails to
run during the following scenario:
  - The xdg-user-dirs package is ported and present.
  - flutter-gallery depends on xdg-user-dirs.
  - The 0001-remove-GetStorage.patch file is removed.

After extensive testing and comparing the current build arguments against what
the meta-flutter repository for Yocto passes to all of the applications that
inherit flutter-app, it is clear that handling the dart_plugin_registrant.dart
file is missing from the dart arguments in the flutter-gallery build step.

As the documentation for the dart_plugin_registrant.dart file is nonexistent
in any official documentation. However, there is a comment from an issue on
the official dart-lang/sdk page on Github that explains what this file is
(and refers to the Dark SDK source code instead of official documentation.)

From https://github.com/dart-lang/sdk/issues/52506#issuecomment-1562806787:
```
The dart_plugin_registrant.dart is a very special file. It's neither included
in the Dart app nor any dependent packages. Rather it's an artificially
created file by the flutter tools. It contains logic to run plugin
registration logic.

A flutter build will eventually compile the Dart application where it will add
<dir>/.dart_tool/flutter_build/dart_plugin_registrant.dart as an extra source
file (see here). Additionally it will also inject that uri as a constant into
Dart source code via a -Dflutter.dart_plugin_registrant=<uri>.

Once the app runs it will access the
package:flutter/src/dart_plugin_registrant.dart:dartPluginRegistrantLibrary
constant and use it to look up the library object and then invoke the plugin
registration logic.
```

Now that what the dart_plugin_registrant.dart does is understood, we need to
pass the following to the dart binary during the flutter-gallery build step:

  -Dflutter.dart_plugin_registrant=file://[...]/dart_plugin_registrant.dart:
   Injects a file containing the logic to run the plugin registration logic as
   a constant into the flutter-application source code.

  --source file://$(@D)/.dart_tool/flutter_build/dart_plugin_registrant.dart:
    Adds the dart_plugin_registrant.dart file as a source file to compile.

  --source package:flutter/src/dart_plugin_registrant.dart:
    Binds the plugin implementation to the platform interface based on the
    configuration of the app's pubpec.yaml, and the plugin's pubspec.yaml.

The native_assets.yaml file provides the native-assets mapping for
@Native external functions. The flutter-gallery package has no functions
marked as @Native; however, calling "flutter build bundle" creates a blank
template "native_assets.yaml" file, which is safe to include in the build.
This line, while not necessary for flutter-gallery, may be helpful for other
users who use @Native external functions in their applications, and this
example makes porting other applications quicker and easier.

Finally, there is a known issue when using the dart_plugin_registrant.dart
file outlined here: https://github.com/flutter/flutter/issues/137972.

To summarize: If a user fails to pass the --obfuscate flag to gen_snapshsot
when using the dart_plugin_registrant.dart file, their application may fail
to start. One such application is Gallery, which I have independently verified.

As such, pass the --obfuscate flag to gen_snapshot to ensure that
flutter-gallery properly starts when building with the additional
dart_plugin_registrant.dart arguments above.

However, I acknowledge that the obfuscate flag hides function and class names
in compiled Dart code, and there are some cases when a user should avoid using
the flag. For example, when using the runtimeType API:
https://api.flutter.dev/flutter/dart-core/Object/runtimeType.html. However,
this is not the case with flutter-gallery, and the --obfuscate flag is needed.

Signed-off-by: Adam Duskett <adam.duskett@amarulasolutions.com>
---
 package/flutter-gallery/flutter-gallery.mk | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

ADam, All,

On 2024-01-17 15:50 -0700, Adam Duskett spake thusly:
> As the flutter-gallery package is a reference package for users wishing to use
> Flutter for their UX with Buildroot, this package must have the correct build
> options. Indeed, this package currently starts and runs, but only because of
> the 0001-remove-GetStorage.patch. Through testing, flutter-gallery fails to
> run during the following scenario:
>   - The xdg-user-dirs package is ported and present.
>   - flutter-gallery depends on xdg-user-dirs.
>   - The 0001-remove-GetStorage.patch file is removed.
> 
> After extensive testing and comparing the current build arguments against what
> the meta-flutter repository for Yocto passes to all of the applications that
> inherit flutter-app, it is clear that handling the dart_plugin_registrant.dart
> file is missing from the dart arguments in the flutter-gallery build step.
[--SNIP--]

Great commit log! This is exactly the kind of commit log that gives
confidence in the patch, as it demonstrates that the topic has been
researched, and the solution is explained, and the drawbacks identified
and justified.

I did not understand all the details of it, but the commit log really
helped me just apply the commit wihtout too much thought.

Thank you! 👍

> Signed-off-by: Adam Duskett <adam.duskett@amarulasolutions.com>
> ---
>  package/flutter-gallery/flutter-gallery.mk | 9 +++++++--
>  1 file changed, 7 insertions(+), 2 deletions(-)
> 
> diff --git a/package/flutter-gallery/flutter-gallery.mk b/package/flutter-gallery/flutter-gallery.mk
> index 50ddd9ffba..e23dc399da 100644
> --- a/package/flutter-gallery/flutter-gallery.mk
> +++ b/package/flutter-gallery/flutter-gallery.mk
> @@ -24,10 +24,15 @@ endef
>  
>  define FLUTTER_GALLERY_BUILD_CMDS
>  	cd $(@D) && \
> -		FLUTTER_RUNTIME_MODES=$(FLUTTER_ENGINE_RUNTIME_MODE) \

As we discusd on IRC, dropping FLUTTER_RUNTIME_MODES is unrelated to
this change, and although FLUTTER_RUNTIME_MODES is totally useless here,
dropping it should be part of another cleanup.

Applied to master with FLUTTER_RUNTIME_MODES restored, thanks.

Regards,
Yann E. MORIN.

> -		$(HOST_FLUTTER_SDK_BIN_DART_BIN) package:gallery/main.dart && \
> +		$(HOST_FLUTTER_SDK_BIN_DART_BIN) \
> +			-Dflutter.dart_plugin_registrant=file://$(@D)/.dart_tool/flutter_build/dart_plugin_registrant.dart \
> +			--source file://$(@D)/.dart_tool/flutter_build/dart_plugin_registrant.dart \
> +			--source package:flutter/src/dart_plugin_registrant.dart \
> +			--native-assets $(@D)/.dart_tool/flutter_build/*/native_assets.yaml \
> +			package:gallery/main.dart && \
>  		$(HOST_FLUTTER_SDK_BIN_ENV) $(FLUTTER_ENGINE_GEN_SNAPSHOT) \
>  			--deterministic \
> +			--obfuscate \
>  			--snapshot_kind=app-aot-elf \
>  			--elf=libapp.so \
>  			.dart_tool/flutter_build/*/app.dill
> -- 
> 2.43.0
> 
> _______________________________________________
> buildroot mailing list
> buildroot@buildroot.org
> https://lists.buildroot.org/mailman/listinfo/buildroot

>>>>> "Yann" == Yann E MORIN <yann.morin.1998@free.fr> writes:

 > ADam, All,
 > On 2024-01-17 15:50 -0700, Adam Duskett spake thusly:
 >> As the flutter-gallery package is a reference package for users wishing to use
 >> Flutter for their UX with Buildroot, this package must have the correct build
 >> options. Indeed, this package currently starts and runs, but only because of
 >> the 0001-remove-GetStorage.patch. Through testing, flutter-gallery fails to
 >> run during the following scenario:
 >> - The xdg-user-dirs package is ported and present.
 >> - flutter-gallery depends on xdg-user-dirs.
 >> - The 0001-remove-GetStorage.patch file is removed.
 >> 
 >> After extensive testing and comparing the current build arguments against what
 >> the meta-flutter repository for Yocto passes to all of the applications that
 >> inherit flutter-app, it is clear that handling the dart_plugin_registrant.dart
 >> file is missing from the dart arguments in the flutter-gallery build step.
 > [--SNIP--]

 > Great commit log! This is exactly the kind of commit log that gives
 > confidence in the patch, as it demonstrates that the topic has been
 > researched, and the solution is explained, and the drawbacks identified
 > and justified.

 > I did not understand all the details of it, but the commit log really
 > helped me just apply the commit wihtout too much thought.

 > Thank you! 👍

Committed to 2023.11.x, thanks.