site/source/docs/api_reference/module.rst

.. _module:

=============
Module object
=============

``Module`` is a global JavaScript object with attributes that
Emscripten-generated code calls at various points in its execution.

Developers can provide an implementation of ``Module`` to control the execution
of code. For example, to define how notification messages from Emscripten are
displayed, developers implement the :js:attr:`Module.print` attribute.

When an Emscripten application starts up it looks at the values on the ``Module``
object and applies them. Note that changing the values *after* startup will not
work in general; in a build with ``ASSERTIONS`` enabled you will get an error
in that case.

.. note:: ``Module`` is also used to provide access to Emscripten API functions
   (for example :js:func:`ccall`) in a safe way. Any function or runtime method
   exported (using ``EXPORTED_FUNCTIONS`` for compiled functions, or
   ``EXPORTED_RUNTIME_METHODS`` for runtime methods like ``ccall``) will be
   accessible on the ``Module`` object, without minification changing the name,
   and the optimizer will make sure to keep the function present (and not remove
   it as unused). See the :ref:`relevant FAQ entry<faq-export-stuff>`.

.. contents:: Table of Contents
  :local:
  :depth: 1


.. _module-creating:

Creating the Module object
==========================

Use emcc's :ref:`pre-js option<emcc-pre-js>` to add JavaScript code that defines
(or extends) the ``Module`` object with the behaviour you need.

When generating only JavaScript (as opposed to HTML), no ``Module`` object is
created by default, and the behaviour is entirely defined by the developer. For
example, creating a ``Module`` object with the following code will cause all
notifications from the program to be calls to ``alert()``.

  .. code-block:: javascript

    var Module = {
      'print': function(text) { alert('stdout: ' + text) },
      'printErr': function(text) { alert('stderr: ' + text) }
    };

.. important:: If you run the :term:`Closure Compiler` on your code (which is
   optional, and can be done by ``--closure 1``), you will need quotation marks
   around the properties of ``Module`` as in the example above. In addition, you
   need to run closure on the compiled code together with the declaration of
   ``Module`` — this is done automatically for a ``--pre-js`` file.

When generating HTML, Emscripten creates a ``Module`` object with default
methods (see `src/shell.html
<https://github.com/emscripten-core/emscripten/blob/1.29.12/src/shell.html#L1220>`_).
In this case you should again use ``--pre-js``, but this time you add properties
to the *existing* ``Module`` object, for example:

  .. code-block:: javascript

    Module['print'] = function(text) { alert('stdout: ' + text) };

Note that once the Module object is received by the main JavaScript file, it
will look for ``Module['print']`` and so forth at that time, and use them
accordingly. Changing their values later may not be noticed.

Compilation settings
====================

The ``INCOMING_MODULE_JS_API`` compiler setting controls which ``Module``
attributes are supported in the emitted JS. This list contains commonly-used
things by default.

Setting this to the smallest possible list for your application will save JS
code size. For example, if you use no ``Module`` attributes, you can build
with ``-sINCOMING_MODULE_JS_API=[]``. Or, if you use just a few, you can list
them out, like this: ``-sINCOMING_MODULE_JS_API=print,printErr``.

Affecting execution
===================

The following ``Module`` attributes affect code execution. Set them to customize
behavior.


.. js:attribute:: Module.arguments

  The commandline arguments. The value of ``arguments`` contains the values
  returned if compiled code checks ``argc`` and ``argv``.

.. js:attribute:: Module.buffer

  Allows you to provide your own ``ArrayBuffer`` or ``SharedArrayBuffer`` to use
  as the memory.

  .. note:: This is only supported if ``-sWASM=0``. See ``Module.wasmMemory``
     for WebAssembly support.

.. js:attribute:: Module.wasmMemory

  Allows you to provide your own ``WebAssembly.Memory`` to use as the memory.
  The properties used to initialize the memory should match the compiler
  options.

  For example, if you set ``INITIAL_MEMORY`` to 8MB without memory growth, then
  the ``wasmMemory`` you provide (if any) should have both the ``'initial'`` and
  ``'maximum'`` set to 128 (due to WASM page sizes being 64KB).

