Describe free-standing

Author: hoodmane

peps/pep-0783.rst

@@ -51,18 +51,23 @@ This creates friction both for package maintainers and for users.
 Rationale
 =========
 
-Emscripten uses a variant of musl libc. The Emscripten compiler makes no ABI
-stability guarantees between versions. Many Emscripten updates are ABI
-compatible by chance, and the Rust Emscripten target behaves as if the ABI were
-stable with only `occasional negative consequences
-<https://github.com/rust-lang/rust/issues/131467>`__.
-
-There are several linker flags that adjust the Emscripten ABI, so Python
-packages built to run with Emscripten must make sure to match the ABI-sensitive
-linker flags used to compile the interpreter to avoid load-time or run-time
-errors. The Emscripten compiler continuously fixes bugs and adds support for new
-web platform features. Thus, there is significant benefit to being able to
-update the ABI.
+When Emscripten builds an application, it builds it as a free-standing program,
+including the entire operating system. Emscripten primarily targets the use case
+of fully static programs. When dynamic linking is used, the primary target use
+case is bundle splitting and lazy loading, where the dynamic libraries are built
+at the same time as the application.
+
+As a result of that, the Emscripten compiler makes no ABI stability guarantees
+between versions. Many Emscripten updates are ABI compatible by chance, and the
+Rust Emscripten target behaves as if the ABI were stable with only `occasional
+negative consequences <https://github.com/rust-lang/rust/issues/131467>`__.
+
+There are several linker flags that adjust the Emscripten ABI or system
+libraries. Python packages built to run with Emscripten must make sure to match
+the ABI-sensitive linker flags used to compile the interpreter to avoid
+load-time or run-time errors. The Emscripten compiler continuously fixes bugs
+and adds support for new web platform features. Thus, there is significant
+benefit to being able to update the ABI.
 
 In order to balance the ABI stability needs of package maintainers with the ABI
 flexibility to allow the platform to move forward, Pyodide plans to adopt a new
@@ -249,7 +254,7 @@ packages <https://pyodide.org/en/stable/usage/loading-packages.html>`__.
 
 For package maintainers, we recommend the `Pyodide documentation on building and
 testing packages
-<https://pyodide.org/en/stable/development/building-and-testing-packages.html>`__.
+<https://pyodide.org/en/stable/development/building-packages-from-source.html>`__.
 
 Reference Implementation
 ========================