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 Module.print attribute.

Note

Module is also used to provide access to all Emscripten API functions (for example 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.

Creating the Module object

Use emcc’s pre-js option 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 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). 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.

Module.print

Called when something is printed to standard output (stdout)

Module.printErr

Called when something is printed to standard error (stderr)

Module.arguments

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

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 File System operations.

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 File System 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 preInit.

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.

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.

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 Changing the data file location for more information.

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.

Module.logReadFiles

If set, Module.printErr will log when any file is read.

Other methods

Module.destroy(obj)

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

Arguments:
  • obj – The JavaScript-wrapped C++ object to be destroyed.
Module.onCustomMessage()

When compiled with PROXY_TO_WORKER = 1 (see settings.js), this callback (which should be implemented on both the client and worker’s Module object) allows sending custom messages and data between the web worker and the main thread (using the postCustomMessage function defined in proxyClient.js and proxyWorker.js).

Overriding execution environment

The generated program is able to detect its execution environment by checking the presence of some typical objects of the environment itself (such as window for browsers).

However, sometimes it may be needed to override the detected environment: a typical use case would be module bundlers (like webpack): they are executed by nodejs but the final output is for browser.

In order to do that, you can dictate your preferred execution environment by setting the Module.ENVIRONMENT variable to one of those allowed values:

WEB

WORKER

NODE

SHELL

In that case, Module will honor your preference and skip auto detection.