[ Meta ] Support conditionally allowing for imports of platform-specific core libraries on unsupported platforms

[bkonyi]

There's scenarios where developer tooling might want to compile code which contains platform specific core library imports for an unsupported platform (e.g, the web-based Flutter Widget Previewer should be able to render widgets from libraries with dart:io or dart:ffi imports, as long as the widgets don't actually use APIs from those libraries). There currently isn't consistent support for this provided by the various web runtimes:

• Neither DDC or dart2js have stubs for dart:ffi or dart:mirrors, so these libraries can never be imported
• webdev serve prevents applications with dart:io (and dart:isolate?) imports from being executed
• flutter run -d chrome, dart compile js, and DDC all allow for dart:io and dart:isolate imports

As previously discussed, we need a solution to allow for these native core libraries to be referenced in web projects created by developer tooling while also continuing to encourage the ecosystem to move towards making their packages platform agnostic.

This effort will consist of multiple parts:

• Add DDC and dart2js stubs for native core libraries
  • Create dart:ffi stubs for dart2js and DDC #62126
  • Create dart:mirrors stubs for dart2js and DDC #62127
• Add --allow-native-core-library-imports to DDC and dart2js to allow for native library imports #62128
  • This flag is disabled by default, and will not initially include dart:io and dart:isolate to avoid a breaking change.
  • Print warnings if an unsupported library is imported when --allow-native-core-library-imports is specified, with a (hidden?) flag to silence the warnings (e.g., --silence-native-core-library-imports-warnings).
  • We could consider printing details about which package or library is responsible for the imports, along with links to documentation on using conditional imports for platform specific libraries.
• Make treatment of dart:io and dart:isolate imports consistent with other native libraries:
  • File a breaking change request to no longer allow for dart:io and dart:isolate imports by default for DDC and dart compile js.
  • Initially include a notice that this behavior will be disabled by default in a future release when DDC or dart compile js encounters these imports without --allow-native-core-library-imports.
  • In a follow-up release, remove the warning and place dart:io and dart:isolate imports behind the --allow-native-core-library-imports flag.

This new behavior will not be widely promoted to avoid encouraging developers from using this in their day to day workflows.

[lrhn]

I would very much recommend not adding any way to import a library that doesn't work.

I'd rather release a package with conditionally exported stub libraries, like import 'package: mock_platform/mirrors.dart';, which exports dart:mirrors of its available, and a stub library of its not.

Such a package can also have features to determine whether the stub library or the real library was exported.

It requires anyone who wants their code to use platform-specific libraries in a cross platform setting to opt in by using the mock package instead of directly accessing the platform libraries.

What won't work with existing code that needs to be migrated. Nothing guarantees that such existing code will work with a mock/stub either. If it tries to use the library, it will fall anyway.

Having it as a compiler option risks everybody just adding that flag by default, because some small package that they depend on requires it, and then they may start adding imports themselves.

At least consider making the flag require you to specify each individual package that needs the feature enabled, so it won't enable it for everyone, potentially masking errors.