From 5767cb6bae4955a62eee57794a566b4f8fdea056 Mon Sep 17 00:00:00 2001 From: Heejin Ahn Date: Wed, 31 Dec 2025 07:49:58 +0000 Subject: [PATCH 1/2] [Docs] Fix typos Spun out of #26014. This fixes typos in docs, `settings.js` (because the comments here are copied into `settings_reference.rst`), and header strings in `update_settings_docs.py`. --- .../docs/api_reference/Filesystem-API.rst | 2 +- site/source/docs/api_reference/console.h.rst | 2 +- .../docs/api_reference/emscripten.h.rst | 2 +- site/source/docs/api_reference/html5.h.rst | 24 +++--- site/source/docs/api_reference/index.rst | 2 +- .../source/docs/api_reference/preamble.js.rst | 6 +- .../docs/api_reference/wasm_workers.rst | 4 +- .../configuring_emscripten_settings.rst | 2 +- .../docs/building_from_source/index.rst | 2 +- .../verify_emscripten_environment.rst | 2 +- .../docs/compiling/Building-Projects.rst | 2 +- .../source/docs/compiling/Dynamic-Linking.rst | 8 +- .../docs/compiling/Modularized-Output.rst | 14 ++-- .../Running-html-files-with-emrun.rst | 2 +- site/source/docs/compiling/WebAssembly.rst | 2 +- .../docs/contributing/developers_guide.rst | 2 +- site/source/docs/getting_started/Tutorial.rst | 2 +- .../source/docs/getting_started/downloads.rst | 4 +- .../docs/introducing_emscripten/community.rst | 2 +- .../emscripten_license.rst | 2 +- .../docs/optimizing/Optimizing-Code.rst | 2 +- site/source/docs/porting/Debugging.rst | 4 +- site/source/docs/porting/asyncify.rst | 2 +- .../Interacting-with-code.rst | 4 +- .../connecting_cpp_and_javascript/embind.rst | 2 +- .../guidelines/function_pointer_issues.rst | 2 +- .../EGL-Support-in-Emscripten.rst | 2 +- site/source/docs/porting/simd.rst | 2 +- site/source/docs/tools_reference/emcc.rst | 4 +- site/source/docs/tools_reference/emsdk.rst | 4 +- .../tools_reference/settings_reference.rst | 82 +++++++++---------- src/settings.js | 78 +++++++++--------- tools/maint/update_settings_docs.py | 6 +- 33 files changed, 140 insertions(+), 142 deletions(-) diff --git a/site/source/docs/api_reference/Filesystem-API.rst b/site/source/docs/api_reference/Filesystem-API.rst index 99c5e23ffb78a..1c5985e5a67c7 100644 --- a/site/source/docs/api_reference/Filesystem-API.rst +++ b/site/source/docs/api_reference/Filesystem-API.rst @@ -171,7 +171,7 @@ The device node acts as an interface between the device and the file system. Any Setting up standard I/O devices =============================== -Emscripten standard I/O works by going though the virtual ``/dev/stdin``, ``/dev/stdout`` and ``/dev/stderr`` devices. You can set them up using your own I/O functions by calling :js:func:`FS.init`. +Emscripten standard I/O works by going through the virtual ``/dev/stdin``, ``/dev/stdout`` and ``/dev/stderr`` devices. You can set them up using your own I/O functions by calling :js:func:`FS.init`. By default: diff --git a/site/source/docs/api_reference/console.h.rst b/site/source/docs/api_reference/console.h.rst index 109d69ddf6cb6..076f8b16bdfde 100644 --- a/site/source/docs/api_reference/console.h.rst +++ b/site/source/docs/api_reference/console.h.rst @@ -51,6 +51,6 @@ Functions Prints the string using the `dbg()` JS function, which by will write to the console (or stdout). Just like the `dbg()` JS function this symbol is only available in debug builds (i.e. when linking with `-sASSERTIONS` or - equivelently `-O0`). + equivalently `-O0`). :param utf8String: A string encoded as UTF-8. diff --git a/site/source/docs/api_reference/emscripten.h.rst b/site/source/docs/api_reference/emscripten.h.rst index f1cbb1ffed2cf..fdb9567ffcd86 100644 --- a/site/source/docs/api_reference/emscripten.h.rst +++ b/site/source/docs/api_reference/emscripten.h.rst @@ -789,7 +789,7 @@ Functions :param int flags: See dlopen flags. :param void* user_data: User data passed to onsuccess, and onerror callbacks. :param em_dlopen_callback onsuccess: Called if the library was loaded successfully. - :param em_arg_callback_func onerror: Called if there as an error loading the library. + :param em_arg_callback_func onerror: Called if there is an error loading the library. Asynchronous IndexedDB API diff --git a/site/source/docs/api_reference/html5.h.rst b/site/source/docs/api_reference/html5.h.rst index fee237551da37..caef9b5c95a75 100644 --- a/site/source/docs/api_reference/html5.h.rst +++ b/site/source/docs/api_reference/html5.h.rst @@ -338,7 +338,7 @@ Struct A system and implementation dependent numeric code identifying the unmodified value of the pressed key; this is usually the same as ``keyCode``. - .. warning:: This attribute is deprecated, you should use the field ``key`` instead, if available. Note thought that while this field is deprecated, the cross-browser support for ``which`` may be better than for the other fields, so experimentation is recommended. Read issue https://github.com/emscripten-core/emscripten/issues/2817 for more information. + .. warning:: This attribute is deprecated, you should use the field ``key`` instead, if available. Note though that while this field is deprecated, the cross-browser support for ``which`` may be better than for the other fields, so experimentation is recommended. Read issue https://github.com/emscripten-core/emscripten/issues/2817 for more information. Callback functions @@ -458,7 +458,7 @@ Struct .. c:member:: int canvasX int canvasY - These fields give the mouse coordinates mapped to the Emscripten canvas client area (Emscripten-specific extension; coordinates are rounded down the nearest integer). + These fields give the mouse coordinates mapped to the Emscripten canvas client area (Emscripten-specific extension; coordinates are rounded down to the nearest integer). .. c:member:: int padding @@ -515,7 +515,7 @@ Functions Returns the most recently received mouse event state. - Note that for this function call to succeed, :c:func:`emscripten_set_xxx_callback ` must have first been called with one of the mouse event types and a non-zero callback function pointer to enable the Mouse state capture. + Note that for this function call to succeed, :c:func:`emscripten_set_xxx_callback ` must have first been called with one of the mouse event types and a non-zero callback function pointer to enable the mouse state capture. :param EmscriptenMouseEvent* mouseState: The most recently received mouse event state. :returns: :c:data:`EMSCRIPTEN_RESULT_SUCCESS`, or one of the other result values. @@ -561,7 +561,7 @@ Struct double deltaY double deltaZ - Movement of the wheel on each of the axis. Note that these values may be fractional, so you should avoid simply casting them to integer, or it might result + Movement of the wheel on each of the axes. Note that these values may be fractional, so you should avoid simply casting them to integer, or it might result in scroll values of 0. The positive Y scroll direction is when scrolling the page downwards (page CSS pixel +Y direction), which corresponds to scrolling the mouse wheel downwards (away from the screen) on Windows, Linux, and also on macOS when the 'natural scroll' option is disabled. @@ -794,7 +794,7 @@ Struct The `orientation `_ of the device in terms of the transformation from a coordinate frame fixed on the Earth to a coordinate frame fixed in the device. - The image (source: `dev.opera.com `_) and definitions below illustrate the co-ordinate frame: + The image (source: `dev.opera.com `_) and definitions below illustrate the coordinate frame: - :c:type:`~EmscriptenDeviceOrientationEvent.alpha`: the rotation of the device around the Z axis. - :c:type:`~EmscriptenDeviceOrientationEvent.beta`: the rotation of the device around the X axis. @@ -1767,7 +1767,7 @@ Functions .. note:: Gamepad API uses an array of gamepad state objects to return the state of - each device. The devices are identified via the index they are present in in + each device. The devices are identified via the index they are present in this array. Because of that, if one first connects gamepad A, then gamepad B, and then disconnects gamepad A, the gamepad B shall not take the place of gamepad A, so in this scenario, this function will still keep returning two @@ -1803,7 +1803,7 @@ Defines .. c:macro:: EMSCRIPTEN_EVENT_BATTERYCHARGINGCHANGE EMSCRIPTEN_EVENT_BATTERYLEVELCHANGE - Emscripten `batterymanager `_ events. + Emscripten `BatteryManager `_ events. Struct @@ -1811,7 +1811,7 @@ Struct .. c:type:: EmscriptenBatteryEvent - The event structure passed in the `batterymanager `_ events: ``chargingchange`` and ``levelchange``. + The event structure passed in the `BatteryManager `_ events: ``chargingchange`` and ``levelchange``. .. c:member:: double chargingTime @@ -1836,14 +1836,14 @@ Callback functions .. c:type:: em_battery_callback_func - Function pointer for the :c:func:`batterymanager event callback functions `, defined as: + Function pointer for the :c:func:`BatteryManager event callback functions `, defined as: .. code-block:: cpp typedef bool (*em_battery_callback_func)(int eventType, const EmscriptenBatteryEvent *batteryEvent, void *userData); - :param int eventType: The type of ``batterymanager`` event (:c:data:`EMSCRIPTEN_EVENT_BATTERYCHARGINGCHANGE`). - :param batteryEvent: Information about the ``batterymanager`` event that occurred. + :param int eventType: The type of ``BatteryManager`` event (:c:data:`EMSCRIPTEN_EVENT_BATTERYCHARGINGCHANGE`). + :param batteryEvent: Information about the ``BatteryManager`` event that occurred. :type batteryEvent: const EmscriptenBatteryEvent* :param void* userData: The ``userData`` originally passed to the registration function. :returns: |callback-handler-return-value-doc| @@ -1857,7 +1857,7 @@ Functions .. c:function:: EMSCRIPTEN_RESULT emscripten_set_batterychargingchange_callback(void *userData, em_battery_callback_func callback) EMSCRIPTEN_RESULT emscripten_set_batterylevelchange_callback(void *userData, em_battery_callback_func callback) - Registers a callback function for receiving the `batterymanager `_ events: ``chargingchange`` and ``levelchange``. + Registers a callback function for receiving the `BatteryManager `_ events: ``chargingchange`` and ``levelchange``. :param void* userData: |userData-parameter-doc| :param em_battery_callback_func callback: |callback-function-parameter-doc| diff --git a/site/source/docs/api_reference/index.rst b/site/source/docs/api_reference/index.rst index 944c8fe1c0308..983cbaa97e1cc 100644 --- a/site/source/docs/api_reference/index.rst +++ b/site/source/docs/api_reference/index.rst @@ -14,7 +14,7 @@ high level it consists of: Low level glue bindings for interfacing with HTML5 APIs from native code. - :ref:`console-h`: - Functions to writing to the console and stdout/stderr. + Functions for writing to the console and stdout/stderr. - :ref:`preamble-js`: APIs for working with compiled code from JavaScript. diff --git a/site/source/docs/api_reference/preamble.js.rst b/site/source/docs/api_reference/preamble.js.rst index c2bd9829f95f5..5819f72286946 100644 --- a/site/source/docs/api_reference/preamble.js.rst +++ b/site/source/docs/api_reference/preamble.js.rst @@ -81,7 +81,7 @@ Calling compiled C functions from JavaScript Returns a native JavaScript wrapper for a C function. - This is similar to :js:func:`ccall`, but returns a JavaScript function that can be reused as many time as needed. The C function can be defined in a C file, or be a C-compatible C++ function defined using ``extern "C"`` (to prevent name mangling). + This is similar to :js:func:`ccall`, but returns a JavaScript function that can be reused as many times as needed. The C function can be defined in a C file, or be a C-compatible C++ function defined using ``extern "C"`` (to prevent name mangling). .. code-block:: javascript @@ -239,7 +239,7 @@ Conversion functions — strings, pointers and arrays .. js:function:: intArrayFromString(stringy, dontAddNull[, length]) - This converts a JavaScript string into a C-line array of numbers, 0-terminated. + This converts a JavaScript string into a C-like array of numbers, 0-terminated. :param stringy: The string to be converted. :type stringy: String @@ -251,7 +251,7 @@ Conversion functions — strings, pointers and arrays .. js:function:: intArrayToString(array) - This creates a JavaScript string from a zero-terminated C-line array of numbers. + This creates a JavaScript string from a zero-terminated C-like array of numbers. :param array: The array to convert. :returns: A ``String``, containing the content of ``array``. diff --git a/site/source/docs/api_reference/wasm_workers.rst b/site/source/docs/api_reference/wasm_workers.rst index ee94bdd56ed88..2cfcaae186cc6 100644 --- a/site/source/docs/api_reference/wasm_workers.rst +++ b/site/source/docs/api_reference/wasm_workers.rst @@ -117,8 +117,6 @@ If you need to synchronously wait for the posted function to finish from within the ``emscripten_wasm_worker_*()`` thread synchronization functions to sleep the calling thread until the callee has finished the operation. -Note that Wasm Workers cannot - Pthreads have cancellation points ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -371,7 +369,7 @@ Both APIs allow one to spawn Web Workers from the main thread, though the semant With the Worker API, the user will be able to spawn a Web Worker from a custom URL. This URL can point to a completely separate JS file that was not compiled with Emscripten, to load up Workers from arbitrary URLs. With Wasm Workers, a custom URL is not specified: Wasm Workers will always spawn a Web Worker that computes in the same WebAssembly+JavaScript context as the main program. -The Worker API does not integrate with SharedArrayBuffer, so interaction with the loaded Worker will always be asynchronous. Wasm Workers howerer is built on top of SharedArrayBuffer, and each Wasm Worker shares and computes in the same WebAssembly Memory address space of the main thread. +The Worker API does not integrate with SharedArrayBuffer, so interaction with the loaded Worker will always be asynchronous. Wasm Workers however is built on top of SharedArrayBuffer, and each Wasm Worker shares and computes in the same WebAssembly Memory address space of the main thread. Both the Worker API and Wasm Workers API provide the user with ability to postMessage() function calls to the Worker. In Worker API, this message posting is restricted to need to originate/initiate from the main thread towards the Worker (using the API ``emscripten_call_worker()`` and ``emscripten_worker_respond()`` in ````). With Wasm Workers however one can also postMessage() function calls to their parent (owning) thread. 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 df24418b6b0e5..80ebe6fc88930 100644 --- a/site/source/docs/building_from_source/configuring_emscripten_settings.rst +++ b/site/source/docs/building_from_source/configuring_emscripten_settings.rst @@ -45,7 +45,7 @@ Locating the compiler configuration file (.emscripten) ====================================================== The settings file (``.emscripten``) is created by default within the emscripten -directory (alongsize ``emcc`` itself). In cases where the emscripten directory +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 diff --git a/site/source/docs/building_from_source/index.rst b/site/source/docs/building_from_source/index.rst index af98f2a9cdfee..118c7d5c10184 100644 --- a/site/source/docs/building_from_source/index.rst +++ b/site/source/docs/building_from_source/index.rst @@ -13,7 +13,7 @@ before it can be used (e.g. ``npm install``). The ``bootstrap`` script in the top level of the repository takes care of running these steps and ``emcc`` will error out if it detects that ``bootstrap`` needs to be run. -Emscripten comes with its own versions some C/C++ system libaries which ``emcc`` +Emscripten comes with its own versions of some C/C++ system libraries which ``emcc`` builds automatically as and when needed (in the emsdk builds, these are precompiled). You can also build them manually with the ``embuilder`` tool - see ``embuilder --help`` for more information. 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 208d97a996d07..30bef9734a0bd 100644 --- a/site/source/docs/building_from_source/verify_emscripten_environment.rst +++ b/site/source/docs/building_from_source/verify_emscripten_environment.rst @@ -31,7 +31,7 @@ could not be found: shared:INFO: (Emscripten: Running sanity checks) emcc: warning: LLVM version for clang executable "/usr/bin/clang" appears incorrect (seeing "16.0", expected "18") [-Wversion-check] -At this point you need to :ref:`Install and activate ` any missing components. When everything is set up properly, ``emcc ---check`` should give no warnings, and if you just enter ``emcc`` (without any input files), it will give an error :: +At this point you need to :ref:`Install and activate ` any missing components. When everything is set up properly, ``emcc --check`` should give no warnings, and if you just enter ``emcc`` (without any input files), it will give an error :: emcc: error: no input files diff --git a/site/source/docs/compiling/Building-Projects.rst b/site/source/docs/compiling/Building-Projects.rst index 72fdc611c3ad8..d2432fa55cfdf 100644 --- a/site/source/docs/compiling/Building-Projects.rst +++ b/site/source/docs/compiling/Building-Projects.rst @@ -101,7 +101,7 @@ This list is not exhaustive, but illustrates most commonly used combinations. .. note:: Regardless of the name of the output file ``emcc`` will always perform linking and produce a final executable, unless a specific flags (e.g. ``-c``) - direct it do something else. This differs to previous behaviour where + direct it to do something else. This differs to previous behaviour where ``emcc`` would default to combining object files (essentially assuming ``-r``) unless given a specific executable extension (e.g. ``.js`` or ``.html``). diff --git a/site/source/docs/compiling/Dynamic-Linking.rst b/site/source/docs/compiling/Dynamic-Linking.rst index 2732cfc50b6fc..81487447de38e 100644 --- a/site/source/docs/compiling/Dynamic-Linking.rst +++ b/site/source/docs/compiling/Dynamic-Linking.rst @@ -12,7 +12,7 @@ with little or no changes (see :ref:`Building-Projects`). In addition, Emscripten also has support for a form of **dynamic** linking of WebAssembly modules. This can add overhead, so for best performance static -linking should still be preferred. However, this overhead can can be reduced +linking should still be preferred. However, this overhead can be reduced with the use of certain command line flags. See below for details. Background @@ -127,7 +127,7 @@ the command line when you link the main module. e.g. emcc -sMAIN_MODULE main.c libsomething.wasm -At runtime, the JavaScript loading code will load ``libsomthing.wasm`` (along +At runtime, the JavaScript loading code will load ``libsomething.wasm`` (along with any other side modules) along with the main module before the application starts to run. The running application then can access code from any of the modules linked together. @@ -218,7 +218,7 @@ Limitations Pthreads support ---------------- -Dynamic linking + pthreads is is still experimental. As such, linking with both +Dynamic linking + pthreads is still experimental. As such, linking with both :ref:`MAIN_MODULE` and ``-pthread`` will produce a warning. While load-time dynamic linking works without any complications, runtime dynamic @@ -238,6 +238,6 @@ However, there there is one class of application that currently may require modification. If your applications busy waits, or directly uses the ``atomic.waitXX`` instructions (or the clang ``__builtin_wasm_memory_atomic_waitXX`` builtins) you maybe need to switch it -to use ``emscripten_futex_wait`` or order avoid deadlocks. If you don't use +to use ``emscripten_futex_wait`` in order to avoid deadlocks. If you don't use ``emscripten_futex_wait`` while you block, you could potentially block other threads that are calling ``dlopen`` and/or ``dlsym``. diff --git a/site/source/docs/compiling/Modularized-Output.rst b/site/source/docs/compiling/Modularized-Output.rst index a4a2bc7b5ad8d..2e14c84252130 100644 --- a/site/source/docs/compiling/Modularized-Output.rst +++ b/site/source/docs/compiling/Modularized-Output.rst @@ -35,7 +35,7 @@ separate and isolated instances of the same program. By default, the factory function is called ``Module``, but it can be given a unique name via the ``-sEXPORT_NAME`` setting. -For example, a program is built using ``-sMODULARIZE -sEXPORT_NAME=Foo`` can +For example, a program built using ``-sMODULARIZE -sEXPORT_NAME=Foo`` can be instantiated using: :: @@ -113,11 +113,11 @@ Limitations ----------- Some major features still do not work in this mode. Many of these we hope to -fix in future releses. Current limitations include: +fix in future releases. Current limitations include: -* Internal usage (e.g. usage within EM_JS / JS libary code) of the ``Module`` +* Internal usage (e.g. usage within EM_JS / JS library code) of the ``Module`` global does not work. This is because symbols are exported directly using - ES6 module syntax rathar than using the ``Module`` global. + ES6 module syntax rather than using the ``Module`` global. * The ``wasmExports`` internal global does not exist. @@ -133,7 +133,7 @@ Source Phase Imports (experimental) =================================== `Source phase imports`_ is a JavaScript proposal that adds support for importing -Wasm modules via ES import statements. This allows emscripten to elide some of +Wasm modules via ES import statements. This allows Emscripten to elide some of the auto-generated code for finding and fetching the Wasm binary. See :ref:`source_phase_imports`. @@ -146,7 +146,7 @@ ES Module Integration (experimental) ==================================== `Wasm ESM integration`_ is a WebAssembly proposal that allows Wasm instances to -be imported directly as ES modules. This allows emscripten to elide a lot of +be imported directly as ES modules. This allows Emscripten to elide a lot of boilerplate code for linking up Wasm and JavaScript. See :ref:`wasm_esm_integration`. @@ -156,7 +156,7 @@ Limitations This setting implicitly enables :ref:`export_es6` and sets :ref:`MODULARIZE` to ``instance``. Because of this all the same limitations mentioned above for -``-sMODULARIZE=intance`` apply. +``-sMODULARIZE=instance`` apply. Some additional limitations are: 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 7324d3a000a26..8fa5aa56813a4 100644 --- a/site/source/docs/compiling/Running-html-files-with-emrun.rst +++ b/site/source/docs/compiling/Running-html-files-with-emrun.rst @@ -110,7 +110,7 @@ The following command line flags affect logging output: - ``--verbose``: Print detailed information about *emrun* internal steps. - ``--log_stdout ``: Write all ``stdout`` messages from the application to the named file (instead of printing to terminal). -- ``--lot_stderr ``: Write all ``stderr`` messages from the application to the named file (instead of printing to terminal). +- ``--log_stderr ``: Write all ``stderr`` messages from the application to the named file (instead of printing to terminal). - ``--system_info``: Print detailed information about the current system before launching. This is useful during automated runs when you want to capture hardware information to logs. - ``--browser_info``: Print information about which browser is about to be launched. - ``--no_emrun_detect``: Hide the warning message that is launched if a target **.html** file is detected to not have been built with ``--emrun``. diff --git a/site/source/docs/compiling/WebAssembly.rst b/site/source/docs/compiling/WebAssembly.rst index 8e6b3953be8a3..c7b939edbb2af 100644 --- a/site/source/docs/compiling/WebAssembly.rst +++ b/site/source/docs/compiling/WebAssembly.rst @@ -97,7 +97,7 @@ WebAssembly feature extensions ============================== Since its original launch, WebAssembly has been expanded with various feature -extensions, which have been implmented in browsers. A list of features +extensions, which have been implemented in browsers. A list of features (including already-shipped and in-progress) and details about browser versions that support them can be found on `webassembly.org `_. diff --git a/site/source/docs/contributing/developers_guide.rst b/site/source/docs/contributing/developers_guide.rst index 7fe05e8c6744f..0f00b0bf54a8d 100644 --- a/site/source/docs/contributing/developers_guide.rst +++ b/site/source/docs/contributing/developers_guide.rst @@ -26,7 +26,7 @@ get using the emsdk: emsdk install tot emsdk activate tot -This with install the latest "tip-of-tree" binaries needed to run Emscripten. +This will install the latest "tip-of-tree" binaries needed to run Emscripten. You can use these emsdk-provided binaries with a git checkout of the Emscripten repository. To do this, you can either edit your local ``.emscripten`` config file, or set ``EM_CONFIG=/path/to/emsdk/.emscripten`` in your environment. diff --git a/site/source/docs/getting_started/Tutorial.rst b/site/source/docs/getting_started/Tutorial.rst index 256bab304cbdf..8ac56e1418e07 100644 --- a/site/source/docs/getting_started/Tutorial.rst +++ b/site/source/docs/getting_started/Tutorial.rst @@ -13,7 +13,7 @@ First things first ====================== Make sure you have :ref:`downloaded and installed ` -Emscripten (the exact approach for doing this will depend your operating system: +Emscripten (the exact approach for doing this will depend on your operating system: Linux, Windows, or Mac). Emscripten is accessed using the :ref:`emccdoc`. This script invokes all the diff --git a/site/source/docs/getting_started/downloads.rst b/site/source/docs/getting_started/downloads.rst index 3ef3796a2e2aa..845e2bf74495c 100644 --- a/site/source/docs/getting_started/downloads.rst +++ b/site/source/docs/getting_started/downloads.rst @@ -60,7 +60,7 @@ GitHub and set them as :term:`active `: .. note:: ``git pull`` will fetch the current list of tags, but very recent ones may not yet be present there. You can run ``./emsdk update-tags`` to update the list of tags directly. -If you change the location of the SDK (e.g. take it to another computer on an +If you change the location of the SDK (e.g. take it to another computer on a USB), re-run the ``./emsdk activate latest`` and ``source ./emsdk_env.sh`` commands. @@ -92,7 +92,7 @@ using a more careful procedure). Tip-of-tree builds may be useful for continuous integration that uses the emsdk (as Emscripten's GitHub CI does), and you may want to use it in your own CI as well, so that if you find a regression on your project you can report it and prevent it from reaching a tagged release. -Tip-of-builds may also be useful if you want to test a feature that just landed +Tip-of-tree builds may also be useful if you want to test a feature that just landed 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, diff --git a/site/source/docs/introducing_emscripten/community.rst b/site/source/docs/introducing_emscripten/community.rst index 791520be2b3e9..f6eed6967722c 100644 --- a/site/source/docs/introducing_emscripten/community.rst +++ b/site/source/docs/introducing_emscripten/community.rst @@ -12,7 +12,7 @@ Welcome to the Emscripten community! Get in touch ============ -The best ways contact the community are: +The best ways to contact the community are: - The GitHub `Issue Tracker `_ - Mailing list: `emscripten-discuss `_ diff --git a/site/source/docs/introducing_emscripten/emscripten_license.rst b/site/source/docs/introducing_emscripten/emscripten_license.rst index 6971453752c03..9af8232340e0d 100644 --- a/site/source/docs/introducing_emscripten/emscripten_license.rst +++ b/site/source/docs/introducing_emscripten/emscripten_license.rst @@ -11,7 +11,7 @@ There is little, if any, practical difference between the licenses. They are bot - *MIT license* is well known and understood. - *University of Illinois/NCSA Open Source License* allows Emscripten's code to be integrated upstream into LLVM, should the opportunity arise. -The license for Emscripten |release| is reproduced below. The `current full licence `_ can be found on GitHub (and is also present in the root of the SDK). +The license for Emscripten |release| is reproduced below. The `current full license `_ can be found on GitHub (and is also present in the root of the SDK). .. include:: ../../../../LICENSE :literal: diff --git a/site/source/docs/optimizing/Optimizing-Code.rst b/site/source/docs/optimizing/Optimizing-Code.rst index 987b876390a49..cc6a8f63bd916 100644 --- a/site/source/docs/optimizing/Optimizing-Code.rst +++ b/site/source/docs/optimizing/Optimizing-Code.rst @@ -124,7 +124,7 @@ 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 of 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 diff --git a/site/source/docs/porting/Debugging.rst b/site/source/docs/porting/Debugging.rst index 8573de6f3af75..2d47526b61b21 100644 --- a/site/source/docs/porting/Debugging.rst +++ b/site/source/docs/porting/Debugging.rst @@ -86,7 +86,7 @@ function names, and variable names, which makes the JavaScript debuggable). The ``-g`` flag can also be specified with integer levels: :ref:`-g0 `, :ref:`-g1 `, :ref:`-g2 `, and :ref:`-g3 ` (equivalent to ``-g``). At compile time these flags control the amount of DWARF in the -object files. At link time, each adds sucessively more kinds of information in +object files. At link time, each adds successively more kinds of information in the wasm and JS files (DWARF is only retained after linking when using ``-g`` or ``-g3``). @@ -140,7 +140,7 @@ is also passed at link time. DWARF can also be used for this purpose. Typically a binary containing DWARF would be generated at build time, and then stripped. The stripped copy would be served to users, and the original would be saved for symbolication purposes. For -this use case, full information about about types and variables from the sources +this use case, full information about types and variables from the sources isn't needed; the `-gline-tables-only `_ compile-time flag causes clang to generate only the line table information, diff --git a/site/source/docs/porting/asyncify.rst b/site/source/docs/porting/asyncify.rst index 0891e5e7041d6..3ab48444d526f 100644 --- a/site/source/docs/porting/asyncify.rst +++ b/site/source/docs/porting/asyncify.rst @@ -480,7 +480,7 @@ later callback, when nothing else is on the stack. Migrating from older Asyncify APIs ################################## -If you have code uses the old Emterpreter-Async API, or the old Asyncify, then +If you have code that uses the old Emterpreter-Async API, or the old Asyncify, then almost everything should just work when you replace ``-sEMTERPRETIFY`` usage with ``-sASYNCIFY``. In particular all the things like ``emscripten_wget`` should just work as they did before. 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 7676b1ab28528..9a0fa631c0e0b 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 @@ -436,7 +436,7 @@ that you can't use a closure directly, for example, as ``toString`` isn't compatible with that - just like when using a string to create a Web Worker, where you also can't pass a closure. (Note that this limitation is just for the values for the keys of the object -passes to ``addToLibrary`` in the JS library, that is, the toplevel +passed to ``addToLibrary`` in the JS library, that is, the toplevel key-value pairs are special. Interior code inside a function can have arbitrary JS, of course). @@ -667,7 +667,7 @@ a 53 bit (double) and returns an integer error code: 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 useable value. See `settings reference `_. +side to convert it to a usable value. See `settings reference `_. .. _interacting-with-code-access-memory: diff --git a/site/source/docs/porting/connecting_cpp_and_javascript/embind.rst b/site/source/docs/porting/connecting_cpp_and_javascript/embind.rst index b697a996bda38..8fe77a59405a6 100644 --- a/site/source/docs/porting/connecting_cpp_and_javascript/embind.rst +++ b/site/source/docs/porting/connecting_cpp_and_javascript/embind.rst @@ -379,7 +379,7 @@ JavaScript and C++ have very different memory models which can lead to it being unclear which language owns and is responsible for deleting an object when it moves between languages. To make object ownership more explicit, *embind* supports smart pointers and return value policies. Return value -polices dictate what happens to a C++ object when it is returned to JavaScript. +policies dictate what happens to a C++ object when it is returned to JavaScript. To use a return value policy, pass the desired policy into function, method, or property bindings. For example: diff --git a/site/source/docs/porting/guidelines/function_pointer_issues.rst b/site/source/docs/porting/guidelines/function_pointer_issues.rst index 8853679e0cd6d..b3e0182f38d4c 100644 --- a/site/source/docs/porting/guidelines/function_pointer_issues.rst +++ b/site/source/docs/porting/guidelines/function_pointer_issues.rst @@ -45,7 +45,7 @@ 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 be worth trying. + - 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/multimedia_and_graphics/EGL-Support-in-Emscripten.rst b/site/source/docs/porting/multimedia_and_graphics/EGL-Support-in-Emscripten.rst index 043d11dd2aa86..fd52a94dd9bd0 100644 --- a/site/source/docs/porting/multimedia_and_graphics/EGL-Support-in-Emscripten.rst +++ b/site/source/docs/porting/multimedia_and_graphics/EGL-Support-in-Emscripten.rst @@ -118,4 +118,4 @@ Currently, Emscripten does not implement any extensions in the `EGL Extension Re EGL-related bugs and todos --------------------------- -The `Emscripten issue tracker `_ lists EGL-relates issues using the label EGL. Check that page to report or find issues in Emscripten related to EGL. +The `Emscripten issue tracker `_ lists EGL-related issues using the label EGL. Check that page to report or find issues in Emscripten related to EGL. diff --git a/site/source/docs/porting/simd.rst b/site/source/docs/porting/simd.rst index bb8dfed807ae5..48c574c010ce1 100644 --- a/site/source/docs/porting/simd.rst +++ b/site/source/docs/porting/simd.rst @@ -1534,7 +1534,7 @@ status `` [link] - In cases where emscripten performs import/export minificiton this option can + In cases where emscripten performs import/export minification this option can be used to output a file that maps minified names back to their original names. The format of this file is single line per import/export of the form ``:``. diff --git a/site/source/docs/tools_reference/emsdk.rst b/site/source/docs/tools_reference/emsdk.rst index 3e077332d26c9..eaa4f51cea63b 100644 --- a/site/source/docs/tools_reference/emsdk.rst +++ b/site/source/docs/tools_reference/emsdk.rst @@ -229,7 +229,7 @@ particular tool: :: On Windows, calling ``activate`` automatically sets up the required paths and environment variables. -.. note:: If you add ``./emsdk_env.sh`` to you default shell config emsdk tools (including the emsdk version of node) will be added to your PATH and this could effect the default version of node used on your system. +.. note:: If you add ``./emsdk_env.sh`` to you default shell config emsdk tools (including the emsdk version of node) will be added to your PATH and this could affect the default version of node used on your system. .. _emsdk-install-old-tools: @@ -287,7 +287,7 @@ It is also possible to use your own fork of the Emscripten repository via the SDK. This is useful in the case when you want to make your own modifications to the Emscripten toolchain, but still keep using the SDK environment and tools. -To to this all you need to do is set the ``EM_CONFIG`` environment variable to +To do this all you need to do is set the ``EM_CONFIG`` environment variable to point to the emsdk emscripten config and then put your own checkout of emscripten first in the ``PATH``: diff --git a/site/source/docs/tools_reference/settings_reference.rst b/site/source/docs/tools_reference/settings_reference.rst index f499f319a6596..c7a2bc4c9ad22 100644 --- a/site/source/docs/tools_reference/settings_reference.rst +++ b/site/source/docs/tools_reference/settings_reference.rst @@ -36,7 +36,7 @@ Chooses what kind of stack smash checks to emit to generated code: Building with ASSERTIONS=1 causes STACK_OVERFLOW_CHECK default to 1. Since ASSERTIONS=1 is the default at -O0, which itself is the default optimization level this means that this setting also effectively -defaults 1, absent any other settings: +defaults to 1, absent any other settings: - 0: Stack overflows are not checked. - 1: Adds a security cookie at the top of the stack, which is checked at end @@ -134,7 +134,7 @@ What malloc()/free() to use, out of: - emmalloc-verbose - use emmalloc with assertions + verbose logging. - emmalloc-memvalidate-verbose - use emmalloc with assertions + heap consistency checking + verbose logging. - - mimalloc - a powerful mulithreaded allocator. This is recommended in + - 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 @@ -189,7 +189,7 @@ The initial amount of heap memory available to the program. This is the memory region available for dynamic allocations via `sbrk`, `malloc` and `new`. Unlike INITIAL_MEMORY, this setting allows the static and dynamic regions of -your programs memory to independently grow. In most cases we recommend using +your program's memory to independently grow. In most cases we recommend using this setting rather than `INITIAL_MEMORY`. However, this setting does not work for imported memories (e.g. when dynamic linking is used). @@ -322,7 +322,7 @@ Default value: 0 INITIAL_TABLE ============= -Sets the initial size of the table when MAIN_MODULE or SIDE_MODULE is use +Sets the initial size of the table when MAIN_MODULE or SIDE_MODULE is used (and not otherwise). Normally Emscripten can determine the size of the table at link time, but in SPLIT_MODULE mode, wasm-split often needs to grow the table, so the table size baked into the JS for the instrumented build will be @@ -432,7 +432,7 @@ Default value: false SUPPORT_BIG_ENDIAN ================== -If set to 1, perform acorn pass that converts each HEAP access into a +If set to 1, perform an acorn pass that converts each HEAP access into a function call that uses DataView to enforce LE byte order for HEAP buffer; This makes generated JavaScript run on BE as well as LE machines. (If 0, only LE systems are supported). Does not affect generated wasm. @@ -478,8 +478,8 @@ best it can. We use 64 bits (i64) to represent values, as if we wrote the sent value to memory and loaded the received type from the same memory (using truncs/extends/ reinterprets). This means that when types do not match the emulated values may not match (this is true of native too, for that matter - -this is all undefined behavior). This approaches appears good enough to -support Python (the original motiviation for this feature) and Glib (the +this is all undefined behavior). This approach appears good enough to +support Python (the original motivation for this feature) and Glib (the continued motivation). Default value: false @@ -552,10 +552,10 @@ SOCKET_WEBRTC As well as being configurable at compile time via the "-s" option the WEBSOCKET_URL and WEBSOCKET_SUBPROTOCOL -settings may configured at run time via the Module object e.g. +settings may be configured at run time via the Module object e.g. Module['websocket'] = {subprotocol: 'base64, binary, text'}; Module['websocket'] = {url: 'wss://', subprotocol: 'base64'}; -You can set 'subprotocol' to null, if you don't want to specify it +You can set 'subprotocol' to null, if you don't want to specify it. Run time configuration may be useful as it lets an application select multiple different services. @@ -566,7 +566,7 @@ Default value: false WEBSOCKET_URL ============= -A string containing either a WebSocket URL prefix (ws:// or wss://) or a' +A string containing either a WebSocket URL prefix (ws:// or wss://) or a complete RFC 6455 URL - "ws[s]:" "//" host [ ":" port ] path [ "?" query ]. In the (default) case of only a prefix being specified the URL will be constructed from prefix + addr + ':' + port @@ -701,7 +701,7 @@ Default value: true GL_EXTENSIONS_IN_PREFIXED_FORMAT ================================ -If true, all GL extensions are advertised in both unprefixed WebGL extension +If true, all GL extensions are advertised in unprefixed WebGL extension format, but also in desktop/mobile GLES/GL extension format with ``GL_`` prefix. @@ -838,7 +838,7 @@ If true, emulates some WebGL 1 features on WebGL 2 contexts, meaning that applications that use WebGL 1/GLES 2 can initialize a WebGL 2/GLES3 context, but still keep using WebGL1/GLES 2 functionality that no longer is supported in WebGL2/GLES3. Currently this emulates GL_EXT_shader_texture_lod extension -in GLSLES 1.00 shaders, support for unsized internal texture formats, and the +in GLSL ES 1.00 shaders, support for unsized internal texture formats, and the GL_HALF_FLOAT_OES != GL_HALF_FLOAT mixup. Default value: false @@ -985,9 +985,9 @@ ENVIRONMENT =========== Specify which runtime environments the JS output will be capable of running -in. For maximum portability this can configured to support all environments -or it can be limited to reduce overall code size. The supported environments -are: +in. For maximum portability this can be configured to support all +environments or it can be limited to reduce overall code size. The supported +environments are: - 'web' - the normal web environment. - 'webview' - just like web, but in a webview like Cordova; considered to be @@ -1189,12 +1189,12 @@ Default value: false NODEJS_CATCH_REJECTION ====================== -Catch unhandled rejections in node. This only effect versions of node older +Catch unhandled rejections in node. This only affects versions of node older than 15. Without this, old version node will print a warning, but exit with a zero return code. With this setting enabled, we handle any unhandled -rejection and throw an exception, which will cause the process exit +rejection and throw an exception, which will cause the process to exit immediately with a non-0 return code. -This not needed in Node 15+ so this setting will default to false if +This is not needed in Node 15+ so this setting will default to false if MIN_NODE_VERSION is 150000 or above. Default value: true @@ -1379,7 +1379,7 @@ JSPI Use VM support for the JavaScript Promise Integration proposal. This allows async operations to happen without the overhead of modifying the wasm. This -is experimental atm while spec discussion is ongoing, see +is experimental at the moment while spec discussion is ongoing, see https://github.com/WebAssembly/js-promise-integration/ TODO: document which of the following flags are still relevant in this mode (e.g. IGNORE_INDIRECT etc. are not needed) @@ -1443,8 +1443,8 @@ you have this:: preRun: [() => console.log('pre run')] }; -Then MODULE_JS_API must contain 'print' and 'preRun'; if it does not then -we may not emit code to read and use that value. In other words, this +Then INCOMING_MODULE_JS_API must contain 'print' and 'preRun'; if it does not +then we may not emit code to read and use that value. In other words, this option lets you set, statically at compile time, the list of which Module JS values you will be providing at runtime, so the compiler can better optimize. @@ -1462,7 +1462,7 @@ Default value: (multi-line value, see settings.js) CASE_INSENSITIVE_FS =================== -If set to nonzero, the provided virtual filesystem if treated +If set to nonzero, the provided virtual filesystem is treated case-insensitive, like Windows and macOS do. If set to 0, the VFS is case-sensitive, like on Linux. @@ -1804,7 +1804,7 @@ implement everything, when you know what is not going to actually be called (and don't want to mess with the existing buildsystem), and functions might be implemented later on, say in --pre-js, so you may want to build with -s WARN_ON_UNDEFINED_SYMBOLS=0 to disable the warnings if they annoy you. See -also ERROR_ON_UNDEFINED_SYMBOLS. Any undefined symbols that are listed in- +also ERROR_ON_UNDEFINED_SYMBOLS. Any undefined symbols that are listed in EXPORTED_FUNCTIONS will also be reported. Default value: true @@ -2098,7 +2098,7 @@ Default value: false BINARYEN_EXTRA_PASSES ===================== -A comma-separated list of extra passes to run in the binaryen optimizer, +A comma-separated list of extra passes to run in the binaryen optimizer. Setting this does not override/replace the default passes. It is appended at the end of the list of passes. @@ -2922,7 +2922,7 @@ MIN_FIREFOX_VERSION Specifies the oldest major version of Firefox to target. I.e. all Firefox versions >= MIN_FIREFOX_VERSION are desired to work. Pass -sMIN_FIREFOX_VERSION=majorVersion to drop support -for Firefox versions older than < majorVersion. +for Firefox versions older than majorVersion. Firefox 79 was released on 2020-07-28. MAX_INT (0x7FFFFFFF, or -1) specifies that target is not supported. Minimum supported value is 68 which was released on 2019-07-09 (see @@ -2974,7 +2974,7 @@ MIN_NODE_VERSION ================ Specifies minimum node version to target for the generated code. This is -distinct from the minimum version required run the emscripten compiler. +distinct from the minimum version required to run the emscripten compiler. Version is encoded in MMmmVV, e.g. 181401 denotes Node 18.14.01. Minimum supported value is 122209, which was released 2022-01-11 (see feature_matrix.py). This version aligns with the Ubuntu TLS 22.04 (Jammy). @@ -3084,11 +3084,11 @@ HTML5_SUPPORT_DEFERRING_USER_SENSITIVE_REQUESTS Certain browser DOM API operations, such as requesting fullscreen mode transition or pointer lock require that the request originates from within -an user initiated event, such as mouse click or keyboard press. Refactoring +a user initiated event, such as mouse click or keyboard press. Refactoring an application to follow this kind of program structure can be difficult, so HTML5_SUPPORT_DEFERRING_USER_SENSITIVE_REQUESTS allows transparent emulation of this by deferring such requests until a suitable event callback is -generated. Set this to 0 to disable support for deferring to on save code +generated. Set this to 0 to disable support for deferring to save code size if your application does not need support for deferred calls. Default value: true @@ -3138,9 +3138,9 @@ Default value: [] DEFAULT_TO_CXX ============== -Default to c++ mode even when run as ``emcc`` rather then ``emc++``. -When this is disabled ``em++`` is required linking C++ programs. Disabling -this will match the behaviour of gcc/g++ and clang/clang++. +Default to c++ mode even when run as ``emcc`` rather than ``emc++``. +When this is disabled ``em++`` is required when linking C++ programs. +Disabling this will match the behaviour of gcc/g++ and clang/clang++. Default value: true @@ -3193,7 +3193,7 @@ Default value: false ABORT_ON_WASM_EXCEPTIONS ======================== -Abort on unhandled excptions that occur when calling exported WebAssembly +Abort on unhandled exceptions that occur when calling exported WebAssembly functions. This makes the program behave more like a native program where the OS would terminate the process and no further code can be executed when an unhandled exception (e.g. out-of-bounds memory access) happens. @@ -3206,7 +3206,7 @@ overhead for the extra instrumented function indirection. Enable this if you want Emscripten to handle unhandled exceptions nicely at the cost of a few bytes extra. Exceptions that occur within the ``main`` function are already handled via an -alternative mechanimsm. +alternative mechanism. Default value: false @@ -3249,13 +3249,13 @@ Default value: false SPLIT_MODULE ============ -Generate code to loading split wasm modules. +Generate code to load split wasm modules. This option will automatically generate two wasm files as output, one with the ``.orig`` suffix and one without. The default file (without -the suffix) when run will generate instrumentation data can later be +the suffix) when run will generate instrumentation data that can later be fed into wasm-split (the binaryen tool). -As well as this the generated JS code will contains helper functions -to loading split modules. +As well as this the generated JS code will contain helper functions +to load split modules. .. note:: This is an experimental setting @@ -3444,7 +3444,7 @@ FAKE_DYLIBS This setting changes the behaviour of the ``-shared`` flag. The default setting of ``true`` means the ``-shared`` flag actually produces a normal object file (i.e. ``ld -r``). Setting this to false will cause ``-shared`` -to behave like :ref:`SIDE_MODULE` and produce and dynamically linked +to behave like :ref:`SIDE_MODULE` and produce a dynamically linked library. Default value: true @@ -3456,8 +3456,8 @@ Deprecated Settings =================== The following settings have been proposed for removal from emscripten. These settings -still function but may be removed in a future version. If your project is using of -the these settings please open a bug (or reply to one of the existing bugs). +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 @@ -3473,7 +3473,7 @@ Legacy Settings =============== The following settings no longer have any effect but are still accepted by emscripten -for backwards compatbility with older versions: +for backwards compatibility with older versions: - ``BINARYEN``: Valid values: WASM - ``TOTAL_STACK``: Valid values: STACK_SIZE diff --git a/src/settings.js b/src/settings.js index 99a624b1db406..fce354fe273a0 100644 --- a/src/settings.js +++ b/src/settings.js @@ -55,7 +55,7 @@ var ASSERTIONS = 1; // Building with ASSERTIONS=1 causes STACK_OVERFLOW_CHECK default to 1. // Since ASSERTIONS=1 is the default at -O0, which itself is the default // optimization level this means that this setting also effectively -// defaults 1, absent any other settings: +// defaults to 1, absent any other settings: // // - 0: Stack overflows are not checked. // - 1: Adds a security cookie at the top of the stack, which is checked at end @@ -122,7 +122,7 @@ var STACK_SIZE = 64*1024; // - emmalloc-verbose - use emmalloc with assertions + verbose logging. // - emmalloc-memvalidate-verbose - use emmalloc with assertions + heap // consistency checking + verbose logging. -// - mimalloc - a powerful mulithreaded allocator. This is recommended in +// - 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 @@ -168,7 +168,7 @@ var ABORTING_MALLOC = true; // memory region available for dynamic allocations via `sbrk`, `malloc` and `new`. // // Unlike INITIAL_MEMORY, this setting allows the static and dynamic regions of -// your programs memory to independently grow. In most cases we recommend using +// your program's memory to independently grow. In most cases we recommend using // this setting rather than `INITIAL_MEMORY`. However, this setting does not work // for imported memories (e.g. when dynamic linking is used). // @@ -260,7 +260,7 @@ var MEMORY_GROWTH_LINEAR_STEP = -1; // [compile+link] var MEMORY64 = 0; -// Sets the initial size of the table when MAIN_MODULE or SIDE_MODULE is use +// Sets the initial size of the table when MAIN_MODULE or SIDE_MODULE is used // (and not otherwise). Normally Emscripten can determine the size of the table // at link time, but in SPLIT_MODULE mode, wasm-split often needs to grow the // table, so the table size baked into the JS for the instrumented build will be @@ -322,7 +322,7 @@ var DECLARE_ASM_MODULE_EXPORTS = true; // [compile] var INLINING_LIMIT = false; -// If set to 1, perform acorn pass that converts each HEAP access into a +// If set to 1, perform an acorn pass that converts each HEAP access into a // function call that uses DataView to enforce LE byte order for HEAP buffer; // This makes generated JavaScript run on BE as well as LE machines. (If 0, only // LE systems are supported). Does not affect generated wasm. @@ -351,8 +351,8 @@ var SAFE_HEAP_LOG = false; // sent value to memory and loaded the received type from the same memory (using // truncs/extends/ reinterprets). This means that when types do not match the // emulated values may not match (this is true of native too, for that matter - -// this is all undefined behavior). This approaches appears good enough to -// support Python (the original motiviation for this feature) and Glib (the +// this is all undefined behavior). This approach appears good enough to +// support Python (the original motivation for this feature) and Glib (the // continued motivation). // [link] var EMULATE_FUNCTION_POINTER_CASTS = false; @@ -394,16 +394,16 @@ var FS_DEBUG = false; // As well as being configurable at compile time via the "-s" option the // WEBSOCKET_URL and WEBSOCKET_SUBPROTOCOL -// settings may configured at run time via the Module object e.g. +// settings may be configured at run time via the Module object e.g. // Module['websocket'] = {subprotocol: 'base64, binary, text'}; // Module['websocket'] = {url: 'wss://', subprotocol: 'base64'}; -// You can set 'subprotocol' to null, if you don't want to specify it +// You can set 'subprotocol' to null, if you don't want to specify it. // Run time configuration may be useful as it lets an application select // multiple different services. // [link] var SOCKET_WEBRTC = false; -// A string containing either a WebSocket URL prefix (ws:// or wss://) or a' +// A string containing either a WebSocket URL prefix (ws:// or wss://) or a // complete RFC 6455 URL - "ws[s]:" "//" host [ ":" port ] path [ "?" query ]. // In the (default) case of only a prefix being specified the URL will be // constructed from prefix + addr + ':' + port @@ -473,7 +473,7 @@ var FULL_ES2 = false; // [link] var GL_EMULATE_GLES_VERSION_STRING_FORMAT = true; -// If true, all GL extensions are advertised in both unprefixed WebGL extension +// If true, all GL extensions are advertised in unprefixed WebGL extension // format, but also in desktop/mobile GLES/GL extension format with ``GL_`` // prefix. // [link] @@ -553,7 +553,7 @@ var MAX_WEBGL_VERSION = 1; // applications that use WebGL 1/GLES 2 can initialize a WebGL 2/GLES3 context, // but still keep using WebGL1/GLES 2 functionality that no longer is supported // in WebGL2/GLES3. Currently this emulates GL_EXT_shader_texture_lod extension -// in GLSLES 1.00 shaders, support for unsized internal texture formats, and the +// in GLSL ES 1.00 shaders, support for unsized internal texture formats, and the // GL_HALF_FLOAT_OES != GL_HALF_FLOAT mixup. // [link] var WEBGL2_BACKWARDS_COMPATIBILITY_EMULATION = false; @@ -640,9 +640,9 @@ var POLYFILL_OLD_MATH_FUNCTIONS = false; var LEGACY_VM_SUPPORT = false; // Specify which runtime environments the JS output will be capable of running -// in. For maximum portability this can configured to support all environments -// or it can be limited to reduce overall code size. The supported environments -// are: +// in. For maximum portability this can be configured to support all +// environments or it can be limited to reduce overall code size. The supported +// environments are: // // - 'web' - the normal web environment. // - 'webview' - just like web, but in a webview like Cordova; considered to be @@ -691,7 +691,7 @@ var ENVIRONMENT = ['web', 'webview', 'worker', 'node']; var LZ4 = false; // Emscripten (JavaScript-based) exception handling options. -// The three relatated settings (:ref:`DISABLE_EXCEPTION_CATCHING`, +// The three related settings (:ref:`DISABLE_EXCEPTION_CATCHING`, // :ref:`EXCEPTION_CATCHING_ALLOWED`, and :ref:`DISABLE_EXCEPTION_THROWING`) // only pertain to JavaScript-based exception handling and do not control the // native Wasm exception handling option (``-fwasm-exceptions``) @@ -801,12 +801,12 @@ var WASM_LEGACY_EXCEPTIONS = true; // [link] var NODEJS_CATCH_EXIT = false; -// Catch unhandled rejections in node. This only effect versions of node older +// Catch unhandled rejections in node. This only affects versions of node older // than 15. Without this, old version node will print a warning, but exit // with a zero return code. With this setting enabled, we handle any unhandled -// rejection and throw an exception, which will cause the process exit +// rejection and throw an exception, which will cause the process to exit // immediately with a non-0 return code. -// This not needed in Node 15+ so this setting will default to false if +// This is not needed in Node 15+ so this setting will default to false if // MIN_NODE_VERSION is 150000 or above. // [link] var NODEJS_CATCH_REJECTION = true; @@ -932,7 +932,7 @@ var ASYNCIFY_EXPORTS = []; // Use VM support for the JavaScript Promise Integration proposal. This allows // async operations to happen without the overhead of modifying the wasm. This -// is experimental atm while spec discussion is ongoing, see +// is experimental at the moment while spec discussion is ongoing, see // https://github.com/WebAssembly/js-promise-integration/ TODO: document which // of the following flags are still relevant in this mode (e.g. IGNORE_INDIRECT // etc. are not needed) @@ -978,8 +978,8 @@ var EXPORTED_RUNTIME_METHODS = []; // preRun: [() => console.log('pre run')] // }; // -// Then MODULE_JS_API must contain 'print' and 'preRun'; if it does not then -// we may not emit code to read and use that value. In other words, this +// Then INCOMING_MODULE_JS_API must contain 'print' and 'preRun'; if it does not +// then we may not emit code to read and use that value. In other words, this // option lets you set, statically at compile time, the list of which Module // JS values you will be providing at runtime, so the compiler can better // optimize. @@ -1006,7 +1006,7 @@ var INCOMING_MODULE_JS_API = [ 'stdin', 'stdout', 'thisProgram', 'wasm', 'wasmBinary', 'websocket' ]; -// If set to nonzero, the provided virtual filesystem if treated +// If set to nonzero, the provided virtual filesystem is treated // case-insensitive, like Windows and macOS do. If set to 0, the VFS is // case-sensitive, like on Linux. // [link] @@ -1225,7 +1225,7 @@ var STRICT_JS = false; // (and don't want to mess with the existing buildsystem), and functions might // be implemented later on, say in --pre-js, so you may want to build with -s // WARN_ON_UNDEFINED_SYMBOLS=0 to disable the warnings if they annoy you. See -// also ERROR_ON_UNDEFINED_SYMBOLS. Any undefined symbols that are listed in- +// also ERROR_ON_UNDEFINED_SYMBOLS. Any undefined symbols that are listed in // EXPORTED_FUNCTIONS will also be reported. // [link] var WARN_ON_UNDEFINED_SYMBOLS = true; @@ -1449,7 +1449,7 @@ var STANDALONE_WASM = false; // [link] var BINARYEN_IGNORE_IMPLICIT_TRAPS = false; -// A comma-separated list of extra passes to run in the binaryen optimizer, +// A comma-separated list of extra passes to run in the binaryen optimizer. // Setting this does not override/replace the default passes. It is appended at // the end of the list of passes. // [link] @@ -1918,7 +1918,7 @@ var AUTO_NATIVE_LIBRARIES = true; // Specifies the oldest major version of Firefox to target. I.e. all Firefox // versions >= MIN_FIREFOX_VERSION // are desired to work. Pass -sMIN_FIREFOX_VERSION=majorVersion to drop support -// for Firefox versions older than < majorVersion. +// for Firefox versions older than majorVersion. // Firefox 79 was released on 2020-07-28. // MAX_INT (0x7FFFFFFF, or -1) specifies that target is not supported. // Minimum supported value is 68 which was released on 2019-07-09 (see @@ -1955,7 +1955,7 @@ var MIN_SAFARI_VERSION = 150000; var MIN_CHROME_VERSION = 85; // Specifies minimum node version to target for the generated code. This is -// distinct from the minimum version required run the emscripten compiler. +// distinct from the minimum version required to run the emscripten compiler. // Version is encoded in MMmmVV, e.g. 181401 denotes Node 18.14.01. // Minimum supported value is 122209, which was released 2022-01-11 (see // feature_matrix.py). This version aligns with the Ubuntu TLS 22.04 (Jammy). @@ -2032,11 +2032,11 @@ var DISABLE_DEPRECATED_FIND_EVENT_TARGET_BEHAVIOR = true; // Certain browser DOM API operations, such as requesting fullscreen mode // transition or pointer lock require that the request originates from within -// an user initiated event, such as mouse click or keyboard press. Refactoring +// a user initiated event, such as mouse click or keyboard press. Refactoring // an application to follow this kind of program structure can be difficult, so // HTML5_SUPPORT_DEFERRING_USER_SENSITIVE_REQUESTS allows transparent emulation // of this by deferring such requests until a suitable event callback is -// generated. Set this to 0 to disable support for deferring to on save code +// generated. Set this to 0 to disable support for deferring to save code // size if your application does not need support for deferred calls. // [link] var HTML5_SUPPORT_DEFERRING_USER_SENSITIVE_REQUESTS = true; @@ -2067,9 +2067,9 @@ var ASAN_SHADOW_SIZE = -1; // [link] var SOURCE_MAP_PREFIXES = []; -// Default to c++ mode even when run as ``emcc`` rather then ``emc++``. -// When this is disabled ``em++`` is required linking C++ programs. Disabling -// this will match the behaviour of gcc/g++ and clang/clang++. +// Default to c++ mode even when run as ``emcc`` rather than ``emc++``. +// When this is disabled ``em++`` is required when linking C++ programs. +// Disabling this will match the behaviour of gcc/g++ and clang/clang++. // [link] var DEFAULT_TO_CXX = true; @@ -2101,7 +2101,7 @@ var SEPARATE_DWARF_URL = ''; // - Lowering sign-extension operation when targeting older browsers. var ERROR_ON_WASM_CHANGES_AFTER_LINK = false; -// Abort on unhandled excptions that occur when calling exported WebAssembly +// Abort on unhandled exceptions that occur when calling exported WebAssembly // functions. This makes the program behave more like a native program where the // OS would terminate the process and no further code can be executed when an // unhandled exception (e.g. out-of-bounds memory access) happens. @@ -2114,7 +2114,7 @@ var ERROR_ON_WASM_CHANGES_AFTER_LINK = false; // want Emscripten to handle unhandled exceptions nicely at the cost of a few // bytes extra. // Exceptions that occur within the ``main`` function are already handled via an -// alternative mechanimsm. +// alternative mechanism. // [link] var ABORT_ON_WASM_EXCEPTIONS = false; @@ -2142,13 +2142,13 @@ var PURE_WASI = false; // [link] var IMPORTED_MEMORY = false; -// Generate code to loading split wasm modules. +// Generate code to load split wasm modules. // This option will automatically generate two wasm files as output, one // with the ``.orig`` suffix and one without. The default file (without -// the suffix) when run will generate instrumentation data can later be +// the suffix) when run will generate instrumentation data that can later be // fed into wasm-split (the binaryen tool). -// As well as this the generated JS code will contains helper functions -// to loading split modules. +// As well as this the generated JS code will contain helper functions +// to load split modules. // [link] // [experimental] var SPLIT_MODULE = false; @@ -2256,6 +2256,6 @@ var CROSS_ORIGIN = false; // This setting changes the behaviour of the ``-shared`` flag. The default // setting of ``true`` means the ``-shared`` flag actually produces a normal // object file (i.e. ``ld -r``). Setting this to false will cause ``-shared`` -// to behave like :ref:`SIDE_MODULE` and produce and dynamically linked +// to behave like :ref:`SIDE_MODULE` and produce a dynamically linked // library. var FAKE_DYLIBS = true; diff --git a/tools/maint/update_settings_docs.py b/tools/maint/update_settings_docs.py index b17f8d2e90bb1..8140e6fd8ba6f 100755 --- a/tools/maint/update_settings_docs.py +++ b/tools/maint/update_settings_docs.py @@ -67,8 +67,8 @@ =================== The following settings have been proposed for removal from emscripten. These settings -still function but may be removed in a future version. If your project is using of -the these settings please open a bug (or reply to one of the existing bugs). +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). ''' @@ -80,7 +80,7 @@ =============== The following settings no longer have any effect but are still accepted by emscripten -for backwards compatbility with older versions: +for backwards compatibility with older versions: ''' From ba012a7f97cf60a1c59e557feadf077028908894 Mon Sep 17 00:00:00 2001 From: Heejin Ahn Date: Wed, 31 Dec 2025 08:15:54 +0000 Subject: [PATCH 2/2] more --- docs/emcc.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/emcc.txt b/docs/emcc.txt index 87be29ca9b79d..919849122bd7f 100644 --- a/docs/emcc.txt +++ b/docs/emcc.txt @@ -221,7 +221,7 @@ Options that are modified or new in *emcc* are listed below: [link] Make the output suitable for profiling. This means including function names in the wasm and JS output, and preserving whitespace in the JS output. It does not affect optimizations (to ensure that - performance profiles reflect production builds). Currenly this is + performance profiles reflect production builds). Currently this is the same as "-g2". "--profiling-funcs" @@ -255,10 +255,11 @@ Options that are modified or new in *emcc* are listed below: "[name].wasm.js.symbols" (with ASM.js symbols) "--emit-minification-map " - [link] In cases where emscripten performs import/export minificiton - this option can be used to output a file that maps minified names - back to their original names. The format of this file is single - line per import/export of the form ":". + [link] In cases where emscripten performs import/export + minification this option can be used to output a file that maps + minified names back to their original names. The format of this + file is single line per import/export of the form + ":". "-flto" [compile+link] Enables link-time optimizations (LTO).