Merge pull request #76514 from kateinoigakukun/yt/update-wasm-doc

Author: kateinoigakukun

docs/WebAssembly.md

@@ -10,20 +10,52 @@ available yet, specifically:
   2. While a preview of multi-threading and atomics is available in some browsers and stand-alone 
   WebAssembly hosts, [the corresponding proposal](https://github.com/WebAssembly/threads/) haven't 
   formally reached the implementation phase yet.
+    The multi-threading feature is available in `wasm32-unknown-wasip1-threads` target, but it's not
+    in `wasm32-unknown-wasi` target.
   3. Dynamic linking is not formally specified and tooling for it is not available yet.
 * Binary size is a high priority requirement. Since WebAssembly payloads are usually served in browsers,
 one wouldn't want end users to download multi-megabyte binaries.
 
-Nevertheless, an early implementation of the WebAssembly target is available [in a separate 
-fork](https://github.com/SwiftWasm). Here we're describing some decisions that were made while developing
+## Building Swift SDK for WebAssembly
+
+The [Swift SDK](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md)
+for WebAssembly is built using the following command:
+
+```bash
+./utils/build-script --build-wasm-stdlib
+```
+
+This command will build the Swift compiler for the host platform and then build the Swift standard library
+for WebAssembly targets. The resulting Swift SDK `.artifactbundle` will be placed in the `../swift-sdk-generator/Bundles`
+directory.
+
+## Building Swift SDK for WebAssembly without building the compiler
+
+Building the Swift compiler is a time-consuming process. If you only want to build the Swift standard library
+with pre-built Swift compiler, you can use the following command:
+
+```console
+$ SWIFT_TOOLS_PATH=path/to/swift-development-snapshot/usr/bin
+$ ./utils/build-script \
+    --skip-build-llvm \
+    --skip-build-swift \
+    --skip-build-cmark \
+    --build-wasm-stdlib \
+    --native-swift-tools-path="$SWIFT_TOOLS_PATH" \
+    --native-clang-tools-path="$SWIFT_TOOLS_PATH" \
+    --native-llvm-tools-path="$SWIFT_TOOLS_PATH"
+```
+
+## Notes on the implementation
+
+Here we're describing some decisions that were made while developing
 the implementation.
 
-## Relative Pointers
+### Relative Pointers
 
-Relative pointers are used in Swift runtime, but currently it's not feasible to use them for the WebAssembly
-target due to the design of WebAssembly and lack of LLVM support. If LLVM supported subtraction relocation 
-type on WebAssembly like `R_X86_64_PC32` or `X86_64_RELOC_SUBTRACTOR`, this issue can be solved easily.
+Relative pointers are used in Swift runtime, but currently it's not feasible to use them for some cases
+where the pointee is a function pointer. The reason is that WebAssembly has a separate address space for
+functions and data, and the offset bwtween a function and a data pointer cannot be defined. Therefore,
+we have to use absolute pointers for function pointers in WebAssembly (see `include/swift/ABI/CompactFunctionPointer.h`
+for more details).
 
-Since `R_X86_64_PC32` and `X86_64_RELOC_SUBTRACTOR` are mainly used to generate PIC but WebAssembly doesn't
-require PIC because it doesn't support dynamic linking. In addition, the memory space also begins at 0, so
-it's unnecessary to relocate at load time. All absolute addresses can be embedded in wasm binary file directly.