Interacting with code

Interacting with Compiled Code

(If you are looking for how compiled code interacts with the browser environment, see Emscripten Browser Environment.)

There are various ways to connect and interact between JS and compiled C++ in JS. An overview appears in the second half of these slides: http://kripken.github.io/mloc_emscripten_talk/qcon.html

Calling Compiled Functions From Normal JavaScript

It's easy to call compiled code from normal JavaScript. For example, run this command in the Emscripten home directory:

./emcc tests/hello_function.cpp -o function.html -s EXPORTED_FUNCTIONS="['_int_sqrt']"

Open the page in a web browser. Nothing will happen because you compiled a function, and there is no main so nothing will be run by default. But, open a JavaScript environment (Control-Shift-K on Firefox, Control-Shift-J on Chrome), then type (as three separate commands, pressing Enter after each one):

int_sqrt = Module.cwrap('int_sqrt', 'number', ['number'])
int_sqrt(12)
int_sqrt(28)

You should get the results 3, 5, which are the correct output: The compiled function does a square root operation, but acts on integers. Open tests/hello_function.cpp to see the source code that you just called here.

cwrap which was used in this example will wrap a compiled C function, returning a JavaScript function you can call normally. cwrap gets as its first parameter the name of the function to be wrapped, then the return type of the function, then an array of parameter types (the array can be omitted if there are no parameters). The types are native JavaScript types, "number" (for a C integer, float, or general pointer) or "string" (for a C char* that represents a string).

There is also ccall, which is like cwrap but receives another parameter with the parameters to pass to the function, and calls the function. cwrap is useful to wrap a function once and call it several times, while ccall is useful for a single call to a function.

Some things to keep in mind with ccall and cwrap:

• In the example above, we compiled a C function. That's easier than C++ because C++ functions are name-mangled.
• By default Emscripten does dead code elimination to minimize code size. See the FAQ entry on "Functions in my C/C++ source code vanish when I compile to JavaScript..?"
• In -O2 and above, closure compiler is run, which minifies function names - which means you won't be able to find your compiled functions. To prevent that, run emcc with -s EXPORTED_FUNCTIONS="['_main','_other_function']". Exported functions will retain their names even through closure compiler. Note that you need _ at the beginning of the functions, and note also that you need to use Module.ccall and not ccall by itself, since closure will minify the function name, leaving only the Module object where we export names.

Accessing Memory

You can access memory using getValue(ptr, type) and setValue(ptr, value, type). The first argument is a pointer, a number representing a memory address. type must be an LLVM IR type, one of i8,i16,i32,i64,float,double or a pointer type like i8* (or just *). Note that the types here are not as in ccall and cwrap - this is a lower-level operation, and we do need to care what specific integer etc. type is being used.

You can also access memory 'directly' by manipulating the arrays that represent memory. This is not recommended unless you are sure you know what you are doing, and need the additional speed over getValue/setValue. A case where you might need this is if you want to import a large amount of data from JS to be processed by compiled code, then you might do something like this:

var buf = Module._malloc(SIZE);
Module.HEAPU8.set(myTypedArray, buf);
Module.ccall('my_function', 'number', ['number'], [buf]);
Module._free(buf);

That allocates a buffer, copies in some data, then calls a C function to process the data, and finally frees the buffer.

Calling JavaScript From C/C++

The most direct way is to just use emscripten_run_script, which basically runs some JS code from C/C++ using eval. So emscripten_run_script("alert('hi')"); will show an alert with 'hi'. This is not very fast though.

More generally, our entire libc, SDL etc. implementations are exactly JS code that is called from C/C++ using a C API. You can add your own libraries as well. For example, if you have some C code like this

extern void my_js();

int main() {
  my_js();
  return 1;
}

Note: when using C++ you should encapsulate extern void my_js(); in extern "C" {} block:

extern "C" {
  extern void my_js();
}

then you can implement my_js in JS by simply adding

   my_js: function() {
     alert('hi');
   },

