[NativeAOT LLVM] Support dotnet.js

[maraf]

• Building naot flavored dotnet.js
• Enable dotnet.js for naot-llvm apps targeting browser-wasm
• JS interop
  • Interop.Runtime.cs as wasm imports (instead of icalls)
  • Marshaling
    • JS marshallers should expect wasm import/export instead of Mono reflection found methods
    • Copy string to heap instead of passing MonoString ref to JS (already as feature flag in upstream)
    • Tasks
    • Delegates
    • JSObject
  • JSImport
  • JSExport
    • Generated __Register_ as wasm export
    • Generated wrapper as wasm export
  • Deliver the interop generator outside of app.ref pack
• Main
  • Export user written Main (possibly async) as wasm export (we need to do JS marshaling for it). Generated managed_main is also responsible for storing args and tearingdown the runtime
  • Store args, so they are available from Environment.GetCommandLineArgs()
• Yield to JS event loop
• Timers
• Allow to call UCO exports before Main (aka library mode)
• Add support for environment variables
• Add support for runtime options
• Move runtime JS files to /aotsdk instead of /framework
• Find a proper solution for Interop.Runtime.NativeAOT.cs and other switches in libs (libs can't use switch based on runtime flavor)
• Run library tests
  • System.Runtime.InteropServices.JavaScript

Smoke test with currently supported feature set
https://github.com/dotnet/runtimelab/blob/feature/NativeAOT-LLVM/src/tests/nativeaot/SmokeTests/DotnetJs

Original prototype
https://github.com/maraf/MinimalDotNetWasmNativeAOT/tree/dotnetjs/DotnetJsHack

[maraf]

cc @dotnet/nativeaot-llvm @pavelsavara @ivanpovazan

[SingleAccretion]

A few comments on the overall architecture.

Buidling naot flavored dotnet.js

The current NAOT-LLVM build is very simple (pass a few things to emcc, get .js back). It would be very valuable to ensure it remains so.

Another point is that the JS runtime contains things that are not the runtime's responsibility, but rather belong to libraries (e. g. hybrid globalization). It should be ensured that the runtime (unmanaged code and Runtime.Base) continues to be unaware of them.

JS interop

As with the above, (C#) code supporting it should live separately, in, e. g., a new System.Private.* library. If we need some special hooks into runtime functionality, they should be provided through an explicit interface.

(That said, I am not familiar with how it is implemented currently)

Async Main

Is a bit of a hard problem. Last time I looked, Mono code looked it up by name emitted by Roslyn. That is a hack. Perhaps we could consider asking Roslyn to somehow mark it...

[maraf]

The current NAOT-LLVM build is very simple (pass a few things to emcc, get .js back). It would be very valuable to ensure it remains so.

In Mono, dotnet.js is build during runtime build and than during app build it's just picked up from runtime pack + emscripten js with build different settings. Our golas is to support the same JS API as we have for Mono (you can see it here https://github.com/maraf/MinimalDotNetWasmNativeAOT/blob/dotnetjs/DotnetJsHack/main.js. The withConfig will go away).
Does that work for you?

Another point is that the JS runtime contains things that are not the runtime's responsibility, but rather belong to libraries (e. g. hybrid globalization). It should be ensured that the runtime (unmanaged code and Runtime.Base) continues to be unaware of them.

I don't details yet. AFAIK hybrid globalization is done by icalls from Globalization* into JavaScript

As with the above, (C#) code supporting it should live separately, in, e. g., a new System.Private.* library. If we need some special hooks into runtime functionality, they should be provided through an explicit interface.

The C# code already lives in a separate library System.Runtime.InteropServices.JavaScript

Is a bit of a hard problem. Last time a looked, Mono code looked it up by name emitted by Roslyn. That is a hack. Perhaps we could consider asking Roslyn to somehow mark it...

I don't have a solution for that yet. We also need to invoke JS marshaling to get the Task correctly back to JS as a promise

[yowl]

For Javascript support in general.

Jco (https://github.com/bytecodealliance/jco) are adding async/promise support to their wit bindgen, I wonder is there a route there, i.e. make the Javascript a component and consume it that way. Down the road a bit as we don't have full wit support yet.

(Edited as not related to Main, just an observation on work in related spaces)

[SingleAccretion]

In Mono, dotnet.js is build during runtime build and than during app build it's just picked up from runtime pack + emscripten js with build different settings.

What does the emcc command line look like (conceptually)? Emscripten has a number of ways to integrate JS code, which one is used?

Separate question: is the JS minified by default (at runtime build)? In NAOT, we have so far been following the strategy that -c Release does not strip debug info by default.

Separate question: how many of JS APIs depend on things like dynamic assembly loading and dynamic code execution (interpreter)? These would not work on NAOT (naturally).

I don't have a solution for that yet. We also need to invoke JS marshaling to get the Task correctly back to JS as a promise

How does the marshalling of tasks to promises work, in terms of native signatures and data flow? For example, how would the underlying UnmanagedCallersOnly method look for [JsExport] async Task AsyncMethod() { ... }?

[maraf]

What does the emcc command line look like (conceptually)? Emscripten has a number of ways to integrate JS code, which one is used?

We let emscripten generate ES6 module and link in mono functions. Then consume the emscripten module from our (two) modules. Running .\build.cmd -bl -os browser -subset mono+libs -c Debug gives you binlog with all the defails

Separate question: is the JS minified by default (at runtime build)? In NAOT, we have so far been following the strategy that -c Release does not strip debug info by default.

Emscripten JavaScript is unminified, our API generated from Typescript is minified in Release mode, but we have source maps pointing to github.

Separate question: how many of JS APIs depend on things like dynamic assembly loading and dynamic code execution (interpreter)? These would not work on NAOT (naturally).

I going to say "none", at least in the core paths. We have an API for lazy assembly loading, but it's not used by default. We lookup some C# functions with mono reflection, but I was able to bypass that with wasm exports for far.

How does the marshalling of tasks to promises work, in terms of native signatures and data flow? For example, how would the underlying UnmanagedCallersOnly method look for [JsExport] async Task AsyncMethod() { ... }?

An example of Roslyn generated wrapper for [JSExport] internal static async Task<string> GreetToJS(string name)

[global::System.Diagnostics.DebuggerNonUserCode]
[global::System.Runtime.InteropServices.UnmanagedCallersOnlyAttribute(EntryPoint = "_5B_BrowserConsoleApp_5D_Xyz_Interop_2F_MyClass_3A_GreetToJS")]
internal static unsafe void __Wrapper_GreetToJS(global::System.Runtime.InteropServices.JavaScript.JSMarshalerArgument* __arguments_buffer)
{
    string name;
    ref global::System.Runtime.InteropServices.JavaScript.JSMarshalerArgument __arg_exception = ref __arguments_buffer[0];
    ref global::System.Runtime.InteropServices.JavaScript.JSMarshalerArgument __arg_return = ref __arguments_buffer[1];
    global::System.Threading.Tasks.Task<string> __retVal = default;
    // Setup - Perform required setup.
    ref global::System.Runtime.InteropServices.JavaScript.JSMarshalerArgument __name_native__js_arg = ref __arguments_buffer[2];
    // Unmarshal - Convert native data to managed data.
    __name_native__js_arg.ToManaged(out name);
    try
    {
        __retVal = Xyz.Interop.MyClass.GreetToJS(name);
        __arg_return.ToJS(__retVal, static (ref global::System.Runtime.InteropServices.JavaScript.JSMarshalerArgument __task_result_arg, string __task_result) =>
        {
            __task_result_arg.ToJS(__task_result);
        });
    }
    catch (global::System.Exception ex)
    {
        __arg_exception.ToJS(ex);
    }
}

[SingleAccretion]

Thanks you, I think I am seeing the bigger picture now. Some more questions.

It is clear how the support for scenarios where JS is the root of execution work. What about cases where WASM is the root of execution, i. e. '$(NativeLib)' != ''? How do you package the JS runtime depends on for this (both static and non-static scenarios)?

(Currently, NAOT-LLVM depends on incredibly little JS, basically one --js-library)

For the async main, I see it will root a lot of task infrastructure, so definitely not something to be done always (i. e. only when the user requests such by writing it).

Is the user required to attribute async main with [JSExport] explicitly? I can see this working out simply by giving the generated UCO method a well-known EntryPoint, which the runtime and ILC would know about (it ties somewhat to your idea in #2433). The details would need to be figured out, but at least we don't need to modify Roslyn.

[maraf]

It is clear how the support for scenarios where JS is the root of execution work. What about cases where WASM is the root of execution, i. e. '$(NativeLib)' != ''? How do you package the JS runtime depends on for this (both static and non-static scenarios)?

Sorry, I probably don't follow. Do you mean the WASI scenario? All this effort is meant for browser/nodejs/v8 target.

For the async main, I see it will root a lot of task infrastructure, so definitely not something to be done always (i. e. only when the user requests such by writing it).

Definitely. If there isn't an async main, nothing should be rooted.

Is the user required to attribute async main with [JSExport] explicitly? I can see this working out simply by giving the generated UCO method a well-known EntryPoint, which the runtime and ILC would know about (it ties somewhat to your idea in #2433). The details would need to be figured out, but at least we don't need to modify Roslyn.

Yeah, adding [JSExport] attribute explicitly is possible, but it doesn't work with top-level-statements. Ideally I would like to find the method automatically, but I didn't probe it yet. I'm not sure if top-level-statements are "converted" before source generators or after and if Roslyn/msbuild will give me the name of the entrypoint in all cases.

[SingleAccretion]

Sorry, I probably don't follow.

The "shared library" scenario is like in https://devblogs.microsoft.com/dotnet/use-net-7-from-any-javascript-app-in-net-7/.

More interesting is the "static library" case. As you know, one can build static WASM libraries and distribute them to be linked with something later. With browser-wasm, you also have to distribute some JS, since the runtime depends on some JS. Today you can do so with basically one --js-library file. The question is how will that look after this work.

Ideally I would like to find the method automatically, but I didn't probe it yet. I'm not sure if top-level-statements are "converted" before source generators or after and if Roslyn/msbuild will give me the name of the entrypoint in all cases.

Pretty sure source generators will see the original source code for top-level statements. I am not sure how to make that work, even - you cannot call an unspeakable Main from the UCO wrapper, even if you generated one implicitly.

[maraf]

The "shared library" scenario is like in https://devblogs.microsoft.com/dotnet/use-net-7-from-any-javascript-app-in-net-7/.

More interesting is the "static library" case. As you know, one can build static WASM libraries and distribute them to be linked with something later. With browser-wasm, you also have to distribute some JS, since the runtime depends on some JS. Today you can do so with basically one --js-library file. The question is how will that look after this work.

I see, thanks! With dotnet.js you would need to (currently) distribute 3 .js files + 1 .wasm, because dotnet.js is split into 3 ES modules. We have an open issue to support merging those JS files into one.

By linking with something later, do you mean at WebAssembly level or at JavaScript level? If later is the case, you would also want to hide the nature that your library is implemented with dotnet under the hood and would probably want to wrap the API surface. I had a demo of that last year with integration to react https://github.com/maraf/dotnet-wasm-react.

[SingleAccretion]

By linking with something later, do you mean at WebAssembly level

Right, linking it statically, as in emcc myapp_written_in_c.o dotet_library.a .... How would that command line look like.

Connected to this is the question of whether the JS is set up to work correctly if it is not the root of execution, i. e. if the first thing under our control called is a UCO method from dotnet_library.a.

[maraf]

Right, linking it statically, as in emcc myapp_written_in_c.o dotet_library.a .... How would that command line look like.

Connected to this is the question of whether the JS is set up to work correctly if it is not the root of execution, i. e. if the first thing under our control called is a UCO method from dotnet_library.a.

I have never tried that. How does it work with plain emscripten? Who is responsible for downloading and instantiating the wasm module?

[SingleAccretion]

How does it work with plain emscripten? Who is responsible for downloading and instantiating the wasm module?

Static linking merges all of the input files together. You can see it in action if you look at some binlogs from the runtime (Mono or NAOT-LLVM) build, there are a bunch of library.a (archive, a collection of object files) and something.o (object) files with functions in the them that wasm-ld links together.

Emscripten then has a bespoke system for making JS "look like C" in this process: https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html#implement-a-c-api-in-javascript.