How is runtime/include versioned?

[blaugold]

While verifying that my package still works with the current stable channel, I ran into an issue where my code broke because of a backwards incompatible change of Dart_CObject_Type in dart_native_api.h. Between Dart 2.18 and 2.19 two new enum values were added in a way that changed the order of other values. The code in question is part of a precompiled native library that is shipped with the package.

Currently, I'm not sure what the ABI versioning policy of the APIs in runtime/include is.

Dart_InitializeApiDL implements an API versioning check, but my understanding is that this is limited to the symbols available through dart_api_dl.h. Dart_InitializeApiDL also does not document the semantics of its return value.

[a-siva]

//cc @dcharkes

[dcharkes]

Thanks for reporting @blaugold !

Between Dart 2.18 and 2.19 two new enum values were added in a way that changed the order of other values.

That should have been a major version bump in https://github.com/dart-lang/sdk/blob/main/runtime/include/dart_version.h
Or, maybe better would have been to add the new values at the end of the enum, so it would have only been a minor version bump.

two new enum values were added

I only see Dart_CObject_kUnmodifiableExternalTypedData, which other one was added as well @blaugold ?

8c577c4 added Dart_CObject_kUnmodifiableExternalTypedData.
cc @rmacnak-google @mkustermann

I believe we should reorder the enum values (they are not alphabetically sorted anyway) so that the new ones are at the end, and file a cherry pick for the 2.19 stable and 3.0.0 beta.
cc @athomas

We've already run into this before:

• Can we get a guarantee for ABI stability? We would break all flutter FFI plugins on bumping the major version (like we have to do now).
• Can we make dart_api_dl.h standalone to limit the API surface? This requires copying some definitions and macros from dart_api.h and dart_native_api.h (gist). It is probably cleaner to move them to a separate standalone file. In any case we need to add tests that the version number is bumped when these are changed to prevent future breakage.

• Problems around versioning of the DL API (dart_api_dl.h). #47649

Issue for tracking standalone file:

• [vm/ffi] dart_api_dl.h should be standalone #49458

(A standalone dart_api_dl.h might have caught this, if we had code that casts the API types blindly and invokes things. That would have led to errors if we had a test exercising this.)

[blaugold]

I only see Dart_CObject_kUnmodifiableExternalTypedData, which other one was added as well @blaugold ?

Ah, sorry. I had an older copy of the files in runtime/include checked into my repo and when comparing it with the current version it looked like Dart_CObject_kNativePointer had also been added, but that was in Dart 2.15.

[dcharkes]

I only see Dart_CObject_kUnmodifiableExternalTypedData, which other one was added as well @blaugold ?

Ah, sorry. I had an older copy of the files in runtime/include checked into my repo and when comparing it with the current version I looked like Dart_CObject_kNativePointer had also been added, but that was in Dart 2.15.

Hm, I don't think we'd want to cherry pick for 2.15, 2.16, 2.17, and 2.18 as well. The only enum value after Dart_CObject_kNativePointer is Dart_CObject_kUnsupported. I do you rely on that?

[blaugold]

No, Dart_CObject_kSendPort is what caused my issue.

[blaugold]

@dcharkes Is a CP planned for the fix? I don't need one, since I had already released a fix for my package by recompiling with a recent Dart SDK when I opened this issue. When the fix lands, I'll have to recompile and release a new version, so I just wanted to know when I should expect the fix to land.

[dcharkes]

Thanks for the ping @blaugold, this had slipped my mind!