From 078f7b36eef4419be29ad887afbac9963f264784 Mon Sep 17 00:00:00 2001 From: Hsiaoming Yang Date: Fri, 10 Jul 2026 09:49:18 +0900 Subject: [PATCH] docs: fix rst syntax --- .../configuring_emscripten_settings.rst | 20 +- .../docs/building_from_source/index.rst | 12 +- .../toolchain_what_is_needed.rst | 14 +- .../verify_emscripten_environment.rst | 6 +- .../docs/compiling/Building-Projects.rst | 31 ++- .../source/docs/compiling/Deploying-Pages.rst | 14 +- .../Running-html-files-with-emrun.rst | 6 +- site/source/docs/getting_started/FAQ.rst | 51 ++--- .../source/docs/getting_started/downloads.rst | 66 +++--- .../docs/getting_started/test-suite.rst | 14 +- .../docs/optimizing/Optimizing-WebGL.rst | 16 +- site/source/docs/porting/Debugging.rst | 6 +- site/source/docs/porting/asyncify.rst | 34 +-- .../Interacting-with-code.rst | 44 ++-- .../WebIDL-Binder.rst | 18 +- site/source/docs/porting/exceptions.rst | 98 ++++---- .../guidelines/function_pointer_issues.rst | 8 +- .../guidelines/portability_guidelines.rst | 18 +- site/source/docs/porting/simd.rst | 60 ++--- site/source/docs/tools_reference/emcc.rst | 46 ++-- .../tools_reference/settings_reference.rst | 214 +++++++++--------- 21 files changed, 390 insertions(+), 406 deletions(-) diff --git a/site/source/docs/building_from_source/configuring_emscripten_settings.rst b/site/source/docs/building_from_source/configuring_emscripten_settings.rst index 80ebe6fc88930..c55dc027fbda5 100644 --- a/site/source/docs/building_from_source/configuring_emscripten_settings.rst +++ b/site/source/docs/building_from_source/configuring_emscripten_settings.rst @@ -26,12 +26,12 @@ in order to generate one in the default location. 1. Navigate to the directory where you cloned the Emscripten repository. 2. Enter the command: - :: + :: - ./emcc --generate-config + ./emcc --generate-config - You should get a ``An Emscripten settings file has been generated at:`` - message, along with the contents of the config file. + You should get a ``An Emscripten settings file has been generated at:`` + message, along with the contents of the config file. When generating this file Emscripten will make its "best guess" at the correct locations for tools based on the current ``PATH``. @@ -48,12 +48,12 @@ The settings file (``.emscripten``) is created by default within the emscripten directory (alongside ``emcc`` itself). In cases where the emscripten directory is read-only the user's home directory will be used: - - On Linux and macOS this file is named **~/.emscripten**, where ~ is the - user's home directory. +- On Linux and macOS this file is named **~/.emscripten**, where ~ is the + user's home directory. - .. note:: Files with the "." prefix are hidden by default. You may need to change your view settings to find the file. + .. note:: Files with the "." prefix are hidden by default. You may need to change your view settings to find the file. - - On Windows the file can be found at a path like: **C:/Users/yourusername_000/.emscripten**. +- On Windows the file can be found at a path like: **C:/Users/yourusername_000/.emscripten**. Compiler configuration file-format @@ -80,10 +80,10 @@ update the variable ``LLVM_ROOT`` #. Edit the variable ``LLVM_ROOT`` to point to the directory where you built the LLVM binaries, such as: - :: + :: LLVM_ROOT = '/home/ubuntu/a-path/llvm/build/bin' - .. note:: Use forward slashes! + .. note:: Use forward slashes! After setting those paths, run ``emcc`` again. It should again perform the sanity checks to test the specified paths. There are further validation tests available at :ref:`verifying-the-emscripten-environment`. diff --git a/site/source/docs/building_from_source/index.rst b/site/source/docs/building_from_source/index.rst index feffe360c1eb6..a2ca3f130c3a1 100644 --- a/site/source/docs/building_from_source/index.rst +++ b/site/source/docs/building_from_source/index.rst @@ -33,14 +33,12 @@ Building LLVM Build LLVM from the `git repo `_. Include clang and wasm-ld (using something like ``-DLLVM_ENABLE_PROJECTS='lld;clang'``) and the Wasm backend (which is included by default; just don't disable it), following `that project's instructions `_. -For example, something like this can work: +For example, something like this can work:: - :: - - mkdir build - cd build/ - cmake ../llvm -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='lld;clang' -DLLVM_TARGETS_TO_BUILD="host;WebAssembly" -DLLVM_INCLUDE_EXAMPLES=OFF -DLLVM_INCLUDE_TESTS=OFF # -DLLVM_ENABLE_ASSERTIONS=ON - cmake --build . + mkdir build + cd build/ + cmake ../llvm -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='lld;clang' -DLLVM_TARGETS_TO_BUILD="host;WebAssembly" -DLLVM_INCLUDE_EXAMPLES=OFF -DLLVM_INCLUDE_TESTS=OFF # -DLLVM_ENABLE_ASSERTIONS=ON + cmake --build . Then set the environment variable ``EM_LLVM_ROOT`` to ``/build/bin`` (no need to install). diff --git a/site/source/docs/building_from_source/toolchain_what_is_needed.rst b/site/source/docs/building_from_source/toolchain_what_is_needed.rst index 4a35a3d1ccae8..33e7c52b303b8 100644 --- a/site/source/docs/building_from_source/toolchain_what_is_needed.rst +++ b/site/source/docs/building_from_source/toolchain_what_is_needed.rst @@ -22,13 +22,13 @@ Emscripten tools and dependencies In general a complete Emscripten environment requires the following tools. First test to see if they are already installed using the :ref:`instructions below `. - - :term:`Node.js` (18.3.0 or above) - - :term:`Python` (3.8 or above) - - :term:`Java` (1.6.0_31 or later). Java is optional. It can be used to run the java version of term:`Closure Compiler`. - - :term:`Git` client. Git is required if building tools from source. - - :term:`LLVM` (LLVM, including clang and wasm-ld) - - :term:`Binaryen` (Binaryen, including wasm-opt, wasm-emscripten-finalize, etc.) - - The `Emscripten code `_, from GitHub +- :term:`Node.js` (18.3.0 or above) +- :term:`Python` (3.8 or above) +- :term:`Java` (1.6.0_31 or later). Java is optional. It can be used to run the java version of term:`Closure Compiler`. +- :term:`Git` client. Git is required if building tools from source. +- :term:`LLVM` (LLVM, including clang and wasm-ld) +- :term:`Binaryen` (Binaryen, including wasm-opt, wasm-emscripten-finalize, etc.) +- The `Emscripten code `_, from GitHub .. note: 64-bit versions of all needed dependencies are preferred, and may be required if you are building large projects. diff --git a/site/source/docs/building_from_source/verify_emscripten_environment.rst b/site/source/docs/building_from_source/verify_emscripten_environment.rst index 30bef9734a0bd..9ef971c0f3aba 100644 --- a/site/source/docs/building_from_source/verify_emscripten_environment.rst +++ b/site/source/docs/building_from_source/verify_emscripten_environment.rst @@ -89,8 +89,8 @@ Other common problems Other common problems to check for are: - - Errors in the paths in :ref:`.emscripten `. These are less likely if you update the file using :ref:`emsdk `. - - Using older versions of Node or JavaScript engines. Use the default versions for the SDK as listed with :ref:`emsdk list `. - - Using older versions of LLVM. The correct versions come with the SDK, but if you're building the environment from source you should make sure to use the proper version of LLVM (which you can find using the `emscripten-releases DEPS file and history `_; other versions might work, especially close-by ones, but are not tested by us and so not guaranteed to work). +- Errors in the paths in :ref:`.emscripten `. These are less likely if you update the file using :ref:`emsdk `. +- Using older versions of Node or JavaScript engines. Use the default versions for the SDK as listed with :ref:`emsdk list `. +- Using older versions of LLVM. The correct versions come with the SDK, but if you're building the environment from source you should make sure to use the proper version of LLVM (which you can find using the `emscripten-releases DEPS file and history `_; other versions might work, especially close-by ones, but are not tested by us and so not guaranteed to work). If none of the above is helpful, then please :ref:`contact us ` for help. diff --git a/site/source/docs/compiling/Building-Projects.rst b/site/source/docs/compiling/Building-Projects.rst index 752bd8b135518..047d8fad91958 100644 --- a/site/source/docs/compiling/Building-Projects.rst +++ b/site/source/docs/compiling/Building-Projects.rst @@ -283,8 +283,8 @@ Adding more ports The simplest way to add a new port is to put it under the ``contrib`` directory. Basically, the steps are: - * Make sure the port is open source and has a suitable license. - * Read the ``README.md`` file under ``tools/ports/contrib`` which contains more information. +* Make sure the port is open source and has a suitable license. +* Read the ``README.md`` file under ``tools/ports/contrib`` which contains more information. External ports -------------- @@ -378,18 +378,18 @@ Detecting Emscripten in Preprocessor Emscripten provides the following preprocessor macros that can be used to identify the compiler version and platform: - * The preprocessor define ``__EMSCRIPTEN__`` is always defined when compiling programs with Emscripten. - * The preprocessor variables ``__EMSCRIPTEN_MAJOR__``, ``__EMSCRIPTEN_MINOR__`` - and ``__EMSCRIPTEN_TINY__`` are defined in ``emscripten/version.h`` and - specify, as integers, the currently used Emscripten compiler version. - * Emscripten behaves like a variant of Unix, so the preprocessor defines ``unix``, ``__unix`` and ``__unix__`` are always present when compiling code with Emscripten. - * Emscripten uses Clang/LLVM as its underlying codegen compiler, so the preprocessor defines ``__llvm__`` and ``__clang__`` are defined, and the preprocessor defines ``__clang_major__``, ``__clang_minor__`` and ``__clang_patchlevel__`` indicate the version of Clang that is used. - * Clang/LLVM is GCC-compatible, so the preprocessor defines ``__GNUC__``, ``__GNUC_MINOR__`` and ``__GNUC_PATCHLEVEL__`` are also defined to represent the level of GCC compatibility that Clang/LLVM provides. - * The preprocessor string ``__VERSION__`` indicates the GCC compatible version, which is expanded to also show Emscripten version information. - * Likewise, ``__clang_version__`` is present and indicates both Emscripten and LLVM version information. - * Emscripten is a 32-bit platform, so ``size_t`` is a 32-bit unsigned integer, ``__POINTER_WIDTH__=32``, ``__SIZEOF_LONG__=4`` and ``__LONG_MAX__`` equals ``2147483647L``. - * When targeting SSEx SIMD APIs using one of the command line compiler flags ``-msse``, ``-msse2``, ``-msse3``, ``-mssse3``, or ``-msse4.1``, one or more of the preprocessor flags ``__SSE__``, ``__SSE2__``, ``__SSE3__``, ``__SSSE3__``, ``__SSE4_1__`` will be present to indicate available support for these instruction sets. - * If targeting the pthreads multithreading support with the compiler & linker flag ``-pthread``, the preprocessor define ``__EMSCRIPTEN_PTHREADS__`` will be present. +* The preprocessor define ``__EMSCRIPTEN__`` is always defined when compiling programs with Emscripten. +* The preprocessor variables ``__EMSCRIPTEN_MAJOR__``, ``__EMSCRIPTEN_MINOR__`` + and ``__EMSCRIPTEN_TINY__`` are defined in ``emscripten/version.h`` and + specify, as integers, the currently used Emscripten compiler version. +* Emscripten behaves like a variant of Unix, so the preprocessor defines ``unix``, ``__unix`` and ``__unix__`` are always present when compiling code with Emscripten. +* Emscripten uses Clang/LLVM as its underlying codegen compiler, so the preprocessor defines ``__llvm__`` and ``__clang__`` are defined, and the preprocessor defines ``__clang_major__``, ``__clang_minor__`` and ``__clang_patchlevel__`` indicate the version of Clang that is used. +* Clang/LLVM is GCC-compatible, so the preprocessor defines ``__GNUC__``, ``__GNUC_MINOR__`` and ``__GNUC_PATCHLEVEL__`` are also defined to represent the level of GCC compatibility that Clang/LLVM provides. +* The preprocessor string ``__VERSION__`` indicates the GCC compatible version, which is expanded to also show Emscripten version information. +* Likewise, ``__clang_version__`` is present and indicates both Emscripten and LLVM version information. +* Emscripten is a 32-bit platform, so ``size_t`` is a 32-bit unsigned integer, ``__POINTER_WIDTH__=32``, ``__SIZEOF_LONG__=4`` and ``__LONG_MAX__`` equals ``2147483647L``. +* When targeting SSEx SIMD APIs using one of the command line compiler flags ``-msse``, ``-msse2``, ``-msse3``, ``-mssse3``, or ``-msse4.1``, one or more of the preprocessor flags ``__SSE__``, ``__SSE2__``, ``__SSE3__``, ``__SSSE3__``, ``__SSE4_1__`` will be present to indicate available support for these instruction sets. +* If targeting the pthreads multithreading support with the compiler & linker flag ``-pthread``, the preprocessor define ``__EMSCRIPTEN_PTHREADS__`` will be present. Using a compiler wrapper @@ -438,8 +438,7 @@ Troubleshooting ``emmake``/``emconfigure`` should avoid this by setting the env var RANLIB, but a build system might have it hardcoded, or require you to `pass an option `_. -- - The compilation error ``multiply defined symbol`` indicates that the project has linked a particular static library multiple times. The project will need to be changed so that the problem library is linked only once. +- The compilation error ``multiply defined symbol`` indicates that the project has linked a particular static library multiple times. The project will need to be changed so that the problem library is linked only once. .. note:: You can use ``llvm-nm`` to see which symbols are defined in each object file. diff --git a/site/source/docs/compiling/Deploying-Pages.rst b/site/source/docs/compiling/Deploying-Pages.rst index db4419f6e7622..01e86ee398529 100644 --- a/site/source/docs/compiling/Deploying-Pages.rst +++ b/site/source/docs/compiling/Deploying-Pages.rst @@ -82,17 +82,17 @@ To provide the best possible user experience, make sure that the different ways - If a particular browser is known to not be supported, resist the temptation to read ``navigator.userAgent`` field to gate users with that browser, if at all possible. For example, if your page needs WebGL 2 but Safari is known not to support it, do not exclude out Safari users with a following type of check: - .. code:: js + .. code:: js if (navigator.userAgent.indexOf('Safari') != -1) alert('Your browser does not support WebGL 2!'); -but instead, detect the actual errors: + but instead, detect the actual errors: - .. code:: js + .. code:: js if (!canvas.getContext('webgl2')) alert('Your browser does not support WebGL 2!'); // And look for webglcontextcreationerror here for an error reason. -This way the page will be future compatible once support for the particular feature later becomes available. + This way the page will be future compatible once support for the particular feature later becomes available. - Test various failure cases up front by simulating different issues and browser limitations. For example, on Firefox, it is possible to manually disable WebGL 2 by navigating to ``about:config`` and setting the preference ``webgl.enable-webgl2`` to ``false``. This allows you to debug what kind of error reporting your page will present to the user in such a scenario. To disable WebGL support altogether for testing purposes, set the preference ``webgl.disabled`` to ``true``. @@ -108,11 +108,11 @@ This way the page will be future compatible once support for the particular feat - Catch all exceptions that come from within entry points that call to compiled asm.js and WebAssembly code. There are three distinct exception classes that compiled code can throw: - 1. C++ exceptions that are represented by a thrown integer and not caught by the C++ program. This integer points to a memory location in the application heap that contains pointer to the thrown object. + 1. C++ exceptions that are represented by a thrown integer and not caught by the C++ program. This integer points to a memory location in the application heap that contains pointer to the thrown object. - 2. Exceptions caused by Emscripten runtime calling the ``abort()`` function. These correspond to a fatal error that execution of the compiled code cannot recover from. For example, this can occur when calling an invalid function pointer. + 2. Exceptions caused by Emscripten runtime calling the ``abort()`` function. These correspond to a fatal error that execution of the compiled code cannot recover from. For example, this can occur when calling an invalid function pointer. - 3. Traps caused by compiled WebAssembly code. These correspond to fatal errors coming from the WebAssembly VM. This can occur for example when performing an integer division by zero, or when converting a large floating point number to an integer when the float is out of range of the numbers representable by that integer type. + 3. Traps caused by compiled WebAssembly code. These correspond to fatal errors coming from the WebAssembly VM. This can occur for example when performing an integer division by zero, or when converting a large floating point number to an integer when the float is out of range of the numbers representable by that integer type. - Implement a final "catch all" error handler on the page by implementing a ``window.onerror`` script. This will be called as a last resort if no other source handled an exception that was raised on the page. See `window.onerror `_ documentation on MDN. diff --git a/site/source/docs/compiling/Running-html-files-with-emrun.rst b/site/source/docs/compiling/Running-html-files-with-emrun.rst index 8fa5aa56813a4..ed8c02b751783 100644 --- a/site/source/docs/compiling/Running-html-files-with-emrun.rst +++ b/site/source/docs/compiling/Running-html-files-with-emrun.rst @@ -27,13 +27,13 @@ Using *emrun* is simple: #. Rebuild your Emscripten application and add the ``--emrun`` :ref:`linker flag `. - This flag injects code into the generated :ref:`Module` to enable capture of ``stdout``, ``stderr`` and ``exit()``. + This flag injects code into the generated :ref:`Module` to enable capture of ``stdout``, ``stderr`` and ``exit()``. - .. note:: If you skip this step, you can still run any **.html** file with *emrun*, but the capture will not work. + .. note:: If you skip this step, you can still run any **.html** file with *emrun*, but the capture will not work. #. Open a terminal, navigate to the build output directory, and call ``emrun page.html``. - This will spawn a new web server to host the page and launch your default system browser to visit that page. *emrun* will block until the page calls ``exit(returncode)``, after which it will quit back to shell with the given process exit code. + This will spawn a new web server to host the page and launch your default system browser to visit that page. *emrun* will block until the page calls ``exit(returncode)``, after which it will quit back to shell with the given process exit code. Choosing the browser to run diff --git a/site/source/docs/getting_started/FAQ.rst b/site/source/docs/getting_started/FAQ.rst index 1d2653a2bc98f..105a363df2a4e 100644 --- a/site/source/docs/getting_started/FAQ.rst +++ b/site/source/docs/getting_started/FAQ.rst @@ -38,16 +38,16 @@ I tried something: why doesn’t it work? Some general steps that might help figure things out: - * See if the problem happens without optimizations (`-O0`, or not specifying - any optimization level). Without optimizations, emscripten enables many - assertions at compile and runtime, which may catch a problem and display an - error message with a suggestion for how to fix it. - * Search the documentation on this site. - * Check if there is a test for the failing functionality in the - :ref:`Emscripten test suite ` (run ``grep -r`` in - **test/**). They should all pass (with only rare exceptions), so they - provide concrete "known-good" examples of how various options and code are - used. +* See if the problem happens without optimizations (`-O0`, or not specifying + any optimization level). Without optimizations, emscripten enables many + assertions at compile and runtime, which may catch a problem and display an + error message with a suggestion for how to fix it. +* Search the documentation on this site. +* Check if there is a test for the failing functionality in the + :ref:`Emscripten test suite ` (run ``grep -r`` in + **test/**). They should all pass (with only rare exceptions), so they + provide concrete "known-good" examples of how various options and code are + used. Do I need to change my build system to use Emscripten? @@ -97,7 +97,8 @@ Make sure you optimize code by building with ``-O2`` (even more :ref:`aggressive optimization ` is available, at the cost of significantly increased compilation time). -.. note: This is necessary both when compiling each source file, and at link +.. note:: + This is necessary both when compiling each source file, and at link time, which is when Emscripten applies many of its optimizations. For more information see :ref:`Building-Projects` and :ref:`Optimizing-Code`. @@ -519,13 +520,13 @@ there, you should add it to ``EXPORTED_FUNCTIONS`` for compiled code, or ``EXPORTED_RUNTIME_METHODS`` for a runtime method (like ``getValue``). For example, - :: +:: emcc -sEXPORTED_FUNCTIONS=_main,_my_func ... would export a C method ``my_func`` (in addition to ``main``, in this example). And - :: +:: emcc -sEXPORTED_RUNTIME_METHODS=ccall ... @@ -556,15 +557,11 @@ generated code more efficient and compact, but requires minor changes if you used ``Runtime.*`` APIs. You just need to remove the ``Runtime.`` prefix, as those functions are now simple functions in the top scope (an error message in ``-O0`` or builds with assertions enabled with suggest this). In other words, -replace - - :: +replace:: x = Runtime.stackAlloc(10); -with - - :: +with:: x = stackAlloc(10); @@ -582,15 +579,11 @@ This can occur if you have non-trivial strings in ``-s`` argument and are having trouble getting the shell quoting / escaping correct. Using the simpler list form (without quotes, spaces or square brackets) can -sometimes help: - -:: +sometimes help:: emcc a.c -sEXPORTED_RUNTIME_METHODS=foo,bar -It is also possible to use a **response file**, that is, - -:: +It is also possible to use a **response file**, that is,:: emcc a.c -sEXPORTED_RUNTIME_METHODS=@extra.txt @@ -600,18 +593,14 @@ separate lines. How do I specify ``-s`` options in a CMake project? =================================================== -Simple things like this should just work in a ``CMakeLists.txt`` file: - -:: +Simple things like this should just work in a ``CMakeLists.txt`` file:: set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -sUSE_SDL=2") However, some ``-s`` options may require quoting, or the space between ``-s`` and the next argument may confuse CMake, when using things like ``target_link_options``. To avoid those problems, you can use ``-sX=Y`` -notation, that is, without spaces and without square brackets or quotes: - -:: +notation, that is, without spaces and without square brackets or quotes:: # same as before but no space after -s set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -sUSE_SDL=2") diff --git a/site/source/docs/getting_started/downloads.rst b/site/source/docs/getting_started/downloads.rst index 8b06c66ba5f67..fbb9de6b91f5a 100644 --- a/site/source/docs/getting_started/downloads.rst +++ b/site/source/docs/getting_started/downloads.rst @@ -23,7 +23,7 @@ prerequisites. The core Emscripten SDK (emsdk) driver is a Python script. You can get it for the first time with: - :: +:: # Get the emsdk repo git clone https://github.com/emscripten-core/emsdk.git @@ -38,7 +38,7 @@ the first time with: Run the following :ref:`emsdk ` commands to get the latest tools from GitHub and set them as :term:`active `: - :: +:: # Fetch the latest version of the emsdk (not needed the first time you clone) git pull @@ -72,7 +72,7 @@ which is the latest tagged release. That is often what you want. You can also install a specific version by specifying it, for example, - :: +:: ./emsdk install 1.38.45 @@ -96,9 +96,9 @@ Tip-of-tree builds may also be useful if you want to test a feature that just la but didn't reach a release yet. To use a tip-of-tree build, use the ``tot`` target, and note that you must specify the backend explicitly, - :: +:: - # Get a tip-of-tree + # Get a tip-of-tree ./emsdk install tot (In the above examples, we installed the various targets; remember to also @@ -114,8 +114,8 @@ Windows #. Install Python 3.8 or newer. - .. note:: Instead of running emscripten on Windows directly, you can use the - Windows Subsystem for Linux to run it in a Linux environment. + .. note:: Instead of running emscripten on Windows directly, you can use the + Windows Subsystem for Linux to run it in a Linux environment. macOS +++++ @@ -132,18 +132,18 @@ skip those steps. #. Install the *Xcode Command Line Tools*. These are a precondition for *git*. - - Install Xcode from the `macOS App Store `_. - - In **Xcode | Preferences | Downloads**, install *Command Line Tools*. + - Install Xcode from the `macOS App Store `_. + - In **Xcode | Preferences | Downloads**, install *Command Line Tools*. #. Install *git*: - - `Make sure the OS allows installing git `_. - - Install Xcode and the Xcode Command Line Tools (should already have been done). This will provide *git* to the system PATH (see `this stackoverflow post `_). - - Download and install git directly from http://git-scm.com/. + - `Make sure the OS allows installing git `_. + - Install Xcode and the Xcode Command Line Tools (should already have been done). This will provide *git* to the system PATH (see `this stackoverflow post `_). + - Download and install git directly from http://git-scm.com/. #. Install *cmake* if you do not have it yet: - - Download and install latest CMake from `Kitware CMake downloads `_. + - Download and install latest CMake from `Kitware CMake downloads `_. Linux +++++ @@ -152,23 +152,21 @@ Linux interact with Linux package managers. All file changes are done inside the **emsdk/** directory. -- *Python* is not provided by *emsdk*. The user is expected to install this - beforehand with the *system package manager*: +#. *Python* is not provided by *emsdk*. The user is expected to install this + beforehand with the *system package manager*:: - :: + # Install Python + sudo apt-get install python3 - # Install Python - sudo apt-get install python3 + # Install CMake (optional, only needed for tests and building Binaryen or LLVM) + sudo apt-get install cmake - # Install CMake (optional, only needed for tests and building Binaryen or LLVM) - sudo apt-get install cmake +#. *Git* is not installed automatically. Git is only needed if you want to use tools from a development branch. -- *Git* is not installed automatically. Git is only needed if you want to use tools from a development branch. + :: - :: - - # Install git - sudo apt-get install git + # Install git + sudo apt-get install git Verifying the installation @@ -190,19 +188,19 @@ Updating the SDK .. tip:: You only need to install the SDK once! After that you can update to the latest SDK at any time using :ref:`Emscripten SDK (emsdk) `. -Type the following in a command prompt :: +Type the following in a command prompt:: - # Fetch the latest registry of available tools. - ./emsdk update + # Fetch the latest registry of available tools. + ./emsdk update - # Download and install the latest SDK tools. - ./emsdk install latest + # Download and install the latest SDK tools. + ./emsdk install latest - # Set up the compiler configuration to point to the "latest" SDK. - ./emsdk activate latest + # Set up the compiler configuration to point to the "latest" SDK. + ./emsdk activate latest - # Activate PATH and other environment variables in the current terminal - source ./emsdk_env.sh + # Activate PATH and other environment variables in the current terminal + source ./emsdk_env.sh The package manager can do many other maintenance tasks ranging from fetching specific old versions of the SDK through to using the :ref:`versions of the diff --git a/site/source/docs/getting_started/test-suite.rst b/site/source/docs/getting_started/test-suite.rst index ca6ff90ad13ae..2e585f6b94793 100644 --- a/site/source/docs/getting_started/test-suite.rst +++ b/site/source/docs/getting_started/test-suite.rst @@ -51,12 +51,12 @@ test suites, that run tests in more special manner (in particular, in those test it is not possible to say "run the test with a different optimization flag" - that is what the core tests are for). The non-core test suites include - * `other`: Non-core tests running in the shell. - * `browser`: Tests that run in a browser. - * `sockets`: Networking tests that run in a browser. - * `interactive`: Browser tests that are not fully automated, and require user interaction (these should be automated eventually). - * `sanity`: Tests for emscripten setting itself up. This modifies your `.emscripten` file temporarily. - * `benchmark`: Runs benchmarks, measuring speed and code size. +* `other`: Non-core tests running in the shell. +* `browser`: Tests that run in a browser. +* `sockets`: Networking tests that run in a browser. +* `interactive`: Browser tests that are not fully automated, and require user interaction (these should be automated eventually). +* `sanity`: Tests for emscripten setting itself up. This modifies your `.emscripten` file temporarily. +* `benchmark`: Runs benchmarks, measuring speed and code size. The wildcards we mentioned above work for non-core test modes too, for example: @@ -216,7 +216,7 @@ runs them. For even more debugging info, you can set :ref:`debugging-EMCC_DEBUG` which will cause the emscripten compiler itself to output a lot of debug info. This will -also tell the compiler to leave all its temporary files behind after it runs +also tell the compiler to leave all its temporary files behind after it runs (the files go in ``/tmp/emscripten_temp/``): .. code-block:: bash diff --git a/site/source/docs/optimizing/Optimizing-WebGL.rst b/site/source/docs/optimizing/Optimizing-WebGL.rst index 1e0614b908b49..d34a3cb39672d 100644 --- a/site/source/docs/optimizing/Optimizing-WebGL.rst +++ b/site/source/docs/optimizing/Optimizing-WebGL.rst @@ -51,7 +51,7 @@ In WebGL, every single GL function call has some amount of overhead, even those - Consider lazily setting GL state only when it needs to take effect. For example, in the following call stream - .. code:: cpp + .. code:: cpp // First draw glBindBuffer(...); @@ -101,17 +101,17 @@ Avoid GPU-CPU Sync Points The most important aspect of efficient GPU usage is to make sure that the CPU will never need to block on the GPU during render time, and vice versa. These types of stalls create extremely costly CPU-GPU sync points, which lead to poor utilization of both resources. Generally a hint of this type of a scenario happening can be detected by observing overall GPU and CPU utilization rates. If a GPU profiler is claiming that the GPU is idle for large portions of the time, but a CPU profiler is claiming that the CPU in turn is idle, or that certain GL functions take a very long time to complete, it suggests that frames are not being efficiently submitted to the GPU, but GPU-CPU sync(s) occur somewhere during draw call submission. Unfortunately OpenGL specifications do not provide any performance guarantees of which GL calls may cause a stall, so look out for the following behavior and experiment by changing these and reprofiling the effects. - - Avoid creating new GL resources at render time. This means optimizing out calls to ``glGen*()`` and ``glCreate*()`` functions (``glGenTextures()``, ``glGenBuffers()``, ``glCreateShader()`` and so on) at render time. If new resources are needed, try to create and upload them a couple of frames before attempting to render using them. +- Avoid creating new GL resources at render time. This means optimizing out calls to ``glGen*()`` and ``glCreate*()`` functions (``glGenTextures()``, ``glGenBuffers()``, ``glCreateShader()`` and so on) at render time. If new resources are needed, try to create and upload them a couple of frames before attempting to render using them. - - Likewise, do not delete any GL resources that have just been rendered with. The functions ``glDelete*()`` can introduce a full pipeline flush if the driver detects that any of the resources are in use. It is better to delete resources at loading time only. +- Likewise, do not delete any GL resources that have just been rendered with. The functions ``glDelete*()`` can introduce a full pipeline flush if the driver detects that any of the resources are in use. It is better to delete resources at loading time only. - - Never call ``glGetError()`` or ``glCheckFramebufferStatus()`` at render time. These functions should be restricted to be checked at loading time only, since both of these can do a full pipeline sync. +- Never call ``glGetError()`` or ``glCheckFramebufferStatus()`` at render time. These functions should be restricted to be checked at loading time only, since both of these can do a full pipeline sync. - - Similarly, do not call any of the ``glGet*()`` API functions at render time, but query them at startup and loading time, and refer to cached results at render time. +- Similarly, do not call any of the ``glGet*()`` API functions at render time, but query them at startup and loading time, and refer to cached results at render time. - - Try to avoid compiling shaders at render time, both ``glCompileShader()`` and ``glLinkProgram()`` can be extremely slow. +- Try to avoid compiling shaders at render time, both ``glCompileShader()`` and ``glLinkProgram()`` can be extremely slow. - - Do not call ``glReadPixels()`` to copy texture contents back to main memory at render time. If necessary, use the WebGL 2 ``GL_PIXEL_PACK_BUFFER`` binding target instead to copy a GPU surface to an offscreen target first, and only later ``glReadPixels()`` the contents of that surface back to main memory. +- Do not call ``glReadPixels()`` to copy texture contents back to main memory at render time. If necessary, use the WebGL 2 ``GL_PIXEL_PACK_BUFFER`` binding target instead to copy a GPU surface to an offscreen target first, and only later ``glReadPixels()`` the contents of that surface back to main memory. GPU Driver Friendly Memory Access Behavior ========================================== @@ -181,7 +181,7 @@ To migrate from WebGL 1 to WebGL 2, pay attention to the following list of known - The full list of WebGL 1 extensions that were adopted to the core WebGL 2 specification is: - .. code:: cpp + .. code:: cpp ANGLE_instanced_arrays EXT_blend_minmax diff --git a/site/source/docs/porting/Debugging.rst b/site/source/docs/porting/Debugging.rst index c26c410019a4d..8c1fe4fb401ee 100644 --- a/site/source/docs/porting/Debugging.rst +++ b/site/source/docs/porting/Debugging.rst @@ -209,7 +209,7 @@ option. For example: Some important settings are: - - +- .. _debugging-ASSERTIONS: ``ASSERTIONS=1`` is used to enable runtime checks for many types of common @@ -218,7 +218,7 @@ Some important settings are: ``ASSERTIONS=1`` is enabled by default at ``-O0`` and disabled at higher optimization levels, but can be overridden. - - +- .. _debugging-SAFE-HEAP: ``SAFE_HEAP=1`` adds additional memory access checks with a Binaryen pass, @@ -229,7 +229,7 @@ Some important settings are: unless :ref:`alignment issues` are important for your platform. - - +- .. _debugging-STACK_OVERFLOW_CHECK: ``STACK_OVERFLOW_CHECK=1`` adds a runtime magic token value at the end of diff --git a/site/source/docs/porting/asyncify.rst b/site/source/docs/porting/asyncify.rst index 2209d8e990cac..65a294852633a 100644 --- a/site/source/docs/porting/asyncify.rst +++ b/site/source/docs/porting/asyncify.rst @@ -7,22 +7,22 @@ Asynchronous Code Emscripten supports two ways (Asyncify and JSPI) that let **synchronous** C or C++ code interact with **asynchronous** JavaScript. This allows things like: - * A synchronous call in C that yields to the event loop, which - allows browser events to be handled. - * A synchronous call in C that waits for an asynchronous operation in JS to - complete. +* A synchronous call in C that yields to the event loop, which + allows browser events to be handled. +* A synchronous call in C that waits for an asynchronous operation in JS to + complete. In general the two options are very similar, but rely on different underlying mechanisms to work. - * `Asyncify` - Asyncify automatically transforms your compiled code into a - form that can be paused and resumed, and handles pausing and resuming for - you, so that it is asynchronous (hence the name "Asyncify") even though you - wrote it in a normal synchronous way. This works in most environments, but - can cause the Wasm output to be much larger. - * `JSPI` (experimental) - Uses the VM's support for JavaScript Promise - Integration (JSPI) for interacting with async JavaScript. The code size will - remain the same, but support for this feature is still experimental. +* `Asyncify` - Asyncify automatically transforms your compiled code into a + form that can be paused and resumed, and handles pausing and resuming for + you, so that it is asynchronous (hence the name "Asyncify") even though you + wrote it in a normal synchronous way. This works in most environments, but + can cause the Wasm output to be much larger. +* `JSPI` (experimental) - Uses the VM's support for JavaScript Promise + Integration (JSPI) for interacting with async JavaScript. The code size will + remain the same, but support for this feature is still experimental. For more on Asyncify see the `Asyncify introduction blogpost `_ @@ -528,8 +528,8 @@ should just work as they did before. Some minor differences include: - * The Emterpreter had "yielding" as a concept, but it isn't needed in Asyncify. - You can replace ``emscripten_sleep_with_yield()`` calls with ``emscripten_sleep()``. - * The internal JS API is different. See notes above on - ``Asyncify.handleSleep()``, and see ``src/library_async.js`` for more - examples. +* The Emterpreter had "yielding" as a concept, but it isn't needed in Asyncify. + You can replace ``emscripten_sleep_with_yield()`` calls with ``emscripten_sleep()``. +* The internal JS API is different. See notes above on + ``Asyncify.handleSleep()``, and see ``src/library_async.js`` for more + examples. diff --git a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst index 2d3df59fb45c6..28f07a0a28e58 100644 --- a/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst +++ b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst @@ -228,18 +228,18 @@ function, but with a leading ``_``. The parameters you pass to and receive from functions need to be primitive values: - - Integer and floating point numbers can be passed as-is. - - Pointers can be passed as-is also, as they are simply integers in the generated code. - - JavaScript string ``someString`` can be converted to a ``char *`` using ``ptr = stringToNewUTF8(someString)``. +- Integer and floating point numbers can be passed as-is. +- Pointers can be passed as-is also, as they are simply integers in the generated code. +- JavaScript string ``someString`` can be converted to a ``char *`` using ``ptr = stringToNewUTF8(someString)``. - .. note:: The conversion to a pointer allocates memory, which needs to be - freed up via a call to ``free(ptr)`` afterwards (``_free`` in JavaScript side) - - - ``char *`` received from C/C++ can be converted to a JavaScript string using :js:func:`UTF8ToString`. + .. note:: The conversion to a pointer allocates memory, which needs to be + freed up via a call to ``free(ptr)`` afterwards (``_free`` in JavaScript side) - +- ``char *`` received from C/C++ can be converted to a JavaScript string using :js:func:`UTF8ToString`. - There are other convenience functions for converting strings and encodings - in :ref:`preamble-js`. - - Other values can be passed via :cpp:class:`emscripten::val`. Check out examples - on :ref:`as_handle and take_ownership methods `. + There are other convenience functions for converting strings and encodings + in :ref:`preamble-js`. +- Other values can be passed via :cpp:class:`emscripten::val`. Check out examples + on :ref:`as_handle and take_ownership methods `. .. _interacting-with-code-call-javascript-from-native: @@ -308,9 +308,9 @@ amount of overhead.) You can also send values from C into JavaScript inside :c:macro:`EM_ASM`, for example:: - EM_ASM({ - console.log('I received: ' + $0); - }, 100); + EM_ASM({ + console.log('I received: ' + $0); + }, 100); This will show ``I received: 100``. @@ -360,7 +360,7 @@ used in many of Emscripten's libraries, like SDL1 and OpenGL. You can use it to write your own APIs to call from C/C++. To do this you define the interface, decorating with ``extern`` to mark the methods in the API as external symbols. You can then implement the symbols in JavaScript by simply -adding their definition to one of the `core JS library`_ files. Undefined +adding their definition to one of the `core JS library`_ files. Undefined native symbols will be resolved by looking for them in JavaScript library files. The `core JS library`_ files are where you will find Emscripten internals. For @@ -630,12 +630,12 @@ The LLVM Wasm backend requires a Wasm function signature string when using string represents a type. The first character represents the return type of a function, and remaining characters are for parameter types. - - ``'v'``: void type - - ``'i'``: 32-bit integer type - - ``'j'``: 64-bit integer type (see note below) - - ``'f'``: 32-bit float type - - ``'d'``: 64-bit float type - - ``'p'``: 32-bit or 64-bit pointer (MEMORY64) +- ``'v'``: void type +- ``'i'``: 32-bit integer type +- ``'j'``: 64-bit integer type (see note below) +- ``'f'``: 32-bit float type +- ``'d'``: 64-bit float type +- ``'p'``: 32-bit or 64-bit pointer (MEMORY64) For example, if you add a function that takes an integer and does not return anything, the signature is ``'vi'``. @@ -656,10 +656,10 @@ a 53 bit (double) and returns an integer error code: .. code-block:: javascript - _set_file_size__i53abi: true, // Handle 64-bit + _set_file_size__i53abi: true, // Handle 64-bit _set_file_size__sig: 'iij', // Function signature _set_file_size: function(handle, size) { ... return error; } - + Using ``-sWASM_BIGINT`` when linking is an alternative method of handling 64-bit types in libraries. ```Number()``` may be needed on the JavaScript side to convert it to a usable value. See `settings reference `_. diff --git a/site/source/docs/porting/connecting_cpp_and_javascript/WebIDL-Binder.rst b/site/source/docs/porting/connecting_cpp_and_javascript/WebIDL-Binder.rst index 81857db241d7a..033dc752106f5 100644 --- a/site/source/docs/porting/connecting_cpp_and_javascript/WebIDL-Binder.rst +++ b/site/source/docs/porting/connecting_cpp_and_javascript/WebIDL-Binder.rst @@ -63,8 +63,8 @@ The following IDL file can be used to describe them: The mapping between the IDL definition and the C++ is fairly obvious. The main things to notice are: - - The IDL class definitions include a function returning ``void`` that has the same name as the interface. This constructor allows you to create the object from JavaScript, and must be defined in IDL even if the C++ uses the default constructor (see ``Foo`` above). - - The type names in WebIDL are not identical to those in C++ (for example, ``int`` maps to ``long`` above). For more information about the mappings see :ref:`webidl-binder-type-name`. +- The IDL class definitions include a function returning ``void`` that has the same name as the interface. This constructor allows you to create the object from JavaScript, and must be defined in IDL even if the C++ uses the default constructor (see ``Foo`` above). +- The type names in WebIDL are not identical to those in C++ (for example, ``int`` maps to ``long`` above). For more information about the mappings see :ref:`webidl-binder-type-name`. .. note:: ``structs`` are defined in the same way as the classes above — using the ``interface`` keyword. @@ -89,12 +89,12 @@ To use the glue code files (``glue.cpp`` and ``glue.js``) in a project: #. Add ``--post-js glue.js`` in your final *emcc* command. The :ref:`post-js ` option adds the glue code at the end of the compiled output. #. Create a file called something like **my_glue_wrapper.cpp** to ``#include`` the headers of the classes you are binding and *glue.cpp*. This might have the following content: - .. code-block:: cpp + .. code-block:: cpp - #include <...> // Where "..." represents the headers for the classes we are binding. - #include + #include <...> // Where "..." represents the headers for the classes we are binding. + #include - .. note:: The C++ glue code emitted by the *bindings generator* does not include the headers for the classes it binds because they are not present in the Web IDL file. The step above makes these available to the glue code. Another alternative would be to include the headers at the top of **glue.cpp**, but then they would be overwritten every time the IDL file is recompiled. + .. note:: The C++ glue code emitted by the *bindings generator* does not include the headers for the classes it binds because they are not present in the Web IDL file. The step above makes these available to the glue code. Another alternative would be to include the headers at the top of **glue.cpp**, but then they would be overwritten every time the IDL file is recompiled. #. Add **my_glue_wrapper.cpp** to the final *emcc* command. @@ -103,7 +103,7 @@ The final *emcc* command includes both the C++ and JavaScript glue code, which a .. code-block:: bash - emcc my_classes.cpp my_glue_wrapper.cpp --post-js glue.js -o output.js + emcc my_classes.cpp my_glue_wrapper.cpp --post-js glue.js -o output.js The output now contains everything needed to use the C++ classes through JavaScript. @@ -172,7 +172,7 @@ Attributes Object attributes are defined in IDL using the ``attribute`` keyword. These can then be accessed in JavaScript using either ``get_foo()``/``set_foo()`` accessor methods, or directly as a property of the object. .. code-block:: cpp - + // C++ int attr; @@ -210,7 +210,7 @@ Undecorated argument and return values of a custom type in the IDL are assumed t // WebIDL MyClass process(MyClass input); - + This assumption isn't true for base types like void,int,bool,DOMString,etc. References should be decorated using ``[Ref]``: diff --git a/site/source/docs/porting/exceptions.rst b/site/source/docs/porting/exceptions.rst index cfd96b506d7fc..ae3b715e60389 100644 --- a/site/source/docs/porting/exceptions.rst +++ b/site/source/docs/porting/exceptions.rst @@ -170,52 +170,52 @@ See :ref:`using-exceptions-and-setjmp-longjmp-together`. Limitations regarding std::terminate() ====================================== - * Currently `std::set_terminate - `_ is NOT supported - when a thrown exception does not have a matching handler and unwinds all the - stack up to the topmost caller and crashes the program, i.e., there is no - ``catch`` that catches it and the callers are not marked as ``noexcept``. - This applies to both Emscripten-style and WebAssembly exceptions. That - functionality requires `two-phase exception handling - `_, which neither - supports. So the following program does NOT print ``my set_terminate``: - - .. code-block:: cpp - - #include - #include - - int main() { - std::set_terminate([] { - std::cerr << "my set_terminate" << std::endl; - std::abort(); - }); - throw 3; - } - - * When the exception handling encounters a termination condition, libc++abi - spec says we call `__cxa_begin_catch()` to mark the exception as handled and - then call `std::terminate()`. But currently Wasm EH does not support calling - `__cxa_begin_catch()`. So the following program prints ``exception_ptr is - null``, where it is supposed to print ``exception_ptr is NOT null``; note - that the use of ``noexcept`` here means that the ``throw 3`` will turn into - a termination condition. - - .. code-block:: cpp - - #include - #include - - int main() noexcept { - std::set_terminate([] { - auto ptr = std::current_exception(); - if (ptr) - std::cerr << "exception_ptr is NOT null" << std::endl; - else - std::cerr << "exception_ptr is null" << std::endl; - std::abort(); - }); - throw 3; - } - - This can possibly be supported in the future. +* Currently `std::set_terminate + `_ is NOT supported + when a thrown exception does not have a matching handler and unwinds all the + stack up to the topmost caller and crashes the program, i.e., there is no + ``catch`` that catches it and the callers are not marked as ``noexcept``. + This applies to both Emscripten-style and WebAssembly exceptions. That + functionality requires `two-phase exception handling + `_, which neither + supports. So the following program does NOT print ``my set_terminate``: + + .. code-block:: cpp + + #include + #include + + int main() { + std::set_terminate([] { + std::cerr << "my set_terminate" << std::endl; + std::abort(); + }); + throw 3; + } + +* When the exception handling encounters a termination condition, libc++abi + spec says we call `__cxa_begin_catch()` to mark the exception as handled and + then call `std::terminate()`. But currently Wasm EH does not support calling + `__cxa_begin_catch()`. So the following program prints ``exception_ptr is + null``, where it is supposed to print ``exception_ptr is NOT null``; note + that the use of ``noexcept`` here means that the ``throw 3`` will turn into + a termination condition. + + .. code-block:: cpp + + #include + #include + + int main() noexcept { + std::set_terminate([] { + auto ptr = std::current_exception(); + if (ptr) + std::cerr << "exception_ptr is NOT null" << std::endl; + else + std::cerr << "exception_ptr is null" << std::endl; + std::abort(); + }); + throw 3; + } + + This can possibly be supported in the future. diff --git a/site/source/docs/porting/guidelines/function_pointer_issues.rst b/site/source/docs/porting/guidelines/function_pointer_issues.rst index 23c181d30ebbd..787d67d3150fa 100644 --- a/site/source/docs/porting/guidelines/function_pointer_issues.rst +++ b/site/source/docs/porting/guidelines/function_pointer_issues.rst @@ -48,7 +48,7 @@ The ``SAFE_HEAP`` and ``ASSERTION`` options can catch some of these errors at ru You can get compiler errors for some of these problems with - :: +:: -Werror=cast-function-type @@ -57,9 +57,9 @@ Working around function pointer issues There are three solutions to this problem (the second is preferred): - - Cast the function pointer back to the correct type before it is called. This is problematic because it requires that the caller knows the original type. - - Manually write an adapter function that does not need to be cast, and calls the original function. For example, it might ignore a parameter, and in that way bridge between the different function pointer types. - - Use ``EMULATE_FUNCTION_POINTER_CASTS``. When you build with ``-sEMULATE_FUNCTION_POINTER_CASTS``, Emscripten emits code to emulate function pointer casts at runtime, adding extra arguments/dropping them/changing their type/adding or dropping a return type/etc. This can add significant runtime overhead, so it is not recommended, but is worth trying. +- Cast the function pointer back to the correct type before it is called. This is problematic because it requires that the caller knows the original type. +- Manually write an adapter function that does not need to be cast, and calls the original function. For example, it might ignore a parameter, and in that way bridge between the different function pointer types. +- Use ``EMULATE_FUNCTION_POINTER_CASTS``. When you build with ``-sEMULATE_FUNCTION_POINTER_CASTS``, Emscripten emits code to emulate function pointer casts at runtime, adding extra arguments/dropping them/changing their type/adding or dropping a return type/etc. This can add significant runtime overhead, so it is not recommended, but is worth trying. For a real-world example, consider the code below: diff --git a/site/source/docs/porting/guidelines/portability_guidelines.rst b/site/source/docs/porting/guidelines/portability_guidelines.rst index 5f16a37307bea..c7989008e11f5 100644 --- a/site/source/docs/porting/guidelines/portability_guidelines.rst +++ b/site/source/docs/porting/guidelines/portability_guidelines.rst @@ -11,21 +11,21 @@ This section explains what types of code are non-portable (or more difficult to Current Web limitations ======================= -- Multithreading depends on SharedArrayBuffer, which is still being standardized and implemented by browsers. Emscripten has working support for threads, which you can try in development browsers by setting the proper preference. -- SIMD is also in the process of standardization and implementation. +- Multithreading depends on SharedArrayBuffer, which is still being standardized and implemented by browsers. Emscripten has working support for threads, which you can try in development browsers by setting the proper preference. +- SIMD is also in the process of standardization and implementation. Code that cannot be compiled ============================ The following types of code would need to be re-written in order to work with Emscripten. (While in theory it might be possible for Emscripten to work around these issues using emulation, it would be very slow.) -- Code relying on a big-endian architecture. Emscripten-compiled code currently requires a little-endian host to run on, which accounts for 99% of machines connected to the internet. This is because JavaScript typed arrays (used for views on memory) obey the host byte ordering and LLVM needs to know which endianness to target. -- Code that uses low-level features of the native environment, for example native stack manipulation in conjunction with ``setjmp``/``longjmp`` (we support proper ``setjmp``/``longjmp``, i.e., jumping down the stack, but not jumping up to an unwound stack, which is undefined behavior). -- Code that scans registers or the stack. This won't work because a variable in a register or on the stack may be held in a JavaScript local variable (which cannot be scanned). +- Code relying on a big-endian architecture. Emscripten-compiled code currently requires a little-endian host to run on, which accounts for 99% of machines connected to the internet. This is because JavaScript typed arrays (used for views on memory) obey the host byte ordering and LLVM needs to know which endianness to target. +- Code that uses low-level features of the native environment, for example native stack manipulation in conjunction with ``setjmp``/``longjmp`` (we support proper ``setjmp``/``longjmp``, i.e., jumping down the stack, but not jumping up to an unwound stack, which is undefined behavior). +- Code that scans registers or the stack. This won't work because a variable in a register or on the stack may be held in a JavaScript local variable (which cannot be scanned). .. note:: Code of this type might be used for conservative garbage collection. You can do conservative scanning when there is no other code on the stack, e.g. from an iteration of the main event loop. Other solutions include the SpillPointers pass in Binaryen. -- Code with architecture-specific inline assembly (like an ``asm()`` containing x86 code) is not portable. That code would need to be replaced with portable C or C++. Sometimes a codebase will have both portable code and optional inline assembly as an optimization, so you might find an option to disable the inline assembly. +- Code with architecture-specific inline assembly (like an ``asm()`` containing x86 code) is not portable. That code would need to be replaced with portable C or C++. Sometimes a codebase will have both portable code and optional inline assembly as an optimization, so you might find an option to disable the inline assembly. Code that compiles but might run slowly @@ -35,13 +35,13 @@ Code that compiles but might run slowly The following types of code will compile, but may not run as fast as expected: -- In asm.js (but not WebAssembly), 64-bit ``int`` variables. Mathematical operations (+, -, \*, /) are slow because they are emulated (bitwise operations are reasonably fast). JavaScript does not have a native 64-bit ``int`` type so this is unavoidable. -- C++ Exceptions. In JavaScript such code generally makes the JavaScript engine turn off various optimizations. For that reason exceptions are turned off by default in ``-O1`` and above. To re-enable them, run *emcc* with ``-sDISABLE_EXCEPTION_CATCHING=0`` (see `src/settings.js `_). +- In asm.js (but not WebAssembly), 64-bit ``int`` variables. Mathematical operations (+, -, \*, /) are slow because they are emulated (bitwise operations are reasonably fast). JavaScript does not have a native 64-bit ``int`` type so this is unavoidable. +- C++ Exceptions. In JavaScript such code generally makes the JavaScript engine turn off various optimizations. For that reason exceptions are turned off by default in ``-O1`` and above. To re-enable them, run *emcc* with ``-sDISABLE_EXCEPTION_CATCHING=0`` (see `src/settings.js `_). - ``setjmp`` also prevents :term:`relooping` around it, forcing us to emulate control flow using a less efficient approach. Other issues ============ -- Code that relies on x86 alignment behavior. x86 allows unaligned reads and writes (so for example you can read a 16-bit value from a non-even address), but other architectures do not (32-bit ARM will raise ``SIGILL``). For asm.js loads and stores are forced to aligned offsets; for WebAssembly unaligned loads and stores will work but may be slow depending on the underlying CPU. If you build your code with ``SAFE_HEAP=1`` then you will get a clear runtime exception, see :ref:`Debugging`. +- Code that relies on x86 alignment behavior. x86 allows unaligned reads and writes (so for example you can read a 16-bit value from a non-even address), but other architectures do not (32-bit ARM will raise ``SIGILL``). For asm.js loads and stores are forced to aligned offsets; for WebAssembly unaligned loads and stores will work but may be slow depending on the underlying CPU. If you build your code with ``SAFE_HEAP=1`` then you will get a clear runtime exception, see :ref:`Debugging`. diff --git a/site/source/docs/porting/simd.rst b/site/source/docs/porting/simd.rst index 94b4c18f78ff9..6c2296a3bbca5 100644 --- a/site/source/docs/porting/simd.rst +++ b/site/source/docs/porting/simd.rst @@ -47,24 +47,24 @@ WebAssembly SIMD Intrinsics LLVM maintains a WebAssembly SIMD Intrinsics header file that is provided with Emscripten, and adds type definitions for the different supported vector types. - .. code-block:: cpp - - #include - #include - - int main() { - #ifdef __wasm_simd128__ - v128_t v1 = wasm_f32x4_make(1.2f, 3.4f, 5.6f, 7.8f); - v128_t v2 = wasm_f32x4_make(2.1f, 4.3f, 6.5f, 8.7f); - v128_t v3 = wasm_f32x4_add(v1, v2); - // Prints "v3: [3.3, 7.7, 12.1, 16.5]" - printf("v3: [%.1f, %.1f, %.1f, %.1f]\n", - wasm_f32x4_extract_lane(v3, 0), - wasm_f32x4_extract_lane(v3, 1), - wasm_f32x4_extract_lane(v3, 2), - wasm_f32x4_extract_lane(v3, 3)); - #endif - } +.. code-block:: cpp + + #include + #include + + int main() { + #ifdef __wasm_simd128__ + v128_t v1 = wasm_f32x4_make(1.2f, 3.4f, 5.6f, 7.8f); + v128_t v2 = wasm_f32x4_make(2.1f, 4.3f, 6.5f, 8.7f); + v128_t v3 = wasm_f32x4_add(v1, v2); + // Prints "v3: [3.3, 7.7, 12.1, 16.5]" + printf("v3: [%.1f, %.1f, %.1f, %.1f]\n", + wasm_f32x4_extract_lane(v3, 0), + wasm_f32x4_extract_lane(v3, 1), + wasm_f32x4_extract_lane(v3, 2), + wasm_f32x4_extract_lane(v3, 3)); + #endif + } The Wasm SIMD header can be browsed online at `wasm_simd128.h `_. @@ -78,13 +78,13 @@ Limitations and behavioral differences When porting native SIMD code, it should be noted that because of portability concerns, the WebAssembly SIMD specification does not expose access to all of the native x86/ARM SIMD instructions. In particular the following changes exist: - - Emscripten does not support x86 or any other native inline SIMD assembly or building .s assembly files, so all code should be written to use SIMD intrinsic functions or compiler vector extensions. +- Emscripten does not support x86 or any other native inline SIMD assembly or building .s assembly files, so all code should be written to use SIMD intrinsic functions or compiler vector extensions. - - WebAssembly SIMD does not have control over managing floating point rounding modes or handling denormals. +- WebAssembly SIMD does not have control over managing floating point rounding modes or handling denormals. - - Cache line prefetch instructions are not available, and calls to these functions will compile, but are treated as no-ops. +- Cache line prefetch instructions are not available, and calls to these functions will compile, but are treated as no-ops. - - Asymmetric memory fence operations are not available, but will be implemented as fully synchronous memory fences when SharedArrayBuffer is enabled (-pthread) or as no-ops when multithreading is not enabled (the default). +- Asymmetric memory fence operations are not available, but will be implemented as fully synchronous memory fences when SharedArrayBuffer is enabled (-pthread) or as no-ops when multithreading is not enabled (the default). SIMD-related bug reports are tracked in the `Emscripten bug tracker with the label SIMD `_. @@ -110,7 +110,7 @@ When developing SIMD code to use WebAssembly SIMD, implementors should be aware * - i8x16.[shl|shr_s|shr_u] - x86 - Included for orthogonality, these instructions have no equivalent x86 instruction and are emulated with `5-11 x86 instructions in v8 `_ (i.e. using 16x8 shifts). - + * - i64x2.shr_s - x86 - Included for orthogonality, this instruction has no equivalent x86 instruction and is emulated with `6-12 x86 instructions in v8 `_. @@ -1401,7 +1401,7 @@ status **.js** : JavaScript (+ separate **.wasm** file if emitting WebAssembly). (default) - - **.mjs** : ES6 JavaScript module (+ separate **.wasm** file if emitting WebAssembly). - - **.html** : HTML + separate JavaScript file (**.js**; + separate **.wasm** file if emitting WebAssembly). - - **.wasm** : WebAssembly without JavaScript support code ("standalone Wasm"; this enables ``STANDALONE_WASM``). + - **.js** : JavaScript (+ separate **.wasm** file if emitting WebAssembly). (default) + - **.mjs** : ES6 JavaScript module (+ separate **.wasm** file if emitting WebAssembly). + - **.html** : HTML + separate JavaScript file (**.js**; + separate **.wasm** file if emitting WebAssembly). + - **.wasm** : WebAssembly without JavaScript support code ("standalone Wasm"; this enables ``STANDALONE_WASM``). These rules only apply when linking. When compiling to object code (See `-c` below) the name of the output file is irrelevant. @@ -592,22 +592,22 @@ Environment variables ===================== *emcc* is affected by several environment variables, as listed below: - - ``EMMAKEN_JUST_CONFIGURE`` [other] - - ``EMCC_AUTODEBUG`` [compile+link] - - ``EMCC_CFLAGS`` [compile+link] - - ``EMCC_CORES`` [general] - - ``EMCC_DEBUG`` [general] - - ``EMCC_DEBUG_SAVE`` [general] - - ``EMCC_FORCE_STDLIBS`` [link] - - ``EMCC_ONLY_FORCED_STDLIBS`` [link] - - ``EMCC_LOCAL_PORTS`` [compile+link] - - ``EMCC_CLOSURE_ARGS`` [link] arguments to be passed to *Closure Compiler* - - ``EMCC_STRICT`` [general] - - ``EMCC_SKIP_SANITY_CHECK`` [general] - - ``EM_IGNORE_SANITY`` [general] - - ``EM_CONFIG`` [general] - - ``EM_LLVM_ROOT`` [compile+link] - - ``_EMCC_CCACHE`` [general] Internal setting that is set to 1 by emsdk when integrating with ccache compiler frontend +- ``EMMAKEN_JUST_CONFIGURE`` [other] +- ``EMCC_AUTODEBUG`` [compile+link] +- ``EMCC_CFLAGS`` [compile+link] +- ``EMCC_CORES`` [general] +- ``EMCC_DEBUG`` [general] +- ``EMCC_DEBUG_SAVE`` [general] +- ``EMCC_FORCE_STDLIBS`` [link] +- ``EMCC_ONLY_FORCED_STDLIBS`` [link] +- ``EMCC_LOCAL_PORTS`` [compile+link] +- ``EMCC_CLOSURE_ARGS`` [link] arguments to be passed to *Closure Compiler* +- ``EMCC_STRICT`` [general] +- ``EMCC_SKIP_SANITY_CHECK`` [general] +- ``EM_IGNORE_SANITY`` [general] +- ``EM_CONFIG`` [general] +- ``EM_LLVM_ROOT`` [compile+link] +- ``_EMCC_CCACHE`` [general] Internal setting that is set to 1 by emsdk when integrating with ccache compiler frontend Search for 'os.environ' in `emcc.py `_ to see how these are used. The most interesting is possibly ``EMCC_DEBUG``, which forces the compiler to dump its build and temporary files to a temporary directory where they can be reviewed. diff --git a/site/source/docs/tools_reference/settings_reference.rst b/site/source/docs/tools_reference/settings_reference.rst index cca2746b2f0ab..d02a931bfdd5e 100644 --- a/site/source/docs/tools_reference/settings_reference.rst +++ b/site/source/docs/tools_reference/settings_reference.rst @@ -126,19 +126,19 @@ MALLOC What malloc()/free() to use, out of: - - dlmalloc - a powerful general-purpose malloc - - emmalloc - a simple and compact malloc designed for emscripten - - emmalloc-debug - use emmalloc and add extra assertion checks - - emmalloc-memvalidate - use emmalloc with assertions+heap consistency - checking. - - emmalloc-verbose - use emmalloc with assertions + verbose logging. - - emmalloc-memvalidate-verbose - use emmalloc with assertions + heap - consistency checking + verbose logging. - - mimalloc - a powerful multithreaded allocator. This is recommended in - large applications that have malloc() contention, but it is - larger and uses more memory. - - none - no malloc() implementation is provided, but you must implement - malloc() and free() yourself. +- dlmalloc - a powerful general-purpose malloc +- emmalloc - a simple and compact malloc designed for emscripten +- emmalloc-debug - use emmalloc and add extra assertion checks +- emmalloc-memvalidate - use emmalloc with assertions+heap consistency + checking. +- emmalloc-verbose - use emmalloc with assertions + verbose logging. +- emmalloc-memvalidate-verbose - use emmalloc with assertions + heap + consistency checking + verbose logging. +- mimalloc - a powerful multithreaded allocator. This is recommended in + large applications that have malloc() contention, but it is + larger and uses more memory. +- none - no malloc() implementation is provided, but you must implement + malloc() and free() yourself. dlmalloc is necessary for split memory and other special modes, and will be used automatically in those cases. @@ -2841,9 +2841,9 @@ API is used otherwise XMLHttpRequest is used. Both modes generally support the same API, but there are some key differences: - - XHR supports synchronous requests - - XHR supports overriding mime types - - Fetch supports streaming data using the 'onprogress' callback +- XHR supports synchronous requests +- XHR supports overriding mime types +- Fetch supports streaming data using the 'onprogress' callback If set to a value of 2, only the DOM Fetch backend will be used. This should only be used in testing. @@ -3533,15 +3533,15 @@ The following settings have been proposed for removal from emscripten. These se still function but may be removed in a future version. If your project is using one of these settings please open a bug (or reply to one of the existing bugs). - - ``RUNTIME_LINKED_LIBS``: you can simply list the libraries directly on the commandline now - - ``CLOSURE_WARNINGS``: use -Wclosure/-Wno-closure instead - - ``LEGALIZE_JS_FFI``: to disable JS type legalization use `-sWASM_BIGINT` or `-sSTANDALONE_WASM` - - ``ASYNCIFY_EXPORTS``: please use JSPI_EXPORTS instead - - ``LINKABLE``: under consideration for removal (https://github.com/emscripten-core/emscripten/issues/25262) - - ``EXPORT_EXCEPTION_HANDLING_HELPERS``: getExceptionMessage is exported anyway when ASSERTIONS or EXCEPTION_STACK_TRACES is set, which are set by default at -O0. At -O1 or above, you can export it separately by -sEXPORTED_RUNTIME_METHODS=getExceptionMessage,decrementExceptionRefcount. - - ``DETERMINISTIC``: under consideration for removal (https://github.com/emscripten-core/emscripten/issues/26647) - - ``USE_PTHREADS``: prefer the standard -pthread flag - - ``MEMORY64``: prefer the standard -m64 or --target=wasm64 flags +- ``RUNTIME_LINKED_LIBS``: you can simply list the libraries directly on the commandline now +- ``CLOSURE_WARNINGS``: use -Wclosure/-Wno-closure instead +- ``LEGALIZE_JS_FFI``: to disable JS type legalization use `-sWASM_BIGINT` or `-sSTANDALONE_WASM` +- ``ASYNCIFY_EXPORTS``: please use JSPI_EXPORTS instead +- ``LINKABLE``: under consideration for removal (https://github.com/emscripten-core/emscripten/issues/25262) +- ``EXPORT_EXCEPTION_HANDLING_HELPERS``: getExceptionMessage is exported anyway when ASSERTIONS or EXCEPTION_STACK_TRACES is set, which are set by default at -O0. At -O1 or above, you can export it separately by -sEXPORTED_RUNTIME_METHODS=getExceptionMessage,decrementExceptionRefcount. +- ``DETERMINISTIC``: under consideration for removal (https://github.com/emscripten-core/emscripten/issues/26647) +- ``USE_PTHREADS``: prefer the standard -pthread flag +- ``MEMORY64``: prefer the standard -m64 or --target=wasm64 flags .. _legacy-settings: @@ -3552,85 +3552,85 @@ Legacy Settings The following settings no longer have any effect but are still accepted by emscripten for backwards compatibility with older versions: - - ``BINARYEN``: Valid values: WASM - - ``TOTAL_STACK``: Valid values: STACK_SIZE - - ``BINARYEN_ASYNC_COMPILATION``: Valid values: WASM_ASYNC_COMPILATION - - ``UNALIGNED_MEMORY``: forced unaligned memory not supported in fastcomp (Valid values: [0]) - - ``FORCE_ALIGNED_MEMORY``: forced aligned memory is not supported in fastcomp (Valid values: [0]) - - ``PGO``: pgo no longer supported (Valid values: [0]) - - ``QUANTUM_SIZE``: altering the QUANTUM_SIZE is not supported (Valid values: [4]) - - ``FUNCTION_POINTER_ALIGNMENT``: Starting from Emscripten 1.37.29, no longer available (https://github.com/emscripten-core/emscripten/pull/6091) (Valid values: [2]) - - ``RESERVED_FUNCTION_POINTERS``: Valid values: ALLOW_TABLE_GROWTH - - ``BUILD_AS_SHARED_LIB``: Starting from Emscripten 1.38.16, no longer available (https://github.com/emscripten-core/emscripten/pull/7433) (Valid values: [0]) - - ``SAFE_SPLIT_MEMORY``: Starting from Emscripten 1.38.19, SAFE_SPLIT_MEMORY codegen is no longer available (https://github.com/emscripten-core/emscripten/pull/7465) (Valid values: [0]) - - ``SPLIT_MEMORY``: Starting from Emscripten 1.38.19, SPLIT_MEMORY codegen is no longer available (https://github.com/emscripten-core/emscripten/pull/7465) (Valid values: [0]) - - ``BINARYEN_METHOD``: Starting from Emscripten 1.38.23, Emscripten now always builds either to Wasm (-sWASM - default), or to JavaScript (-sWASM=0), other methods are not supported (https://github.com/emscripten-core/emscripten/pull/7836) (Valid values: ['native-wasm']) - - ``BINARYEN_TRAP_MODE``: The wasm backend does not support a trap mode (it always clamps, in effect) (Valid values: [-1]) - - ``PRECISE_I64_MATH``: Starting from Emscripten 1.38.26, PRECISE_I64_MATH is always enabled (https://github.com/emscripten-core/emscripten/pull/7935) (Valid values: [1, 2]) - - ``MEMFS_APPEND_TO_TYPED_ARRAYS``: Starting from Emscripten 1.38.26, MEMFS_APPEND_TO_TYPED_ARRAYS=0 is no longer supported. MEMFS no longer supports using JS arrays for file data (https://github.com/emscripten-core/emscripten/pull/7918) (Valid values: [1]) - - ``ERROR_ON_MISSING_LIBRARIES``: missing libraries are always an error now (Valid values: [1]) - - ``EMITTING_JS``: The new STANDALONE_WASM flag replaces this (replace EMITTING_JS=0 with STANDALONE_WASM=1) (Valid values: [1]) - - ``SKIP_STACK_IN_SMALL``: SKIP_STACK_IN_SMALL is no longer needed as the backend can optimize it directly (Valid values: [0, 1]) - - ``SAFE_STACK``: Replace SAFE_STACK=1 with STACK_OVERFLOW_CHECK=2 (Valid values: [0]) - - ``MEMORY_GROWTH_STEP``: Valid values: MEMORY_GROWTH_LINEAR_STEP - - ``ELIMINATE_DUPLICATE_FUNCTIONS``: Duplicate function elimination for wasm is handled automatically by binaryen (Valid values: [0, 1]) - - ``ELIMINATE_DUPLICATE_FUNCTIONS_DUMP_EQUIVALENT_FUNCTIONS``: Duplicate function elimination for wasm is handled automatically by binaryen (Valid values: [0]) - - ``ELIMINATE_DUPLICATE_FUNCTIONS_PASSES``: Duplicate function elimination for wasm is handled automatically by binaryen (Valid values: [5]) - - ``WASM_OBJECT_FILES``: For LTO, use -flto or -fto=thin instead. Otherwise, Wasm object files are the default (Valid values: [1]) - - ``TOTAL_MEMORY``: Valid values: INITIAL_MEMORY - - ``WASM_MEM_MAX``: Valid values: MAXIMUM_MEMORY - - ``BINARYEN_MEM_MAX``: Valid values: MAXIMUM_MEMORY - - ``BINARYEN_PASSES``: Use BINARYEN_EXTRA_PASSES to add additional passes (Valid values: ['']) - - ``SWAPPABLE_ASM_MODULE``: Fully swappable asm modules are no longer supported (Valid values: [0]) - - ``ASM_JS``: asm.js output is not supported anymore (Valid values: [1]) - - ``FINALIZE_ASM_JS``: asm.js output is not supported anymore (Valid values: [0, 1]) - - ``ASYNCIFY_WHITELIST``: Valid values: ASYNCIFY_ONLY - - ``ASYNCIFY_BLACKLIST``: Valid values: ASYNCIFY_REMOVE - - ``EXCEPTION_CATCHING_WHITELIST``: Valid values: EXCEPTION_CATCHING_ALLOWED - - ``SEPARATE_ASM``: Separate asm.js only made sense for fastcomp with asm.js output (Valid values: [0]) - - ``SEPARATE_ASM_MODULE_NAME``: Separate asm.js only made sense for fastcomp with asm.js output (Valid values: ['']) - - ``FAST_UNROLLED_MEMCPY_AND_MEMSET``: The wasm backend implements memcpy/memset in C (Valid values: [0, 1]) - - ``DOUBLE_MODE``: The wasm backend always implements doubles normally (Valid values: [0, 1]) - - ``PRECISE_F32``: The wasm backend always implements floats normally (Valid values: [0, 1, 2]) - - ``ALIASING_FUNCTION_POINTERS``: The wasm backend always uses a single index space for function pointers, in a single Table (Valid values: [0, 1]) - - ``AGGRESSIVE_VARIABLE_ELIMINATION``: Wasm ignores asm.js-specific optimization flags (Valid values: [0, 1]) - - ``SIMPLIFY_IFS``: Wasm ignores asm.js-specific optimization flags (Valid values: [1]) - - ``DEAD_FUNCTIONS``: The wasm backend does not support dead function removal (Valid values: [[]]) - - ``WASM_BACKEND``: Only the wasm backend is now supported (note that setting it as -s has never been allowed anyhow) (Valid values: [-1]) - - ``EXPORT_BINDINGS``: No longer needed (Valid values: [0, 1]) - - ``RUNNING_JS_OPTS``: Fastcomp cared about running JS which could alter asm.js validation, but not upstream (Valid values: [0]) - - ``EXPORT_FUNCTION_TABLES``: No longer needed (Valid values: [0]) - - ``BINARYEN_SCRIPTS``: No longer needed (Valid values: ['']) - - ``WARN_UNALIGNED``: No longer needed (Valid values: [0, 1]) - - ``ASM_PRIMITIVE_VARS``: No longer needed (Valid values: [[]]) - - ``WORKAROUND_IOS_9_RIGHT_SHIFT_BUG``: Wasm2JS does not support iPhone 4s, iPad 2, iPad 3, iPad Mini 1, Pod Touch 5 (devices with end-of-life at iOS 9.3.5) and older (Valid values: [0]) - - ``RUNTIME_FUNCS_TO_IMPORT``: No longer needed (Valid values: [[]]) - - ``LIBRARY_DEPS_TO_AUTOEXPORT``: No longer needed (Valid values: [[]]) - - ``EMIT_EMSCRIPTEN_METADATA``: No longer supported (Valid values: [0]) - - ``SHELL_FILE``: No longer supported (Valid values: ['']) - - ``LLD_REPORT_UNDEFINED``: Disabling is no longer supported (Valid values: [1]) - - ``MEM_INIT_METHOD``: No longer supported (Valid values: [0]) - - ``USE_PTHREADS``: No longer needed. Use -pthread instead (Valid values: [0, 1]) - - ``USES_DYNAMIC_ALLOC``: No longer supported. Use -sMALLOC=none (Valid values: [1]) - - ``REVERSE_DEPS``: No longer needed (Valid values: ['auto', 'all', 'none']) - - ``RUNTIME_LOGGING``: Valid values: RUNTIME_DEBUG - - ``MIN_EDGE_VERSION``: No longer supported (Valid values: [2147483647]) - - ``MIN_IE_VERSION``: No longer supported (Valid values: [2147483647]) - - ``WORKAROUND_OLD_WEBGL_UNIFORM_UPLOAD_IGNORED_OFFSET_BUG``: No longer supported (Valid values: [0]) - - ``AUTO_ARCHIVE_INDEXES``: No longer needed (Valid values: [0, 1]) - - ``USE_ES6_IMPORT_META``: Disabling is no longer supported (Valid values: [1]) - - ``EXTRA_EXPORTED_RUNTIME_METHODS``: No longer supported, use EXPORTED_RUNTIME_METHODS (Valid values: [[]]) - - ``SUPPORT_ERRNO``: No longer supported (Valid values: [0]) - - ``DEMANGLE_SUPPORT``: No longer supported (Valid values: [0]) - - ``MAYBE_WASM2JS``: No longer supported (use -sWASM=2) (Valid values: [0]) - - ``HEADLESS``: No longer supported, use headless browsers or Node.js with JSDOM (Valid values: [0]) - - ``USE_OFFSET_COVERTER``: No longer supported, not needed with modern v8 versions (Valid values: [0]) - - ``ASYNCIFY_LAZY_LOAD_CODE``: No longer supported (Valid values: [0]) - - ``USE_WEBGPU``: No longer supported; replaced by --use-port=emdawnwebgpu, which implements a newer (but incompatible) version of webgpu.h - see tools/ports/emdawnwebgpu.py (Valid values: [0]) - - ``PROXY_TO_WORKER``: No longer supported (Valid values: [0]) - - ``NODEJS_CATCH_EXIT``: No longer supported (Valid values: [0]) - - ``NODEJS_CATCH_REJECTION``: No longer supported (Valid values: [0]) - - ``POLYFILL_OLD_MATH_FUNCTIONS``: No longer supported (Valid values: [0]) - - ``RELOCATABLE``: No longer supported (Valid values: [0]) - - ``WASM_JS_TYPES``: No longer supported (Valid values: [0]) - - ``DETERMINISTIC``: No longer supported (Valid values: [0]) +- ``BINARYEN``: Valid values: WASM +- ``TOTAL_STACK``: Valid values: STACK_SIZE +- ``BINARYEN_ASYNC_COMPILATION``: Valid values: WASM_ASYNC_COMPILATION +- ``UNALIGNED_MEMORY``: forced unaligned memory not supported in fastcomp (Valid values: [0]) +- ``FORCE_ALIGNED_MEMORY``: forced aligned memory is not supported in fastcomp (Valid values: [0]) +- ``PGO``: pgo no longer supported (Valid values: [0]) +- ``QUANTUM_SIZE``: altering the QUANTUM_SIZE is not supported (Valid values: [4]) +- ``FUNCTION_POINTER_ALIGNMENT``: Starting from Emscripten 1.37.29, no longer available (https://github.com/emscripten-core/emscripten/pull/6091) (Valid values: [2]) +- ``RESERVED_FUNCTION_POINTERS``: Valid values: ALLOW_TABLE_GROWTH +- ``BUILD_AS_SHARED_LIB``: Starting from Emscripten 1.38.16, no longer available (https://github.com/emscripten-core/emscripten/pull/7433) (Valid values: [0]) +- ``SAFE_SPLIT_MEMORY``: Starting from Emscripten 1.38.19, SAFE_SPLIT_MEMORY codegen is no longer available (https://github.com/emscripten-core/emscripten/pull/7465) (Valid values: [0]) +- ``SPLIT_MEMORY``: Starting from Emscripten 1.38.19, SPLIT_MEMORY codegen is no longer available (https://github.com/emscripten-core/emscripten/pull/7465) (Valid values: [0]) +- ``BINARYEN_METHOD``: Starting from Emscripten 1.38.23, Emscripten now always builds either to Wasm (-sWASM - default), or to JavaScript (-sWASM=0), other methods are not supported (https://github.com/emscripten-core/emscripten/pull/7836) (Valid values: ['native-wasm']) +- ``BINARYEN_TRAP_MODE``: The wasm backend does not support a trap mode (it always clamps, in effect) (Valid values: [-1]) +- ``PRECISE_I64_MATH``: Starting from Emscripten 1.38.26, PRECISE_I64_MATH is always enabled (https://github.com/emscripten-core/emscripten/pull/7935) (Valid values: [1, 2]) +- ``MEMFS_APPEND_TO_TYPED_ARRAYS``: Starting from Emscripten 1.38.26, MEMFS_APPEND_TO_TYPED_ARRAYS=0 is no longer supported. MEMFS no longer supports using JS arrays for file data (https://github.com/emscripten-core/emscripten/pull/7918) (Valid values: [1]) +- ``ERROR_ON_MISSING_LIBRARIES``: missing libraries are always an error now (Valid values: [1]) +- ``EMITTING_JS``: The new STANDALONE_WASM flag replaces this (replace EMITTING_JS=0 with STANDALONE_WASM=1) (Valid values: [1]) +- ``SKIP_STACK_IN_SMALL``: SKIP_STACK_IN_SMALL is no longer needed as the backend can optimize it directly (Valid values: [0, 1]) +- ``SAFE_STACK``: Replace SAFE_STACK=1 with STACK_OVERFLOW_CHECK=2 (Valid values: [0]) +- ``MEMORY_GROWTH_STEP``: Valid values: MEMORY_GROWTH_LINEAR_STEP +- ``ELIMINATE_DUPLICATE_FUNCTIONS``: Duplicate function elimination for wasm is handled automatically by binaryen (Valid values: [0, 1]) +- ``ELIMINATE_DUPLICATE_FUNCTIONS_DUMP_EQUIVALENT_FUNCTIONS``: Duplicate function elimination for wasm is handled automatically by binaryen (Valid values: [0]) +- ``ELIMINATE_DUPLICATE_FUNCTIONS_PASSES``: Duplicate function elimination for wasm is handled automatically by binaryen (Valid values: [5]) +- ``WASM_OBJECT_FILES``: For LTO, use -flto or -fto=thin instead. Otherwise, Wasm object files are the default (Valid values: [1]) +- ``TOTAL_MEMORY``: Valid values: INITIAL_MEMORY +- ``WASM_MEM_MAX``: Valid values: MAXIMUM_MEMORY +- ``BINARYEN_MEM_MAX``: Valid values: MAXIMUM_MEMORY +- ``BINARYEN_PASSES``: Use BINARYEN_EXTRA_PASSES to add additional passes (Valid values: ['']) +- ``SWAPPABLE_ASM_MODULE``: Fully swappable asm modules are no longer supported (Valid values: [0]) +- ``ASM_JS``: asm.js output is not supported anymore (Valid values: [1]) +- ``FINALIZE_ASM_JS``: asm.js output is not supported anymore (Valid values: [0, 1]) +- ``ASYNCIFY_WHITELIST``: Valid values: ASYNCIFY_ONLY +- ``ASYNCIFY_BLACKLIST``: Valid values: ASYNCIFY_REMOVE +- ``EXCEPTION_CATCHING_WHITELIST``: Valid values: EXCEPTION_CATCHING_ALLOWED +- ``SEPARATE_ASM``: Separate asm.js only made sense for fastcomp with asm.js output (Valid values: [0]) +- ``SEPARATE_ASM_MODULE_NAME``: Separate asm.js only made sense for fastcomp with asm.js output (Valid values: ['']) +- ``FAST_UNROLLED_MEMCPY_AND_MEMSET``: The wasm backend implements memcpy/memset in C (Valid values: [0, 1]) +- ``DOUBLE_MODE``: The wasm backend always implements doubles normally (Valid values: [0, 1]) +- ``PRECISE_F32``: The wasm backend always implements floats normally (Valid values: [0, 1, 2]) +- ``ALIASING_FUNCTION_POINTERS``: The wasm backend always uses a single index space for function pointers, in a single Table (Valid values: [0, 1]) +- ``AGGRESSIVE_VARIABLE_ELIMINATION``: Wasm ignores asm.js-specific optimization flags (Valid values: [0, 1]) +- ``SIMPLIFY_IFS``: Wasm ignores asm.js-specific optimization flags (Valid values: [1]) +- ``DEAD_FUNCTIONS``: The wasm backend does not support dead function removal (Valid values: [[]]) +- ``WASM_BACKEND``: Only the wasm backend is now supported (note that setting it as -s has never been allowed anyhow) (Valid values: [-1]) +- ``EXPORT_BINDINGS``: No longer needed (Valid values: [0, 1]) +- ``RUNNING_JS_OPTS``: Fastcomp cared about running JS which could alter asm.js validation, but not upstream (Valid values: [0]) +- ``EXPORT_FUNCTION_TABLES``: No longer needed (Valid values: [0]) +- ``BINARYEN_SCRIPTS``: No longer needed (Valid values: ['']) +- ``WARN_UNALIGNED``: No longer needed (Valid values: [0, 1]) +- ``ASM_PRIMITIVE_VARS``: No longer needed (Valid values: [[]]) +- ``WORKAROUND_IOS_9_RIGHT_SHIFT_BUG``: Wasm2JS does not support iPhone 4s, iPad 2, iPad 3, iPad Mini 1, Pod Touch 5 (devices with end-of-life at iOS 9.3.5) and older (Valid values: [0]) +- ``RUNTIME_FUNCS_TO_IMPORT``: No longer needed (Valid values: [[]]) +- ``LIBRARY_DEPS_TO_AUTOEXPORT``: No longer needed (Valid values: [[]]) +- ``EMIT_EMSCRIPTEN_METADATA``: No longer supported (Valid values: [0]) +- ``SHELL_FILE``: No longer supported (Valid values: ['']) +- ``LLD_REPORT_UNDEFINED``: Disabling is no longer supported (Valid values: [1]) +- ``MEM_INIT_METHOD``: No longer supported (Valid values: [0]) +- ``USE_PTHREADS``: No longer needed. Use -pthread instead (Valid values: [0, 1]) +- ``USES_DYNAMIC_ALLOC``: No longer supported. Use -sMALLOC=none (Valid values: [1]) +- ``REVERSE_DEPS``: No longer needed (Valid values: ['auto', 'all', 'none']) +- ``RUNTIME_LOGGING``: Valid values: RUNTIME_DEBUG +- ``MIN_EDGE_VERSION``: No longer supported (Valid values: [2147483647]) +- ``MIN_IE_VERSION``: No longer supported (Valid values: [2147483647]) +- ``WORKAROUND_OLD_WEBGL_UNIFORM_UPLOAD_IGNORED_OFFSET_BUG``: No longer supported (Valid values: [0]) +- ``AUTO_ARCHIVE_INDEXES``: No longer needed (Valid values: [0, 1]) +- ``USE_ES6_IMPORT_META``: Disabling is no longer supported (Valid values: [1]) +- ``EXTRA_EXPORTED_RUNTIME_METHODS``: No longer supported, use EXPORTED_RUNTIME_METHODS (Valid values: [[]]) +- ``SUPPORT_ERRNO``: No longer supported (Valid values: [0]) +- ``DEMANGLE_SUPPORT``: No longer supported (Valid values: [0]) +- ``MAYBE_WASM2JS``: No longer supported (use -sWASM=2) (Valid values: [0]) +- ``HEADLESS``: No longer supported, use headless browsers or Node.js with JSDOM (Valid values: [0]) +- ``USE_OFFSET_COVERTER``: No longer supported, not needed with modern v8 versions (Valid values: [0]) +- ``ASYNCIFY_LAZY_LOAD_CODE``: No longer supported (Valid values: [0]) +- ``USE_WEBGPU``: No longer supported; replaced by --use-port=emdawnwebgpu, which implements a newer (but incompatible) version of webgpu.h - see tools/ports/emdawnwebgpu.py (Valid values: [0]) +- ``PROXY_TO_WORKER``: No longer supported (Valid values: [0]) +- ``NODEJS_CATCH_EXIT``: No longer supported (Valid values: [0]) +- ``NODEJS_CATCH_REJECTION``: No longer supported (Valid values: [0]) +- ``POLYFILL_OLD_MATH_FUNCTIONS``: No longer supported (Valid values: [0]) +- ``RELOCATABLE``: No longer supported (Valid values: [0]) +- ``WASM_JS_TYPES``: No longer supported (Valid values: [0]) +- ``DETERMINISTIC``: No longer supported (Valid values: [0])