Check generated features against SDK constraint of user

[dcharkes]

@jonasfj suggested that we should check the SDK constraint for the package we're generating to and give an error if we generate dart:ffi code that does not work on the oldest version.

• Unions should only work for SDK constraint 2.14 and higher.
• Packed structs and inline arrays should only work for SDK constraint 2.13 and higher.
• etc.

Then we tell our users to bump their SDK version to the one that the generated code will work for so that they don't accidentally upload code to pub which contains dart:ffi constructs that will only work on the latest stable release while their pubspec says it would work on older stable releases.

[mannprerak2]

Yes, that seems reasonable. I always thought the analyzer would indicate that the generated code will not work on older sdk versions. (Like it does when we use typedef (typealias) in <2.13)

[jonasfj]

I always thought the analyzer would indicate that the generated code will not work on older sdk versions.

That might be the case... depending on how features are annotated.

@dcharkes maybe, classes in dart:ffi should be annotated with @Since("2.13"), see:
https://github.com/dart-lang/sdk/blob/0cbadee34481d74cd92c6e18d49243070fd1fce7/sdk/lib/internal/internal.dart#L354-L390

I tried and couldn't get the hints to work, but maybe I'm just doing it wrong / or didn't rebuild correctly. Certainly looks like it's exposed in dartdoc.

[mannprerak2]

@dcharkes maybe, classes in dart:ffi should be annotated with @`Since("2.13"),

If this is added in 2.14 would we still need ffigen to error if generated code is not compatible with their SDK contraints?
Since the analyzer will give this info (with much more details).

If this is fixed in the analyzer, we can also simply call dart analyze . from ffigen. (Similar to how we can dart format .)

[dcharkes]

@mannprerak2 would you like to try to make a PR for the Dart SDK adding the @Since annotations?

[mannprerak2]

Sure, I can try. 😄

[mannprerak2]

I tried and couldn't get the hints to work

Same here. The analyzer isn't printing any warnings or errors.

I am not sure if the @Since annotations are even working. I tried to run dart analyze . on this -

void main(List<String> arguments) {
  Future<int>.delayed(Duration(seconds: 1)).onError<int>((e, stackTrace) => 0);
}

With the sdk lower bound set to 2.11.0.
The extension class that adds this function is marked with @Since("2.12"), but the analyzer didn't complain.

@Since("2.12")
extension FutureExtensions<T> on Future<T> {
Future<T> onError<E extends Object>(...

[dcharkes]

cc @lrhn for some light on the semantics on @Since().

[lrhn]

I don't know whether the analyzer uses the information in Since annotations. It's the intent, but I haven't actually checked what the analyzer does. I've made sure to add them, both as documentation and as actionable information.

The language versioning only applies to the language, so there is no problem using a @Since("2.14") API in a // @dart=2.12 library, as long as the min SDK for the package is 2.14.0.