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 Emscripten API functions (for example ccall()) in a safe way. Any function or runtime method exported (using EXPORTED_FUNCTIONS for compiled functions, or EXTRA_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 relevant FAQ entry.

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

If you run the Closure Compiler on your code (which is optional, and can be done by --closure1), 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 existingModule object, for example

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.

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

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 (like the wasm binary when running wasm), 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).

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.

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 URL, and should return the actual URL. This lets you host file packages or the .mem file etc. on a different location than the current directory (which is the default expectation), for example if you want to host them on a CDN. Note that locateFile is sort of a generalization of Module.filePackagePrefixURL.

If building with -s GL_PREINITIALIZED_CONTEXT=1 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.

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.

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

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 tests/manual_wasm_instantiate.html and the test browser.test_manual_wasm_instantiate for an example of how this construct works in action.

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 downloade file data. See file tests/manual_download_data.html and the test browser.test_preload_file_with_manual_data_download for an example.