From 6e7482aca0f4b969a78e1cf4d8d54a018bd01866 Mon Sep 17 00:00:00 2001 From: Sam Clegg Date: Thu, 14 May 2026 23:16:56 -0700 Subject: [PATCH] Add some documentation for `Module.postRun` Fixes: #26938 --- site/source/docs/api_reference/Filesystem-API.rst | 4 ++-- site/source/docs/api_reference/module.rst | 8 ++++++-- .../docs/porting/emscripten-runtime-environment.rst | 2 +- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/site/source/docs/api_reference/Filesystem-API.rst b/site/source/docs/api_reference/Filesystem-API.rst index 1c5985e5a67c7..a3e06c5fc21e2 100644 --- a/site/source/docs/api_reference/Filesystem-API.rst +++ b/site/source/docs/api_reference/Filesystem-API.rst @@ -179,7 +179,7 @@ By default: - ``stdout`` will use a ``print`` function if one such is defined, printing to the terminal in command line engines and to the browser console in browsers that have a console (again, line-buffered). - ``stderr`` will use the same output function as ``stdout``. -.. note:: All the configuration should be done before the main ``run()`` method is executed, typically by implementing :js:attr:`Module.preRun`. See :ref:`Interacting-with-code` for more information. +.. note:: All the configuration should be done before the ``main()`` is executed, typically by implementing :js:attr:`Module.preRun`. See :ref:`Interacting-with-code` for more information. .. js:function:: FS.init(input, output, error) @@ -718,7 +718,7 @@ File system API .. js:function:: FS.createPreloadedFile(parent, name, url, canRead, canWrite) - Preloads a file asynchronously, and uses preload plugins to prepare its content. You should call this in ``preRun``, ``run()`` will be delayed until all preloaded files are ready. This is how the :ref:`preload-file ` option works in *emcc* when ``--use-preload-plugins`` has been specified (if you use this method by itself, you will need to build the program with that option). + Preloads a file asynchronously, and uses preload plugins to prepare its content. You should call this in ``preRun``, ``main()`` will then be delayed until all preloaded files are ready. This is how the :ref:`preload-file ` option works in *emcc* when ``--use-preload-plugins`` has been specified (if you use this method by itself, you will need to build the program with that option). :param parent: The parent folder, either as a path (e.g. **'/usr/lib'**) or an object previously returned from a `FS.mkdir()` or `FS.createPath()` call. :type parent: string/object diff --git a/site/source/docs/api_reference/module.rst b/site/source/docs/api_reference/module.rst index 2c0124694f232..691a8cf775357 100644 --- a/site/source/docs/api_reference/module.rst +++ b/site/source/docs/api_reference/module.rst @@ -119,7 +119,7 @@ The following ``Module`` attributes affect code execution. Set them to customize .. js:attribute:: Module.noExitRuntime - If ``noExitRuntime`` is set to ``true``, the runtime is not shut down after ``run`` completes. Shutting down the runtime calls shutdown callbacks, for example ``atexit`` calls. If you want to continue using the code after ``run()`` finishes, it is necessary to set this. This is automatically set for you if you use an API command that implies that you want the runtime to not be shut down, for example ``emscripten_set_main_loop``. + If ``noExitRuntime`` is set to ``true``, the runtime is not shut down after ``main()`` completes. Shutting down the runtime calls shutdown callbacks, for example ``atexit`` calls. If you want to continue using the code after ``main()`` finishes, it is necessary to set this. This is automatically set for you if you use an API command that implies that you want the runtime to not be shut down, for example ``emscripten_set_main_loop``. .. js:attribute:: Module.noInitialRun @@ -135,10 +135,14 @@ The following ``Module`` attributes affect code execution. Set them to customize .. js:attribute:: Module.preRun - An array of functions to call right before calling ``run()``, but after defining and setting up the environment, including global initializers. This is useful, for example, to set up directories and files using the :ref:`Filesystem-API` — as this needs to happen after the FileSystem API has been loaded, but before the program starts to run. + A function (or array of functions) to call right before calling ``main()``, but after defining and setting up the environment, including global initializers. This is useful, for example, to set up directories and files using the :ref:`Filesystem-API` — as this needs to happen after the FileSystem API has been loaded, but before the program starts to run. .. note:: If code needs to affect global initializers, it should instead be run using :js:attr:`preInit`. +.. js:attribute:: Module.postRun + + A function (or array of functions) to call after the program's ``main()`` returns. + .. js:attribute:: Module.print Called when something is printed to standard output (stdout) diff --git a/site/source/docs/porting/emscripten-runtime-environment.rst b/site/source/docs/porting/emscripten-runtime-environment.rst index 6010e3ce7d203..92a6a628acd8a 100644 --- a/site/source/docs/porting/emscripten-runtime-environment.rst +++ b/site/source/docs/porting/emscripten-runtime-environment.rst @@ -122,7 +122,7 @@ You can add additional operations with :js:func:`addRunDependency`, which is a c .. note:: Generally it is not necessary to add additional operations — preloading is suitable for almost all use cases. -When all dependencies are met, Emscripten will call ``run()``, which proceeds to call your ``main()`` function. The ``main()`` function should be used to perform initialization tasks, and will often call :c:func:`emscripten_set_main_loop` (as :ref:`described above `). The main loop function will be then be called at the requested frequency. +When all dependencies are met, Emscripten will call your programs's ``main()`` function. The ``main()`` function should be used to perform initialization tasks, and will often call :c:func:`emscripten_set_main_loop` (as :ref:`described above `). The main loop function will be then be called at the requested frequency. You can affect the operation of the main loop in several ways: