From c84523b3a501bbb1127d1da988d794a2dc4469b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Laban?= Date: Thu, 24 Oct 2024 08:26:17 -0400 Subject: [PATCH] docs: Adjust upgrade and native deps --- doc/features-additional-files.md | 3 +-- doc/features-module-linking.md | 44 ++++++++++++++++---------------- doc/using-the-bootstrapper.md | 4 +-- 3 files changed, 25 insertions(+), 26 deletions(-) diff --git a/doc/features-additional-files.md b/doc/features-additional-files.md index 0c0763f05..a64d0e8b3 100644 --- a/doc/features-additional-files.md +++ b/doc/features-additional-files.md @@ -58,5 +58,4 @@ Exclusions: Asset files: `wwwroot/uno-assets.txt` contains the package relative paths of the content files that were copied to the `wwwroot` folder. It can be used to identify which assets are packaged with the application at runtime and avoid costly probing operations. Important: Will only contain files deployed in `UnoDeploy="Package"` mode. -A few files extensions are excluded (`UnoDeploy="None")`by default such as `*.a`, `*.bc`. - `.html` files are those named `web.config` will default to `UnoDeploy="Root"`. +A few files extensions are excluded (`UnoDeploy="None")`by default such as `*.a`, `*.o`. `.html` files are those named `web.config` will default to `UnoDeploy="Root"`. diff --git a/doc/features-module-linking.md b/doc/features-module-linking.md index 7ea7a7fe5..2cd770f9e 100644 --- a/doc/features-module-linking.md +++ b/doc/features-module-linking.md @@ -6,18 +6,18 @@ uid: UnoWasmBootstrap.ModuleLinking ## Static Linking overview -Statically linking Emscripten LLVM Bitcode (`.bc` and `.a` files) files to mono is supported on both Windows 10 and Linux. To build on Windows please refer to the AOT environment setup instructions. +Statically linking Emscripten LLVM Bitcode (`.o` and `.a` files) files to mono is supported on both Windows 10 and Linux. To build on Windows please refer to the AOT environment setup instructions. -This linking type embeds the `.bc` or `.a` files with the rest of the WebAssembly modules, and uses _normal_ webassembly function invocations that are faster than with dynamic linking. +This linking type embeds the `.o` or `.a` files with the rest of the WebAssembly modules, and uses _normal_ webassembly function invocations that are faster than with dynamic linking. -Any `.bc` or `.a` file placed as `content` in the built project will be statically linked to the currently running application. +Any `.o` or `.a` file placed as `content` in the built project will be statically linked to the currently running application. -This allowing for p/invoke to be functional when resolving methods from the loaded module. If you have a `.bc` or a `.a` file you don't want to be include in the linking, you may add the `UnoAotCompile="false"` metadata that way: +This allowing for p/invoke to be functional when resolving methods from the loaded module. If you have a `.o` or a `.a` file you don't want to be include in the linking, you may add the `UnoAotCompile="false"` metadata that way: ```xml - - + + ``` @@ -41,22 +41,22 @@ error: DISABLE_EXCEPTION_THROWING was set (likely due to -fno-exceptions), which ## Static Linking multi-version support -As emscripten's ABI is not guaranteed to be compatible between versions, it may also be required to include multiple versions of the same LLVM binaries, compiled against different versions of LLVM. In order to enable this scenario, the Uno Bootstrapper supports adding .bc files by convention. - -If the bitcode file to be added is named `libTest.bc` or `libTest.a`, the following structure can be used in a project: - -| File path | Description | -|---------------------------------------|-------------------------------------------------------------------------------------------------------| -| `libTest.bc/2.0.6/libTest.bc` | Emscripten 2.0.6 to 2.0.8, single threaded (Bootstrapper 3.3 and earlier format) | -| `libTest.bc/2.0.9/libTest.bc` | Emscripten 2.0.9 and later, single threaded (Bootstrapper 3.3 and earlier format) | -| `libTest.bc/2.0.6/st/libTest.bc` | Emscripten 2.0.6 and later, single threaded | -| `libTest.bc/2.0.9/st/libTest.bc` | Emscripten 2.0.9 and later, single threaded | -| `libTest.bc/2.0.6/mt/libTest.bc` | Emscripten 2.0.6 and later, multi threaded | -| `libTest.bc/2.0.9/mt/libTest.bc` | Emscripten 2.0.9 and later, multi threaded | -| `libTest.bc/2.0.6/st,simd/libTest.bc` | Emscripten 2.0.6 and later, single threaded with SIMD | -| `libTest.bc/2.0.9/st,simd/libTest.bc` | Emscripten 2.0.9 and later, single threaded with SIMD | -| `libTest.bc/2.0.6/mt,simd/libTest.bc` | Emscripten 2.0.6 and later, multi threaded with SIMD | -| `libTest.bc/2.0.9/mt,simd/libTest.bc` | Emscripten 2.0.9 and later, multi threaded with SIMD | +As emscripten's ABI is not guaranteed to be compatible between versions, it may also be required to include multiple versions of the same LLVM binaries, compiled against different versions of LLVM. In order to enable this scenario, the Uno Bootstrapper supports adding .a files by convention. + +If the bitcode file to be added is named `libTest.o` or `libTest.a`, the following structure can be used in a project: + +| File path | Description | +|-------------------------------------|-------------------------------------------------------------------------------------------------------| +| `libTest.a/2.0.6/libTest.a` | Emscripten 2.0.6 to 2.0.8, single threaded (Bootstrapper 3.3 and earlier format) | +| `libTest.a/2.0.9/libTest.a` | Emscripten 2.0.9 and later, single threaded (Bootstrapper 3.3 and earlier format) | +| `libTest.a/2.0.6/st/libTest.a` | Emscripten 2.0.6 and later, single threaded | +| `libTest.a/2.0.9/st/libTest.a` | Emscripten 2.0.9 and later, single threaded | +| `libTest.a/2.0.6/mt/libTest.a` | Emscripten 2.0.6 and later, multi threaded | +| `libTest.a/2.0.9/mt/libTest.a` | Emscripten 2.0.9 and later, multi threaded | +| `libTest.a/2.0.6/st,simd/libTest.a` | Emscripten 2.0.6 and later, single threaded with SIMD | +| `libTest.a/2.0.9/st,simd/libTest.a` | Emscripten 2.0.9 and later, single threaded with SIMD | +| `libTest.a/2.0.6/mt,simd/libTest.a` | Emscripten 2.0.6 and later, multi threaded with SIMD | +| `libTest.a/2.0.9/mt,simd/libTest.a` | Emscripten 2.0.9 and later, multi threaded with SIMD | Based on the emscripten version used by the .NET runtime and the enabled runtime features, the bootstrapper will choose the closest matching version. diff --git a/doc/using-the-bootstrapper.md b/doc/using-the-bootstrapper.md index 98d9bcfda..a6dc4579d 100644 --- a/doc/using-the-bootstrapper.md +++ b/doc/using-the-bootstrapper.md @@ -104,10 +104,10 @@ By default, the .NET runtime does not load all resource assemblies, but if you w ``` -## Interop +### Interop - `Module.mono_bind_static_method` is not available anymore, you'll need to use `Module.getAssemblyExports` instead. -- `.bc` native files are not supported anymore. Use `.a` or `.o` extensions. +- .NET 9 upgrades to emscripten 3.1.56 for which `.bc` native files are not supported properly. Use `.a` or `.o` extensions instead for native dependencies. ### Deprecated APIs