[native_assets_cli] Add config.code.flutter.cApi

[dcharkes]

Developers might want to build native code against flutter.h.

To prevent version skew between the package and the Flutter SDK, from-source build should use flutter.h from Flutter itself.
We should provide a path to it in the build config. Something along the lines of

config
  .code
    .flutter
      .cApi
        .headerPath
        .version

(Should flutter-specific code-specific config live under config.flutter.code or config.code.flutter?)

This is analogous to:

• [native_assets_cli] Access to dart_api.h and dart_api_dl.h + passing in the api version #839

To support prebuilt binaries, the version should be taken into account.

Note that this doesn't solve version skew between generated dart:ffi bindings with FFIgen on a flutter.h and then flutter.h getting a breaking change. This could theoretically be solved by providing access to version in Dart (for example via passing in version as a define in a C lib and compiling it in and accessing it via an FFI call, or by writing the version to a data asset and accessing it at runtime), and then branching between two sets of generated bindings. (This is a similar issue to #1589.)

[mkustermann]

Developers might want to build native code against flutter.h.

I don't think we'd want anything in dart-lang/native for that, as that is flutter specific.

So it would be a flutter-specific extension to the protocol. Because of that it would probably live in flutter/flutter. In fact it would probably be a package that flutter ships as part of Flutter SDK (i.e. a pined package:flutter_hooks Flutter SDK package, just like package:flutter).

Regarding stability of flutter.h. This is no different from stability of dart_api_dl.h, I assume it's kept very stable. Packages making use of it could use flutter sdk constraints to narrow that (e.g. newly introduced API functions in flutter version X would cause the package to use minimum flutter sdk version, ...).

(Should flutter-specific code-specific config live under config.flutter.code or config.code.flutter?)

The config.code.* namespace is managed by e.g. package:code and is intended to be used independent of flutter. It can decide to add more things to it's namespace, so I'd say that flutter specifics shouldn't be in there.

=> I'd tend to say flutter specifics can be in config.flutter* and flutter can manage that namespace.

[dcharkes]

Developers might want to build native code against flutter.h.

I don't think we'd want anything in dart-lang/native for that, as that is flutter specific.

So it would be a flutter-specific extension to the protocol. Because of that it would probably live in flutter/flutter. In fact it would probably be a package that flutter ships as part of Flutter SDK (i.e. a pined package:flutter_hooks Flutter SDK package, just like package:flutter).

Agreed. (Seems like I violated my own rule and filed the issue in the wrong repo!)

(Should flutter-specific code-specific config live under config.flutter.code or config.code.flutter?)

The config.code.* namespace is managed by e.g. package:code and is intended to be used independent of flutter. It can decide to add more things to it's namespace, so I'd say that flutter specifics shouldn't be in there.

=> I'd tend to say flutter specifics can be in config.flutter* and flutter can manage that namespace.

So you're kind of saying that extensibility should only be at the root of the config.json, not in nested maps? (I just filed #1837.)

[dcharkes]

Is the flutter.h not also an flutter embedder API (used for other C++ apps that want to embed flutter) rather than an API for plugins to talk to? Or is it both?

Originally posted by @mkustermann in #1837 (comment)

@stuartmorgan Could you elaborate on the need for having flutter.h available for your exploration of writing plugins with FFIgen/JNIgen? Was it for getting access to textures, or something else?