Document blazor msbuild configuration options

[pbiggar]

There are a bunch of knobs available to config blazor projects, that I could not find documented anywhere:

• EmccCompileOptimizationFlag - allows you set how the wasm gets compiled
  • for example, this creates wasm that runs with assertions enabled:
    <EmccCompileOptimizationFlag>-O0 -s ASSERTIONS=2 -s STACK_OVERFLOW_CHECK=2 -s SAFE_HEAP=1</EmccCompileOptimizationFlag>
• EmccCompileLinkFlag - similar to EmccCompileOptimizationFlag but for linking
• BlazorEnableCompression - on by default, disables the (extremely slow) compression of Blazor assets
• I don't know what these do:
  • WasmNativeStrip
  • WasmLinkIcalls
  • WasmDebugLevel
  • WasmDedup
  • WasmNativeDebugSymbols
  • EmccVerbose

[guardrex]

BlazorEnableCompression is covered at ...

https://docs.microsoft.com/en-us/aspnet/core/blazor/host-and-deploy/webassembly?view=aspnetcore-6.0#compression

@mkArtakMSFT ... A bit in-the-weeds for us 😄, but we could do it. These sorts of things I would expect to find in Emscripten and Mono docs. However, I checked, and it's not trivial to cross-link anything for many of them. Definitions either aren't clear, aren't official, or are just code comments or must be surmised from reference source.

Anyway, should we mention the following and cross-link the Emscripten doc at https://emscripten.org/docs/optimizing/Optimizing-Code.html?

• EmccCompileOptimizationFlag
• EmccCompileLinkFlag

... and if we are going to cover those: Is it EmccCompileOptimizationFlag for the AOT section and EmccCompileLinkFlag for the Runtime Relinking section? Is that correct?

• https://docs.microsoft.com/en-us/aspnet/core/blazor/host-and-deploy/webassembly?view=aspnetcore-6.0#ahead-of-time-aot-compilation
• https://docs.microsoft.com/en-us/aspnet/core/blazor/host-and-deploy/webassembly?view=aspnetcore-6.0#runtime-relinking

I hacked up some definitions from Mono repo code comments for the following that might not be correct or complete. I'm going to stop tho before proceeding any further with it. This is just to give us a flavor of what we might try to cover and what we might say. Unfortunately, I can't provide any guidance on when/why they would be set, so we'll need a real PU engineer to flesh out best practices for use if we go further.

• WasmNativeStrip: Strip the native executable. Defaults to true.
• WasmLinkIcalls: Link out unused icalls. Defaults to the value of WasmBuildNative.
• WasmDebugLevel: Enables debugging and sets the debug log level. A value greater than zero (0) enables debugging and sets the debug log level to debug_level. A value of zero (0) disables debugging and enables interpreter optimizations. A value less than zero (0) enables debugging and disables debug logging.
• WasmDedup: String deduplication of generic instances when using AOT. Defaults to true.
• WasmNativeDebugSymbols: Build with native debug symbols. Useful only with RunAOTCompilation or WasmBuildNative set to true. Defaults to true.
• EmccVerbose: Set to false to disable verbose emcc output. Defaults to false❓

... and that's not all of them. I see more of these sorts of properties around the Mono repo, especially per this ...

https://github.com/dotnet/runtime/blob/main/src/mono/wasm/build/WasmApp.targets

I'm 👂 for your guidance on what to do.

[pbiggar]

Thanks!

WasmDebugLevel: Enables debugging and sets the debug log level. A value greater than zero (0) enables debugging and sets the debug log level to debug_level. A value of zero (0) disables debugging and enables interpreter optimizations. A value less than zero (0) enables debugging and disables debug logging.

As a quick note, it would be helpful to say what it means to "enable debugging" in the context of a Blazor app.

[mkArtakMSFT]

Thanks for bringing this up, @pbiggar.
@guardrex the first two bullet points as well as the last group I don't know what these do: are things owned by the runtime team - @lewing and @radical. @lewing I'll let it up to you to decide whether it's worth documenting these or not and where exactly these docs should be. Maybe https://docs.microsoft.com/en-us/dotnet/core/project-sdk/overview will be the right place.

And the compression is already covered in our docs. I don't think there is more to do here.

[mkArtakMSFT]

@guardrex I don't think there is anything else for you to do here, so removing this from Blazor docs project board.

[guardrex]

Thanks @mkArtakMSFT ... In that case, we can close as well, since we won't track any work that they do in .NET docs for this.

[pbiggar]

Just to make sure this doesn't get lost - it was transferred here from another repo. Is there a good repo to transfer this issue to?

[guardrex]

Go to that project SDK topic and use the feedback form there to open (This page button at the bottom). You can cross-link to this from the new issue there ...

https://docs.microsoft.com/dotnet/core/project-sdk/overview