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

.. note:: ``Module`` is also used to provide access to all Emscripten API functions (for example :js:func:`ccall`) in a way that avoids issues with function name minification at higher optimisation levels. These functions are documented as part of their own APIs.

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

	::

		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/kripken/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

	::

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


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

The following ``Module`` attributes affect code execution. 


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

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


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

	.. note:: If code needs to affect global initializers, it should instead be run using :js:attr:`preInit`.


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

.. js:attribute:: Module.filePackagePrefixURL

	This is the "prefix" URL for a preloaded data file that is hosted separately from its JavaScript and HTML files (it includes the full path up to, but not including, the data file). See :ref:`packaging-files-data-file-location` for more information.
	
.. js:attribute:: Module.locateFile

	If set, this method will be called when the runtime needs to load either a file generated by the file packager (this is a generalization of ``Module.filePackagePrefixURL``), or the ``.mem`` memory init file. In both cases the function receives the URL, and should return the actual URL. This lets you host file packages or the ``.mem`` file on a different location than the current directory (which is the default expectation), for example if you want to host them on a CDN.

.. js:attribute:: Module.logReadFiles

	If set, :js:attr:`Module.printErr` will log when any file is read.

	
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.
	
