diff --git a/docs/emcc.txt b/docs/emcc.txt index f0278f7c5f856..e5644a58eb0d4 100644 --- a/docs/emcc.txt +++ b/docs/emcc.txt @@ -80,12 +80,12 @@ Options that are modified or new in *emcc* are listed below: "-Os" [compile+link] Like "-O3", but focuses more on code size (and may - make tradeoffs with speed). This can affect both wasm and + make tradeoffs with speed). This can affect both Wasm and JavaScript. "-Oz" [compile+link] Like "-Os", but reduces code size even further, and - may take longer to run. This can affect both wasm and JavaScript. + may take longer to run. This can affect both Wasm and JavaScript. Note: @@ -166,7 +166,7 @@ Options that are modified or new in *emcc* are listed below: Preserve debug information, but in a separate file on the side. This is the same as "-g", but the main file will contain no debug info. Instead, debug info will be present in a file on the side, in - "FILENAME" if provided, otherwise the same as the wasm file but + "FILENAME" if provided, otherwise the same as the Wasm file but with suffix ".debug.wasm". While the main file contains no debug info, it does contain a URL to where the debug file is, so that devtools can find it. You can use "-sSEPARATE_DWARF_URL=URL" to @@ -180,7 +180,7 @@ Options that are modified or new in *emcc* are listed below: file is updated to have a "sourceMappingURL" section. The resulting URL will have format: "" + "" + ".map". "" defaults to being empty (which means the source map is - served from the same directory as the wasm file). It can be changed + served from the same directory as the Wasm file). It can be changed using --source-map-base. "-g" @@ -221,7 +221,7 @@ Options that are modified or new in *emcc* are listed below: to the compiler. "--emit-symbol-map" - [link] Save a map file between function indexes in the wasm and + [link] Save a map file between function indexes in the Wasm and function names. By storing the names on a file on the side, you can avoid shipping the names, and can still reconstruct meaningful stack traces by translating the indexes back to the names. @@ -487,8 +487,8 @@ Options that are modified or new in *emcc* are listed below: Note: - Note that this is only relevant when *not* emitting wasm, as - wasm embeds the memory init data in the wasm binary. + Note that this is only relevant when *not* emitting Wasm, as + Wasm embeds the memory init data in the Wasm binary. Possible values are: @@ -594,7 +594,7 @@ Options that are modified or new in *emcc* are listed below: WebAssembly). * **.wasm** : WebAssembly without JavaScript support code - ("standalone wasm"; this enables "STANDALONE_WASM"). + ("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. diff --git a/docs/packaging.md b/docs/packaging.md index 785e5dfa8dd63..e15bd27ccbee3 100644 --- a/docs/packaging.md +++ b/docs/packaging.md @@ -55,8 +55,7 @@ To see how our CI builds things, the relevant script is In general, the repos you need to build are LLVM and Binaryen (as emscripten itself doesn't have any binaries to build). -When packaging build results, you need the following executables (when using -the wasm backend): +When packaging build results, you need the following executables: * From LLVM: * clang diff --git a/site/source/docs/api_reference/emscripten.h.rst b/site/source/docs/api_reference/emscripten.h.rst index 034b8753e889a..f2277abc6e338 100644 --- a/site/source/docs/api_reference/emscripten.h.rst +++ b/site/source/docs/api_reference/emscripten.h.rst @@ -1385,10 +1385,10 @@ IndexedDB :param perror: An out parameter that will be filled with a non-zero value if an error occurred. -Upstream Asyncify functions -=========================== +Asyncify functions +================== -These functions only work with the upstream wasm backend when using Asyncify. +These functions only work when using Asyncify. Typedefs -------- @@ -1408,18 +1408,18 @@ Functions .. c:function:: void emscripten_scan_stack(em_scan_func func) Scan the C userspace stack, which means the stack managed by the compiled - code (as opposed to the wasm VM's internal stack, which is not directly + code (as opposed to the Wasm VM's internal stack, which is not directly observable). This data is already in linear memory; this function just gives you a simple way to know where it is. .. c:function:: void emscripten_scan_registers(em_scan_func func) - Scan "registers", by which we mean data that is not in memory. In wasm, + Scan "registers", by which we mean data that is not in memory. In Wasm, that means data stored in locals, including locals in functions higher up - the stack - the wasm VM has spilled them, but none of that is observable to + the stack - the Wasm VM has spilled them, but none of that is observable to user code). - Note that this function scans wasm locals. Depending on the LLVM + Note that this function scans Wasm locals. Depending on the LLVM optimization level, this may not scan the original locals in your source code. For example in ``-O0`` locals may be stored on the stack. To make sure you scan everything necessary, you can also do @@ -1431,15 +1431,15 @@ Functions .. c:function:: void emscripten_lazy_load_code() - This creates two wasm files at compile time: the first wasm which is + This creates two Wasm files at compile time: the first Wasm which is downloaded and run normally, and a second that is lazy-loaded. When an - ``emscripten_lazy_load_code()`` call is reached, we load the second wasm + ``emscripten_lazy_load_code()`` call is reached, we load the second Wasm and resume execution using it. The idea here is that the initial download can be quite small, if you place enough ``emscripten_lazy_load_code()`` calls in your codebase, as - the optimizer can remove code from the first wasm if it sees it can't - be reached. The second downloaded wasm can contain your full codebase, + the optimizer can remove code from the first Wasm if it sees it can't + be reached. The second downloaded Wasm can contain your full codebase, including rarely-used functions, in which case the lazy-loading may not happen at all. @@ -1456,8 +1456,8 @@ Emscripten runtime JS code, or run Emscripten binaries in your own runtime. .. c:function:: void emscripten_notify_memory_growth(i32 index) Called when memory has grown. In a JS runtime, this is used to know when - to update the JS views on the wasm memory, which otherwise we would need - to constantly check for after any wasm code runs. See + to update the JS views on the Wasm memory, which otherwise we would need + to constantly check for after any Wasm code runs. See `this wasi discussion `_. :param i32 index: Which memory has grown. diff --git a/site/source/docs/api_reference/module.rst b/site/source/docs/api_reference/module.rst index 7b2a3e88a496f..f7aa4ec69ecc2 100644 --- a/site/source/docs/api_reference/module.rst +++ b/site/source/docs/api_reference/module.rst @@ -111,7 +111,7 @@ The following ``Module`` attributes affect code execution. Set them to customize .. js:attribute:: Module.onAbort - If set, this function is called when abnormal program termination occurs. That can happen due to the C method ``abort()`` being called directly, or called from JavaScript, or due to a fatal problem such as being unable to fetch a necessary file during startup (like the wasm binary when running wasm), etc. After calling this function, program termination occurs (i.e., you can't use this to try to do something else instead of stopping; there is no possibility of recovering here). + If set, this function is called when abnormal program termination occurs. That can happen due to the C method ``abort()`` being called directly, or called from JavaScript, or due to a fatal problem such as being unable to fetch a necessary file during startup (such as the Wasm binary), etc. After calling this function, program termination occurs (i.e., you can't use this to try to do something else instead of stopping; there is no possibility of recovering here). .. js:attribute:: Module.onRuntimeInitialized diff --git a/site/source/docs/api_reference/wasm_workers.rst b/site/source/docs/api_reference/wasm_workers.rst index c8e8fdcc09fb7..5d2b53939ad51 100644 --- a/site/source/docs/api_reference/wasm_workers.rst +++ b/site/source/docs/api_reference/wasm_workers.rst @@ -18,7 +18,7 @@ Quick Example void run_in_worker() { - printf("Hello from wasm worker!\n"); + printf("Hello from Wasm Worker!\n"); } int main() diff --git a/site/source/docs/building_from_source/index.rst b/site/source/docs/building_from_source/index.rst index 79da527c8ea6f..8df0eb679cd92 100644 --- a/site/source/docs/building_from_source/index.rst +++ b/site/source/docs/building_from_source/index.rst @@ -14,8 +14,8 @@ Get the ``main`` branches, or check the `Packaging `_. -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 `_. +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: :: diff --git a/site/source/docs/compiling/Building-Projects.rst b/site/source/docs/compiling/Building-Projects.rst index 79b84dc70a06e..18ec988297d1d 100644 --- a/site/source/docs/compiling/Building-Projects.rst +++ b/site/source/docs/compiling/Building-Projects.rst @@ -30,7 +30,7 @@ To build with Emscripten, you would instead use the following commands: # Run emconfigure with the normal configure command as an argument. emconfigure ./configure - # Run emmake with the normal make to generate wasm object files. + # Run emmake with the normal make to generate Wasm object files. emmake make # Compile the linked code generated by make to JavaScript + WebAssembly. @@ -48,8 +48,8 @@ To build with Emscripten, you would instead use the following commands: .. tip:: We recommend you call both *emconfigure* and *emmake* scripts in *configure*- and *CMake*-based build systems. Whether you actually **need** to call both tools depends on the build system (some systems will store the environment variables in the configure step, and others will not). -*Make* generates wasm object files. It may also link the object files into -libraries and/or wasm executables. Unless such a build system has been modified +*Make* generates Wasm object files. It may also link the object files into +libraries and/or Wasm executables. Unless such a build system has been modified to also emit JavaScript output, you will need to run an additional ``emcc`` command as shown above, that will emit the final runnable JavaScript and WebAssembly. @@ -61,15 +61,15 @@ WebAssembly. file extensions are the same as *gcc* would use for the different types). Irrespective of the file extension, these files contain something that *emcc* can compile into the final JavaScript + WebAssembly (typically the contents - will be wasm object files, but if you build with LTO then they will contain + will be Wasm object files, but if you build with LTO then they will contain LLVM bitcode). .. note:: - Some build systems may not properly emit wasm object files using the above procedure, + Some build systems may not properly emit Wasm object files using the above procedure, and you may see ``is not a valid input file`` warnings. You can run ``file`` to check what a file contains (also you can manually check if the contents - start with ``\0asm`` to see if they are wasm object files, or ``BC`` if they + start with ``\0asm`` to see if they are Wasm object files, or ``BC`` if they are LLVM bitcode). It is also worth running ``emmake make VERBOSE=1`` which will print out the commands it runs - you should see *emcc* being used, and not the native system compiler. If *emcc* is not used, you may need to modify @@ -178,7 +178,7 @@ must specify :ref:`-g ` or one of the .. code-block:: bash - # Compile the wasm object file to JavaScript+WebAssembly, with debug info + # Compile the Wasm object file to JavaScript+WebAssembly, with debug info # -g or -gN can be used to set the debug level (N) emcc -g project.o -o project.js @@ -406,4 +406,4 @@ Troubleshooting .. note:: You can use ``llvm-nm`` to see which symbols are defined in each object file. One solution is to use :ref:`dynamic-linking `. This ensures that libraries are linked only once, in the final build stage. -- When generating standalone wasm, make sure to invoke the ``_start`` or (for ``--no-entry``) ``_initialize`` export before attempting to use the module. +- When generating standalone Wasm, make sure to invoke the ``_start`` or (for ``--no-entry``) ``_initialize`` export before attempting to use the module. diff --git a/site/source/docs/compiling/WebAssembly.rst b/site/source/docs/compiling/WebAssembly.rst index 979855e8fbb4b..f8095ba848a8e 100644 --- a/site/source/docs/compiling/WebAssembly.rst +++ b/site/source/docs/compiling/WebAssembly.rst @@ -20,31 +20,31 @@ WebAssembly is emitted by default, without the need for any special flags. emcc [..args..] -sWASM=0 .. note:: Emscripten's WebAssembly support depends on `Binaryen `_, which is provided by the emsdk (if you don't use the emsdk, you need to build it and set it up in your ``.emscripten`` file). -.. note:: Deciding to compile to wasm or JS can be done at the linking stage: it doesn't affect the object files. +.. note:: Deciding to compile to Wasm or JS can be done at the linking stage: it doesn't affect the object files. Backends -------- -Emscripten emits WebAssembly using the **upstream LLVM wasm backend**, since +Emscripten emits WebAssembly using the **upstream LLVM Wasm backend**, since version ``1.39.0`` (October 2019). Previously emscripten also supported the old **fastcomp** backend which was removed in ``2.0.0`` (August 2020). There are some differences you may notice between the two backends, if you upgrade from fastcomp to upstream: -* The wasm backend is strict about linking files with different features sets - +* The Wasm backend is strict about linking files with different features sets - for example, if one file was built with atomics but another was not, it will error at link time. This prevents possible bugs, but may mean you need to make some build system fixes. * ``WASM=0`` behaves differently in the two backends. In fastcomp we emit - asm.js, while in upstream we emit JS (since not all wasm constructs can be + asm.js, while in upstream we emit JS (since not all Wasm constructs can be expressed in asm.js). Also, the JS support implements the same external - ``WebAssembly.*`` API, so in particular startup will be async just like wasm + ``WebAssembly.*`` API, so in particular startup will be async just like Wasm by default, and you can control that with ``WASM_ASYNC_COMPILATION`` (even though ``WASM=0``). -* The wasm backend uses wasm object files by default. That means that it does +* The Wasm backend uses Wasm object files by default. That means that it does codegen at the compile step, which makes the link step much faster - like a normal native compiler. For comparison, in fastcomp the compile step emits LLVM IR in object files. @@ -67,7 +67,7 @@ upgrade from fastcomp to upstream: perform some minor types of link time optimization even without LTO being set. The LLVM backend requires actually setting LTO for those things. -* `wasm-ld`, the linker used by the wasm backend, requires libraries (`.a` +* `wasm-ld`, the linker used by the Wasm backend, requires libraries (`.a` archives) to contain symbol indexes. This matches the behaviour the native GNU linker. While `emar` will create such indexes by default, native tools such as GNU `ar` and GNU `strip` are not aware of the WebAssembly object @@ -75,14 +75,14 @@ upgrade from fastcomp to upstream: `strip` on an archive file that contains WebAssembly object files it will remove the index which makes the archive unusable at link time. -* Also see the `blocker bugs on the wasm backend `_, and the `wasm backend tagged issues `_. +* Also see the `blocker bugs on the Wasm backend `_, and the `Wasm backend tagged issues `_. Trapping ======== WebAssembly can trap - throw an exception - on things like division by zero, rounding a very large float to an int, and so forth. In asm.js such things were silently ignored, as in JavaScript they do not throw, so this is a difference between JavaScript and WebAssembly that you may notice, with the browser reporting an error like ``float unrepresentable in integer range``, ``integer result unrepresentable``, ``integer overflow``, or ``Out of bounds Trunc operation``. -The LLVM wasm backend avoids traps by adding more code around each possible trap (basically clamping the value if it would trap). This can increase code size and decrease speed, if you don't need that extra code. The proper solution for this is to use newer wasm instructions that do not trap, by calling emcc or clang with ``-mnontrapping-fptoint``. That code may not run in older VMs, though. +The LLVM Wasm backend avoids traps by adding more code around each possible trap (basically clamping the value if it would trap). This can increase code size and decrease speed, if you don't need that extra code. The proper solution for this is to use newer Wasm instructions that do not trap, by calling emcc or clang with ``-mnontrapping-fptoint``. That code may not run in older VMs, though. Compiler output =============== @@ -112,7 +112,7 @@ Another noticeable effect is that WebAssembly is compiled asynchronously by defa Web server setup ================ -To serve wasm in the most efficient way over the network, make sure your web server has the proper MIME type for ``.wasm`` files, which is application/wasm. That will allow streaming compilation, where the browser can start to compile code as it downloads. +To serve Wasm in the most efficient way over the network, make sure your web server has the proper MIME type for ``.wasm`` files, which is application/wasm. That will allow streaming compilation, where the browser can start to compile code as it downloads. In Apache, you can do this with diff --git a/site/source/docs/contributing/developers_guide.rst b/site/source/docs/contributing/developers_guide.rst index af170ef775d97..b596016741bba 100644 --- a/site/source/docs/contributing/developers_guide.rst +++ b/site/source/docs/contributing/developers_guide.rst @@ -79,12 +79,12 @@ The :ref:`Emscripten Compiler Frontend (emcc) ` is a python script that builds and integrates with the Emscripten system libraries, both the compiled ones and the ones implemented in JS. - **emcc** then calls `emscripten.py `_ - which performs the final transformation to wasm (including invoking + which performs the final transformation to Wasm (including invoking **wasm-emscripten-finalize** from Binaryen) and calls the JS compiler (see ``src/compiler.js`` and related files) which emits the JS. -- If optimizing wasm, **emcc** will then call **wasm-opt**, run meta-dce, and +- If optimizing Wasm, **emcc** will then call **wasm-opt**, run meta-dce, and other useful things. It will also run JS optimizations on the JS that is - emitted alongside the wasm. + emitted alongside the Wasm. Emscripten Test Suite ===================== diff --git a/site/source/docs/debugging/Sanitizers.rst b/site/source/docs/debugging/Sanitizers.rst index 16b6d839082ed..fa97605533b0e 100644 --- a/site/source/docs/debugging/Sanitizers.rst +++ b/site/source/docs/debugging/Sanitizers.rst @@ -131,7 +131,7 @@ you will receive an error message that looks something like: ASan fully supports multi-thread environments. ASan also operates on the JS support code, that is, if JS tries to read from a memory address that is not -valid, it will be caught, just like if that access happened from wasm. +valid, it will be caught, just like if that access happened from Wasm. Examples -------- @@ -380,7 +380,7 @@ Emscripten provides a ``SAFE_HEAP`` mode, which can be activated by running with sanitizers. In general, ``SAFE_HEAP`` focuses on the specific pain points that come up when -targeting wasm. The sanitizers on the other hand focus on the specific pain points that are +targeting Wasm. The sanitizers on the other hand focus on the specific pain points that are involved with using languages like C/C++. Those two sets overlap, but are not identical. Which you should use depends on which types of problems you are looking for. You may want to test with all sanitizers and with ``SAFE_HEAP`` @@ -402,16 +402,16 @@ The specific things ``SAFE_HEAP`` errors on include: unaligned operations. * **Reads or writes past the top of valid memory** as managed by ``sbrk()``, that is, memory that was not properly allocated by ``malloc()``. This is not specific - to wasm, however, in JavaScript if the address is big enough to be outside the + to Wasm, however, in JavaScript if the address is big enough to be outside the Typed Array, ``undefined`` is returned which can be very confusing, which is - why this was added (in wasm at least an error is thrown; ``SAFE_HEAP`` still - helps with wasm though, by checking the area between the top of ``sbrk()``'s - memory and the end of the wasm Memory). + why this was added (in Wasm at least an error is thrown; ``SAFE_HEAP`` still + helps with Wasm though, by checking the area between the top of ``sbrk()``'s + memory and the end of the Wasm Memory). ``SAFE_HEAP`` does these checks by instrumenting every single load and store. That has the cost of slowing things down, but it does give a simple guarantee of finding *all* such problems. It can also be done after compilation, on an -arbitrary wasm binary, while the sanitizers must be done when compiling from +arbitrary Wasm binary, while the sanitizers must be done when compiling from source. In comparison, UBSan can also find null pointer reads and writes. It does not diff --git a/site/source/docs/getting_started/FAQ.rst b/site/source/docs/getting_started/FAQ.rst index 1cea1fe9c4092..ef5acd5e77b1b 100644 --- a/site/source/docs/getting_started/FAQ.rst +++ b/site/source/docs/getting_started/FAQ.rst @@ -81,7 +81,7 @@ The main tips for improving build time are: - For compiling your source files, use a parallel build system (for example, in ``make`` you can do something like ``make -j8`` to run using 8 cores). - For the link step, Emscripten can run some optimizations in parallel - (specifically, Binaryen optimizations for wasm, and our JavaScript + (specifically, Binaryen optimizations for Wasm, and our JavaScript optimizations). Increasing the number of cores results in an almost linear improvement. Emscripten will automatically use more cores if they are available, but you can control that with ``EMCC_CORES=N`` in the environment @@ -152,7 +152,7 @@ the browser devtools (web console and network tab), or in your webserver's logging. -What is "No WebAssembly support found. Build with -sWASM=0 to target JavaScript instead" or "no native wasm support detected"? +What is "No WebAssembly support found. Build with -sWASM=0 to target JavaScript instead" or "no native Wasm support detected"? =============================================================================================================================== Those errors indicate that WebAssembly support is not present in the VM you are @@ -695,7 +695,7 @@ This is a limitation of the asm.js target in :term:`Clang`. This code is not currently supported. -How do I pass int64_t and uint64_t values from js into wasm functions? +How do I pass int64_t and uint64_t values from js into Wasm functions? ====================================================================== If you build using the `-sWASM_BIGINT` flag, then `int64_t` and `uint64_t` will diff --git a/site/source/docs/getting_started/test-suite.rst b/site/source/docs/getting_started/test-suite.rst index 6b9a2896f7f6f..422042582c422 100644 --- a/site/source/docs/getting_started/test-suite.rst +++ b/site/source/docs/getting_started/test-suite.rst @@ -45,11 +45,11 @@ individual test, or use wildcards to run some tests in some modes. For example: The *core* test modes (defined at the bottom of `test/test_core.py `_) -let you run a specific test in either asm.js or wasm, and with different -optimization flags. There are also non-core test modes, that run tests in more -special manner (in particular, in those tests 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 modes include +let you run the tests in variety of different configurations and with different +optimization flags. For example, wasm2js or wasm64. There are also non-core +test suites, that run tests in more special manner (in particular, in those tests +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. @@ -119,8 +119,8 @@ commands: .. code-block:: bash - # Run all core wasm tests - test/runner wasm* + # Run all core tests + test/runner core* # Run "other" test suite test/runner other diff --git a/site/source/docs/introducing_emscripten/about_emscripten.rst b/site/source/docs/introducing_emscripten/about_emscripten.rst index b37ecf1142209..9cccbe37b9510 100644 --- a/site/source/docs/introducing_emscripten/about_emscripten.rst +++ b/site/source/docs/introducing_emscripten/about_emscripten.rst @@ -8,7 +8,7 @@ Emscripten is a complete :ref:`Open Source ` compiler toolchain to WebAssembly. Using Emscripten you can: - Compile C and C++ code, or any other language that uses LLVM, into WebAssembly, - and run it on the Web, Node.js, or other wasm runtimes. + and run it on the Web, Node.js, or other Wasm runtimes. - Compile the C/C++ **runtimes** of other languages into WebAssembly, and then run code in those other languages in an *indirect* way (for example, this has been done for diff --git a/site/source/docs/optimizing/Optimizing-Code.rst b/site/source/docs/optimizing/Optimizing-Code.rst index 05993b5e88990..cca20dcbf0c74 100644 --- a/site/source/docs/optimizing/Optimizing-Code.rst +++ b/site/source/docs/optimizing/Optimizing-Code.rst @@ -36,9 +36,9 @@ How Emscripten optimizes Compiling source files to object files works as you'd expect in a native build system that uses clang and LLVM. When linking object files to the final executable, Emscripten does additional optimizations as well depending on the optimization level: -- For wasm, the Binaryen optimizer is run. Binaryen does both general-purpose optimizations to the wasm that LLVM does not, and also does some whole-program optimization. (Note that Binaryen's whole-program optimizations may do things like inlining, which can be surprising in some cases as LLVM IR attributes like ``noinline`` have been lost at this point.) +- The Binaryen optimizer is run. Binaryen does both general-purpose optimizations to the Wasm that LLVM does not, and also does some whole-program optimization. (Note that Binaryen's whole-program optimizations may do things like inlining, which can be surprising in some cases as LLVM IR attributes like ``noinline`` have been lost at this point.) - JavaScript is generated at this phase, and is optimized by Emscripten's JS optimizer. Optionally you can also run :ref:`the closure compiler `, which is highly recommended for code size. -- Emscripten also optimizes the combined wasm+JS, by minifying imports and exports between them, and by running meta-dce which removes unused code in cycles that span the two worlds. +- Emscripten also optimizes the combined Wasm+JS, by minifying imports and exports between them, and by running meta-dce which removes unused code in cycles that span the two worlds. Link Times ========== @@ -49,15 +49,15 @@ to link with those flags even if the source files were compiled with a different optimization level.) To also skip non-optimization work at link time, link with ``-sWASM_BIGINT``. -Enabling BigInt support removes the need for Emscripten to "legalize" the wasm +Enabling BigInt support removes the need for Emscripten to "legalize" the Wasm to handle ``i64`` values on the JS/Wasm boundary (as with BigInts ``i64`` values are legal, and require no extra processing). Some link flags add additional work at the link stage that can slow things down. For example ``-g`` enables DWARF support, flags like ``-sSAFE_HEAP`` will require -JS post-processing, and flags like ``-sASYNCIFY`` will require wasm +JS post-processing, and flags like ``-sASYNCIFY`` will require Wasm post-processing. To ensure your flags allow the fastest possible link, in which -the wasm is not modified after ``wasm-ld``, build with +the Wasm is not modified after ``wasm-ld``, build with ``-sERROR_ON_WASM_CHANGES_AFTER_LINK``. With that option you will get an error during link if Emscripten must perform changes to the Wasm. For example, if you didn't pass ``-sWASM_BIGINT`` then it will tell you that legalization forces @@ -73,7 +73,7 @@ There are several flags you can :ref:`pass to the compiler WebAssembly =========== -Emscripten will emit WebAssembly by default. You can switch that off with ``-sWASM=0`` (in which case emscripten emit JavaScript), which is necessary if you want the output to run in places where wasm support is not present yet, but the downside is larger and slower code. +Emscripten will emit WebAssembly by default. You can switch that off with ``-sWASM=0`` (in which case emscripten emit JavaScript), which is necessary if you want the output to run in places where Wasm support is not present yet, but the downside is larger and slower code. .. _optimizing-code-size: @@ -113,10 +113,10 @@ Link Time Optimization (LTO) lets the compiler do more optimizations, as it can inline across separate compilation units, and even with system libraries. LTO is enabled by compiling objects files with ``-flto``. The effect of this flag is to emit LTO object files (technically this means emitting bitcode). The -linker can handle a mix wasm object files and LTO object files. Passing +linker can handle a mix Wasm object files and LTO object files. Passing ``-flto`` at link time will also trigger LTO system libraries to be used. -Thus, to allow maximal LTO opportunities with the LLVM wasm backend, build all +Thus, to allow maximal LTO opportunities with the LLVM Wasm backend, build all source files with ``-flto`` and also link with ``flto``. EVAL_CTORS @@ -196,7 +196,7 @@ Other optimization issues C++ exceptions -------------- -Catching C++ exceptions (specifically, emitting catch blocks) is turned off by default in ``-O1`` (and above). Due to how WebAssembly currently implement exceptions, this makes the code much smaller and faster (eventually, wasm should gain native support for exceptions, and not have this issue). +Catching C++ exceptions (specifically, emitting catch blocks) is turned off by default in ``-O1`` (and above). Due to how WebAssembly currently implement exceptions, this makes the code much smaller and faster (eventually, Wasm should gain native support for exceptions, and not have this issue). To re-enable exceptions in optimized code, run *emcc* with ``-sDISABLE_EXCEPTION_CATCHING=0`` (see `src/settings.js `_). diff --git a/site/source/docs/porting/asyncify.rst b/site/source/docs/porting/asyncify.rst index 13e33ec29a6c8..81c238f85c2d3 100644 --- a/site/source/docs/porting/asyncify.rst +++ b/site/source/docs/porting/asyncify.rst @@ -98,8 +98,8 @@ Making async Web APIs behave as if they were synchronous Aside from ``emscripten_sleep`` and the other standard sync APIs Asyncify supports, you can also add your own functions. To do so, you must create a JS -function that is called from wasm (since Emscripten controls pausing and -resuming the wasm from the JS runtime). +function that is called from Wasm (since Emscripten controls pausing and +resuming the Wasm from the JS runtime). One way to do that is with a JS library function. Another is to use ``EM_ASYNC_JS``, which we'll use in this next example: @@ -206,7 +206,7 @@ More on ``ASYNCIFY_IMPORTS`` As in the above example, you can add JS functions that do an async operation but look synchronous from the perspective of C. If you don't use ``EM_ASYNC_JS``, it's vital to add such methods to ``ASYNCIFY_IMPORTS``. That list of imports is -the list of imports to the wasm module that the Asyncify instrumentation must be +the list of imports to the Wasm module that the Asyncify instrumentation must be aware of. Giving it that list tells it that all other JS calls will **not** do an async operation, which lets it not add overhead where it isn't needed. @@ -319,7 +319,7 @@ value is an ``instanceof Promise`` or simply ``await`` on the returned value. Usage with ``ccall`` #################### -To make use of an Asyncify-using wasm export from Javascript, you can use the +To make use of an Asyncify-using Wasm export from Javascript, you can use the ``Module.ccall`` function and pass ``async: true`` to its call options object. ``ccall`` will then return a Promise, which will resolve with the result of the function once the computation completes. 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 6f57d6903d885..a3f8287047e88 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 @@ -622,7 +622,7 @@ See `test_add_function in test/test_core.py`_ for an example. You should build with ``-sALLOW_TABLE_GROWTH`` to allow new functions to be added to the table. Otherwise by default the table has a fixed size. -.. note:: When using ``addFunction`` on LLVM wasm backend, you need to provide +.. note:: When using ``addFunction`` on LLVM Wasm backend, you need to provide an additional second argument, a Wasm function signature string. Each character within a signature string represents a type. The first character represents the return type of a function, and remaining characters are for @@ -679,7 +679,7 @@ Here ``my_function`` is a C function that receives a single integer parameter integer. This could be something like ``int my_function(char *buf)``. The converse case of exporting allocated memory into JavaScript can be -tricky when wasm-based memory is allowed to **grow**, by compiling with +tricky when Wasm-based memory is allowed to **grow**, by compiling with ``-sALLOW_MEMORY_GROWTH``. Increasing the size of memory changes to a new buffer and existing array views essentially become invalid, so you cannot simply do this: diff --git a/site/source/docs/porting/guidelines/function_pointer_issues.rst b/site/source/docs/porting/guidelines/function_pointer_issues.rst index f9e0714152f20..8853679e0cd6d 100644 --- a/site/source/docs/porting/guidelines/function_pointer_issues.rst +++ b/site/source/docs/porting/guidelines/function_pointer_issues.rst @@ -10,7 +10,7 @@ There are two main issues with function pointers: #. Function pointer casts can cause function pointer calls to fail. - Function pointers must be called with the correct type: it is undefined behavior in C and C++ to cast a function pointer to another type and call it that way. This does work in most native platforms, however, despite it being UB, but in asm.js and in wasm it can fail. In that case, you may see an ``abort(10)`` or some other number, and if assertions are on you may see a message with details that start with + Function pointers must be called with the correct type: it is undefined behavior in C and C++ to cast a function pointer to another type and call it that way. This does work in most native platforms, however, despite it being UB, but in Wasm it can fail. In that case, you may see an ``abort(10)`` or some other number, and if assertions are on you may see a message with details that start with :: diff --git a/site/source/docs/porting/pthreads.rst b/site/source/docs/porting/pthreads.rst index 9931bc80b34d6..b3545050b08e2 100644 --- a/site/source/docs/porting/pthreads.rst +++ b/site/source/docs/porting/pthreads.rst @@ -144,7 +144,7 @@ The Emscripten implementation for the pthreads API should follow the POSIX stand - Note that the function emscripten_num_logical_cores() will always return the value of navigator.hardwareConcurrency, i.e. the number of logical cores on the system, even when shared memory is not supported. This means that it is possible for emscripten_num_logical_cores() to return a value greater than 1, while at the same time emscripten_has_threading_support() can return false. The return value of emscripten_has_threading_support() denotes whether the browser has shared memory support available. -- Pthreads + memory growth (``ALLOW_MEMORY_GROWTH``) is especially tricky, see `wasm design issue #1271 `_. This currently causes JS accessing the wasm memory to be slow - but this will likely only be noticeable if the JS does large amounts of memory reads and writes (wasm runs at full speed, so moving work over can fix this). This also requires that your JS be aware that the HEAP* views may need to be updated - JS code embedded with ``--js-library`` etc will automatically be transformed to use the ``GROWABLE_HEAP_*`` helper functions where ``HEAP*`` are used, but external code that uses ``Module.HEAP*`` directly may encounter problems with views being smaller than memory. +- Pthreads + memory growth (``ALLOW_MEMORY_GROWTH``) is especially tricky, see `Wasm design issue #1271 `_. This currently causes JS accessing the Wasm memory to be slow - but this will likely only be noticeable if the JS does large amounts of memory reads and writes (Wasm runs at full speed, so moving work over can fix this). This also requires that your JS be aware that the HEAP* views may need to be updated - JS code embedded with ``--js-library`` etc will automatically be transformed to use the ``GROWABLE_HEAP_*`` helper functions where ``HEAP*`` are used, but external code that uses ``Module.HEAP*`` directly may encounter problems with views being smaller than memory. Also note that when compiling code that uses pthreads, an additional JavaScript file ``NAME.worker.js`` is generated alongside the output .js file (where ``NAME`` is the basename of the main file being emitted). That file must be deployed with the rest of the generated code files. By default, ``NAME.worker.js`` will be loaded relative to the main HTML page URL. If it is desirable to load the file from a different location e.g. in a CDN environment, then one can define the ``Module.locateFile(filename)`` function in the main HTML ``Module`` object to return the URL of the target location of the ``NAME.worker.js`` entry point. If this function is not defined in ``Module``, then the default location relative to the main HTML file is used. diff --git a/site/source/docs/site/glossary.rst b/site/source/docs/site/glossary.rst index 900f4b4c77bff..299bc53afd540 100644 --- a/site/source/docs/site/glossary.rst +++ b/site/source/docs/site/glossary.rst @@ -54,10 +54,10 @@ Emscripten tools and dependencies `LLVM `_ is a compiler infrastructure designed to allow optimization of programs written in arbitrary programming languages. Fastcomp - Fastcomp is Emscripten's second compiler core, after the JS compiler and before the new LLVM wasm backend. + Fastcomp was Emscripten's second compiler core, after the JS compiler and before the new LLVM Wasm backend. Binaryen - `Binaryen `_ is a WebAssembly compiler toolkit, which Emscripten uses to modify and optimize wasm. + `Binaryen `_ is a WebAssembly compiler toolkit, which Emscripten uses to modify and optimize Wasm. node.js `Node.js `_ is a cross-platform runtime environment for server-side and networking applications written in JavaScript. Essentially it allows you to run JavaScript applications outside of a browser context. diff --git a/site/source/docs/tools_reference/emcc.rst b/site/source/docs/tools_reference/emcc.rst index 873b56c373509..e442db641ed98 100644 --- a/site/source/docs/tools_reference/emcc.rst +++ b/site/source/docs/tools_reference/emcc.rst @@ -83,13 +83,13 @@ Options that are modified or new in *emcc* are listed below: ``-Os`` [compile+link] - Like ``-O3``, but focuses more on code size (and may make tradeoffs with speed). This can affect both wasm and JavaScript. + Like ``-O3``, but focuses more on code size (and may make tradeoffs with speed). This can affect both Wasm and JavaScript. .. _emcc-Oz: ``-Oz`` [compile+link] - Like ``-Os``, but reduces code size even further, and may take longer to run. This can affect both wasm and JavaScript. + Like ``-Os``, but reduces code size even further, and may take longer to run. This can affect both Wasm and JavaScript. .. note:: For more tips on optimizing your code, see :ref:`Optimizing-Code`. @@ -154,7 +154,7 @@ Options that are modified or new in *emcc* are listed below: Preserve debug information, but in a separate file on the side. This is the same as ``-g``, but the main file will contain no debug info. Instead, debug info will be present in a file on the side, in ``FILENAME`` if provided, - otherwise the same as the wasm file but with suffix ``.debug.wasm``. While + otherwise the same as the Wasm file but with suffix ``.debug.wasm``. While the main file contains no debug info, it does contain a URL to where the debug file is, so that devtools can find it. You can use ``-sSEPARATE_DWARF_URL=URL`` to customize that location (this is useful if @@ -170,7 +170,7 @@ Options that are modified or new in *emcc* are listed below: ``sourceMappingURL`` section. The resulting URL will have format: ```` + ```` + ``.map``. ```` defaults to being empty (which means the source map is served from the same directory - as the wasm file). It can be changed using :ref:`--source-map-base `. + as the Wasm file). It can be changed using :ref:`--source-map-base `. .. _emcc-gN: @@ -224,7 +224,7 @@ Options that are modified or new in *emcc* are listed below: ``--emit-symbol-map`` [link] - Save a map file between function indexes in the wasm and function names. By + Save a map file between function indexes in the Wasm and function names. By storing the names on a file on the side, you can avoid shipping the names, and can still reconstruct meaningful stack traces by translating the indexes back to the names. @@ -474,7 +474,7 @@ Options that are modified or new in *emcc* are listed below: [link] Specifies whether to emit a separate memory initialization file. - .. note:: Note that this is only relevant when *not* emitting wasm, as wasm embeds the memory init data in the wasm binary. + .. note:: Note that this is only relevant when *not* emitting Wasm, as Wasm embeds the memory init data in the Wasm binary. Possible values are: @@ -546,7 +546,7 @@ Options that are modified or new in *emcc* are listed below: - **.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``). + - **.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.