Add documentation for feature flags and browser version flags. (#23347)

Author: dschuff

ChangeLog.md

@@ -31,14 +31,14 @@ See docs/process.md for more on how version tagging works.
     of the target integer type, the result will be a number of the max or min value
     instead of a trap. This also results in a small code size improvement because
     of details of the LLVM IR semantics. This feature can be disabled in clang with
-    the -mno-nontrapping-fptoint flag. (#23007)
+    the `-mno-nontrapping-fptoint` flag. (#23007)
   - The `WASM_BIGINT` feature is enabled by default. This has the effect that
     Wasm i64 values are passed and returned between Wasm and JS as BigInt values
     rather than being split by Binaryen into pairs of Numbers. (#22993)
   - The `BULK_MEMORY` feature is enabled by default. `memory.copy` and
     `memory.fill` instructions are used in the implementation of C `memcpy` and
     `memset`, and Clang may generate them elsewhere (#22873). It can be
-    disabled with the `-mno-bulk-memory` flag.
+    disabled with the `-mno-bulk-memory -mno-bulk-memory-opt` flags.
 - When using `-sMODULARIZE` we now assert if the factory function is called with
   the JS `new` keyword.  e.g. `a = new Module()` rather than `b = Module()`.
   This paves the way for marking the function as `async` which does not allow

site/source/docs/compiling/WebAssembly.rst

@@ -92,14 +92,57 @@ When using ``emcc`` to build to WebAssembly, you will see a ``.wasm`` file conta
 
 You may also see additional files generated, like a ``.data`` file if you are preloading files into the virtual filesystem. All that is exactly the same as when building to asm.js. One difference you may notice is the lack of a ``.mem file``, which for asm.js contains the static memory initialization data, which in WebAssembly we can pack more efficiently into the WebAssembly binary itself.
 
-WebAssembly support in browsers
-===============================
 
-WebAssembly is supported by all major browsers going back to Firefox 52, Chrome
-57, Safari 11 and Opera 44.
+WebAssembly feature extensions
+==============================
+
+Since its original launch, WebAssembly has been expanded with various feature
+extensions, which have been implmented in browsers. A list of features
+(including already-shipped and in-progress) and details about browser versions
+that support them can be found on
+`webassembly.org <https://webassembly.org/features/>`_.
+
+Several of these features can be used by Emscripten (or are by default) and can
+be enabled or disabled individually (using either Clang or emscripten flags)
+or by selecting which version of browsers Emscripten should target.
+
+Examples:
+
+* Exception handling (see :ref:`exceptions` for details).
+* SIMD (see :ref:`Porting SIMD code` for details).
+* Nontrapping float-to-int conversion (enabled by default, use
+  ``-mno-nontrapping-fptoint`` to disable).
+  Clang will generate nontrapping (saturating) float-to-int conversion instructions for
+  C typecasts. This should have no effect on programs that do not have
+  undefined behavior but if the casted floating-point value is outside the range
+  of the target integer type, the result will be a number of the max or min value
+  instead of a trap. This also results in a small code size improvement because
+  of details of the LLVM IR semantics.
+* Bulk memory operations (enabled by default, use
+  ``-mno-bulk-memory-opt -mno-bulk-memory`` to disable). ``memory.copy``
+  and ``memory.fill`` instructions are used in the implementation of C
+  ``memcpy`` and ``memset``, and Clang may generate them elsewhere.
+* JS BigInt integration (enabled by default, use the
+  ``-sWASM_BIGINT=0`` :ref:`setting <wasm_bigint>`
+  to disable). This has the effect that Wasm i64 values are passed and returned
+  between Wasm and JS as BigInt values rather than being split by Binaryen into
+  pairs of Numbers.
+* Sign-extension operators (enabled by default, use ``-mno-sign-ext`` to disable).
+
+For the features that are enabled by default (or will be when sufficient
+browser support exists), it's also possible to control them by specifying
+which browser versions you want to target. You can use the
+``-sMIN_FIREFOX_VERSION`` :ref:`setting <min_firefox_version>`
+(and also ``MIN_CHROME_VERSION``, ``MIN_SAFARI_VERSION`` and
+``MIN_NODE_VERSION``). Setting a value lower than the default version will
+disable features not supported by the specified version. Some features (e.g.
+Exception handling and threads) are not enabled by default because they have
+tradeoffs (e.g. binary size costs or restrictions on how the resulting wasm
+can be used such as COEP headers). These are not controlled by the browser
+version flags and must be enabled explicitly.
+See the :ref:`settings <min_firefox_version>` page for details of the default
+browser versions Emscripten targets.
 
-For further info on WebAssembly features supported in various browsers, see the
-`WebAssembly Roadmap <https://webassembly.org/roadmap/>`_
 
 ``.wasm`` files and compilation
 ===============================

site/source/docs/porting/simd.rst

@@ -1,4 +1,4 @@
-.. Porting SIMD code:
+.. _Porting SIMD code:
 
 .. role:: raw-html(raw)
     :format: html