.. js:attribute:: Module.locateFile

  If set, this method will be called when the runtime needs to load a file, such
  as a ``.wasm`` WebAssembly file, ``.mem`` memory init file, or a file
  generated by the file packager. The function receives the relative path to the
  file as configured in build process and a ``prefix`` (path to the main
  JavaScript file's directory), and should return the actual URL. This lets you
  host file packages or the ``.mem`` file etc. on a different location than the
  directory of the JavaScript file (which is the default expectation), for
  example if you want to host them on a CDN.

  .. note:: ``prefix`` might be an empty string, if ``locateFile`` is called
     before we load the main JavaScript. For example, that can happen if a file
     package or a memory initializer file are loaded beforehand (perhaps from the
     HTML, before it loads the main JavaScript).

  .. note:: Several ``Module.*PrefixURL`` options have been deprecated in favor
            of ``locateFile``, which includes ``memoryInitializerPrefixURL``,
            ``pthreadMainPrefixURL``, ``cdInitializerPrefixURL``,
            ``filePackagePrefixURL``. To update your code, for example if you
            used ``Module.memoryInitializerPrefixURL`` equal to
            ``"https://mycdn.com/memory-init-dir/"``, then you can replace that
            with something like:

            .. code-block:: javascript

              Module['locateFile'] = function(path, prefix) {
                // if it's a mem init file, use a custom dir
                if (path.endsWith(".mem")) return "https://mycdn.com/memory-init-dir/" + path;
                // otherwise, use the default, the prefix (JS file's dir) + the path
                return prefix + path;
              }

.. js:attribute:: Module.logReadFiles

  If set, stderr will log when any file is read.

.. js:attribute:: Module.printWithColors

  Controls whether Emscripten runtime libraries try to print with colors.
  Currently, this only affects sanitizers.

  If unset, colors will be enabled if printing to a terminal with ``node``.

  If set to ``true``, colors will always be used if possible. If set to
  ``false``, colors will never be used.

.. 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 (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

  If set, this function is called when the runtime is fully initialized, that
  is, when compiled code is safe to run, which is after any asynchronous startup
  operations have completed (such as asynchronous WebAssembly compilation, file
  preloading, etc.). (An alternative to waiting for this to be called is to wait
  for ``main()`` to be called.)

.. js:attribute:: Module.noExitRuntime

  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

  If ``noInitialRun`` is set to ``true``, ``main()`` will not be automatically
  called (you can do so yourself later). The program will still call global
  initializers, set up memory initialization, and so forth.

.. js:attribute:: Module.preInit

  A function (or array of functions) that must be called before global
  initializers run, but after basic initialization of the JavaScript runtime.
  This is typically used for :ref:`File System operations <Filesystem-API>`.

.. js:attribute:: Module.preinitializedWebGLContext

  If building with ``-sGL_PREINITIALIZED_CONTEXT`` set, you can set
  ``Module.preinitializedWebGLContext`` to a precreated instance of a WebGL
  context, which will be used later when initializing WebGL in C/C++ side.
  Precreating the GL context is useful if doing GL side loading (shader
  compilation, texture loading etc.) parallel to other page startup actions,
  and/or for detecting WebGL feature support, such as GL version or compressed
  texture support up front on a page before or in parallel to loading up any
  compiled code.

.. js:attribute:: Module.preRun

  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)

.. js:attribute:: Module.printErr

  Called when something is printed to standard error (stderr)

.. js:attribute:: Module.mainScriptUrlOrBlob

  Allows pthread workers to independently load up the main file (e.g. main.js)
  from a URL or blob. New pthread workers need to load the main JavaScript file
  (e.g. main.js). By default, they load the content of main.js from the URL of
  main.js. However, if the main.js file was loaded from a Blob, it is not
  possible to access the URL of the main.js. Also, when main.js is bundled by a
  Node.JS module bundler (e.g. webpack), the URL of that script can be wrong,
  the URL after webpack bundler will result in wrong URL like main.chunk.js

Other methods
=============

.. js:function:: Module.destroy(obj)

  This method should be called to destroy C++ objects created in JavaScript
  using :ref:`WebIDL bindings <WebIDL-Binder>`. If this method is not called, an
  object may be garbage collected, but its destructor will not be called.

  :param obj: The JavaScript-wrapped C++ object to be destroyed.

.. js:function:: Module.getPreloadedPackage

  If you want to manually manage the download of .data file packages for custom
  caching, progress reporting and error handling behavior, you can implement the
  ``Module.getPreloadedPackage = function(remotePackageName, remotePackageSize)``
  callback to provide the contents of the data files back to the file loading
  scripts. The return value of this callback should be an Arraybuffer with the
  contents of the downloaded file data. See file
  ``test/manual_download_data.html`` and the test
  ``browser.test_preload_file_with_manual_data_download`` for an example.

.. js:function:: Module.instantiateWasm

  When targeting WebAssembly, Module.instantiateWasm is an optional
  user-implemented callback function that the Emscripten runtime calls to
  perform the WebAssembly instantiation action. The callback function will be
  called with two parameters, ``imports`` and ``successCallback``. ``imports``
  is a JS object which contains all the function imports that need to be passed
  to the WebAssembly Module when instantiating, and once instantiated, this
  callback function should call ``successCallback()`` with the generated
  WebAssembly Instance object.

  The instantiation can be performed either synchronously or asynchronously. The
  return value of this function should contain the ``exports`` object of the
  instantiated WebAssembly Module, or an empty dictionary object ``{}`` if the
  instantiation is performed asynchronously, or ``false`` if instantiation
  failed.

  Overriding the WebAssembly instantiation procedure via this function is useful
  when you have other custom asynchronous startup actions or downloads that can
  be performed in parallel to WebAssembly compilation. Implementing this
  callback allows performing all of these in parallel. See the file
  ``test/manual_wasm_instantiate.html`` and the test
  ``browser.test_manual_wasm_instantiate`` for an example of how this construct
  works in action.

  .. note:: Source maps are currently not supported if overriding
     WebAssembly instantiation with Module.instantiateWasm. Providing
     Module.instantiateWasm when source maps are enabled can prevent
     WebAssembly instantiation from finishing.

.. js:function:: Module.fetchSettings

  Override the default settings object used when fetching the Wasm module from
  the network.  This attribute is expected to be a string and it defaults to ``{
  credentials: 'same-origin' }``.