[native_assets_cli] Asset build-time classes and run-time classes

[dcharkes]

While discussing with @mosuem we realized that many asset types will have a build-time API and run-time API in the same package.

This is nice, because it means that the these APIs can point to each other:

// package:my_asset/declaration.dart

/// A declaration for my asset.
///
/// Use this asset at runtime via [MyAsset].
class MyAssetDeclaration {
  
}

// package:my_asset/my_asset.dart

/// My asset.
///
/// Declare assets in hooks via [MyAssetDeclaration].
class MyAsset {
  
}

This is nice because the runtime API is version locked with the declaration API. So for assets built on top of data assets the serialization to JSON/bytes/... in the build hook and deserialization at runtime does not have to deal with version skew.

(CodeAssets are weird because they use @Native as runtime API. DataAssets are somewhat special because the implementation is in the SDK, but the public API is still in a package: currently package:assets. This should most likely be moved to be together with package:data_assets which should also contain the declaration.)

The API used at runtime and build-time should be disjoint, which calls for having two libraries which can be imported separately:

• package:my_asset/declaration.dart for use in hooks.
• package:my_asset/my_asset.dart for use at runtime.

Now, we have a questions about naming.

• How do we name the class used at build-time and the one named at run-time? (They could both be named MyAsset since they're available under different import paths, but that's likely going to be very confusing.)
  • build-time: DataAssetDeclaration, DataAssetDefinition, BuildDataAsset, ...
  • runtime: DataAsset
• How do we name the libraries?
  • build-time: package:data_assets/for_hooks.dart, package:data_assets/declaration.dart, ...
  • runtime: package:data_assets/data_assets.dart, package:data_assets/runtime.dart, package:data_assets/use.dart, ...

[mosuem]

As always - interested in your opinion on this @lrhn. https://dart-review.googlesource.com/c/sdk/+/412920 is a CL for a hypothetical package:assets, so far only containing the runtime components.

[dcharkes]

Notes from discussion w @mosuem @mkustermann @liamappelbe:

• import library: have hook in the name. package:data_assets/hook.dart
• (The public API may not have to expose a class, however this only applies if the package author also owns the linker. So this is not a general pattern.)
• The most important class is the runtime class (as noted above), so that should claim the DataAssert name.
• Naming options for the class used in hooks:
  • Possible name DataHookAsset have HookAsset as naming convention for assets in hooks.
  • DataAssetHookTime, DataAssetInHook but more verbose than DataHookAsset
  • pieces:
    • 1. hook part -> output is a built artifact
    • 2. bundling part -> packages it in a certain way
    • 3. runtime part -> users access an opaque id with load method or @Native annotation.
    • Is it the same thing at step 1 and step 3? No: it's different information. Yes: It's conceptually the same thing. Related but not the same thing.
    • What naming can we take from these 3 phases? "hook time".
  • DataAsset$ concise, once the convention is known could be good.
  • DataAsset$InHook (using the the $ as separator).
    • DataAsset$InHook is phase 1 during the hook, DataAsset is phase 3 at runtime.
  • DataAssetOutput, DataAssetHookOutput (weird because assets can be input)

Leaning towards DataHookAsset. It's a data asset during the hook invocations. (I don't like how it splits the name DataAsset in two, but it's better than DataAsset$InHook and DataAsset$.) cc @lrhn

Side note from discussion:

• Should probably also update CodeAsset to CodeHookAsset then? We don't have a CodeAsset in the @Natives though, they are used simply with @Native(assetId: someCodeAsssetAssetId). And CodeAsset(assetId).lookupFunction would make the API be dynamic instead of static.
  • CodeAsset(Runtime) would be the natural place to put [vm/ffi] Add support for weak symbols @Native(weak: true) sdk#60038 (comment).