to library.js. How this works is that when there is an external symbol, the compiler looks in the JS libraries and pulls in the relevant symbols. See the library*.js files for more details and examples.

You can use the emcc option --js-library to add a file with such code, instead of placing it inside library.js. This lets you be more modular. See test_js_libraries in tests/runner.py for a complete working example, including the syntax you should use inside the JS library file.

Other Methods

You can directly interact in various other ways with the compiled code:

• Functions in the original source become JS functions, so you can call them directly if you do type translations yourself - this will be faster than using ccall or cwrap, but a little more complex. Note that you need to prefix function calls with '_' (all compiled functions have that added).
  • The types of the parameters you pass to functions need to make sense. Integers and floating point values can be passed as is. Aside from those, there are pointers, which are simply integers in the generated code.
  • Strings in JavaScript must be converted to pointers for compiled code, the relevant functions are Pointer_stringify which given a pointer returns a JavaScript string, and the other direction can be accomplished by allocate(intArrayFromString(someString), 'i8', ALLOC_STACK) which will convert a JavaScript string someString to a pointer. Note that conversion to a pointer allocates memory (that's the call to allocate there).
• There are various other convenience functions, see preamble.js (that file will be included with the generated code).
• The bindings generator can generate convenient JS classes from C++ headers. See the bindings test in the test runner, test_scriptaclass_2, for a concrete example of the process (test_scriptaclass has a more detailed testcase). Also see the ammo.js and box2d.js projects (the main consumers of that tool). Note however that the bindings generator is considered experimental, and has various inherent limitations that stem from objects in C++ not being the same as in JS: In general, it is recommended to interact with your code through a C API and ccall/cwrap.
• For filesystem-related manners, see the Filesystem Guide.

Affecting Execution

You can affect how code runs by creating an object called Module before the compiled script. Certain properties on Module can then have various effects:

• arguments: The commandline arguments (if the compiled code checks argc, argv, it will be seeing arguments)
• print: Called when something is printed to standard output.
• preInit: A function (or array of functions) to call before global initializers run, but after basic initialization of the JS runtime (so you can do FS.* stuff, but no C++ initializers were called yet).
• preRun: A function (or 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 FileSystem API (since that needs the FileSystem API to be defined, but also needs to be done before the program starts to run; if you need to affect global initializers, though, you should use preInit).
• noInitialRun: If set to true, main() will not be called. The program will still call global initializers, set up memory initialization, and so forth. You can then call main() yourself later.
• noExitRuntime: If set to true, the runtime is not shut down after run is called. Shutting down the runtime calls shutdown callbacks, for example atexit calls. If you want to be able to continue to use the code after run finishes, it is safer to set this.

For example,

var Module = {
  'print': function(text) { alert(text) }
};

This will cause all printouts from the program to be calls to alert.

Important: If you run closure compiler on your code (which is done by default in -O2 and above), you will need quotation marks around the properties of Module as in the example above (and you need to run closure on the compiled code together with the declaration of Module).

Setting Module

When generating just JavaScript, no Module object is created. So you can use emcc's --pre-js to add some JS code that defines the Module object with the stuff you need.

When generating HTML, a Module object is created for you and filled with some defaults for printing, etc. (compile a little hello world example to see, or view src/shell.html). The simplest thing is to use --pre-js to add some JS code that adds properties to that existing Module object.

Environment variables

Sometimes, the code you are compiling will want to access environment variables (for instance, in C, by calling the getenv() function). Just as with the filesystem, emscripten generated javascript cannot access the computer's environment variables so a virtualised environment is provided. The javascript object ENV contains these virtualised environment variables, and by modifying it you can pass variables to your compiled code. Care must be taken to ensure that the ENV variable has been initialised by emscripten before it is modified - using Module.preRun is a convenient way to do this. For example to set an environment variable MY_FILE_ROOT to be "/usr/lib/test/" you could add

Module.preRun.push(function() {ENV.MY_FILE_ROOT = "/usr/lib/test"})

to your setup code, as described above.