Add ENVIRONMENT to specify which environment the code will run in (#6565)

By default we still emit code that can run in node, web, shell, etc., but with the option the user can fix only one to be emitted.

This also sets ENVIRONMENT to "web" if the user specifies an HTML output (emcc [..] -o code.html). In that case the indication is clear that the code should only run on the web. This is technically a breaking change though, as people may have tried to run the .js file outside of the web, and that may have worked in some cases. To prevent confusion, when ASSERTIONS are on we show an error if we hit a problem, and also in debug logging we mention doing HTML output setting the environment that way. The benefit to doing this is that it gets all the benefits of web-only emitting in a natural way for the main use case.

For more details on the benefits, see #6542 #1140, but basically

*    When targeting only web, we don't emit node.js support code which includes require() operations that confuse bundlers.
*    We emit less unneeded code.

Author: kripken

src/compiler.js

@@ -197,6 +197,19 @@ load('jsifier.js');
 globalEval(processMacros(preprocess(read('runtime.js'), 'runtime.js')));
 Runtime.QUANTUM_SIZE = QUANTUM_SIZE;
 
+// State computations
+
+ENVIRONMENT_MAY_BE_WEB    = !ENVIRONMENT || ENVIRONMENT === 'web';
+ENVIRONMENT_MAY_BE_WORKER = !ENVIRONMENT || ENVIRONMENT === 'worker';
+ENVIRONMENT_MAY_BE_NODE   = !ENVIRONMENT || ENVIRONMENT === 'node';
+ENVIRONMENT_MAY_BE_SHELL  = !ENVIRONMENT || ENVIRONMENT === 'shell';
+
+ENVIRONMENT_MAY_BE_WEB_OR_WORKER = ENVIRONMENT_MAY_BE_WEB || ENVIRONMENT_MAY_BE_WORKER;
+
+if (ENVIRONMENT && !(ENVIRONMENT_MAY_BE_WEB || ENVIRONMENT_MAY_BE_WORKER || ENVIRONMENT_MAY_BE_NODE || ENVIRONMENT_MAY_BE_SHELL)) {
+  throw 'Invalid environment specified in "ENVIRONMENT": ' + ENVIRONMENT + '. Should be one of: web, worker, node, shell.';
+}
+
 //===============================
 // Main
 //===============================

src/library_fs.js

@@ -1295,8 +1295,10 @@ mergeInto(LibraryManager.library, {
         var randomBuffer = new Uint8Array(1);
         random_device = function() { crypto.getRandomValues(randomBuffer); return randomBuffer[0]; };
       } else if (ENVIRONMENT_IS_NODE) {
+#if ENVIRONMENT_MAY_BE_NODE
         // for nodejs
         random_device = function() { return require('crypto')['randomBytes'](1)[0]; };
+#endif // ENVIRONMENT_MAY_BE_NODE
       } else {
         // default for ES5 platforms
         random_device = function() { return (Math.random()*256)|0; };

src/library_sockfs.js

@@ -206,9 +206,13 @@ mergeInto(LibraryManager.library, {
             // If node we use the ws library.
             var WebSocketConstructor;
             if (ENVIRONMENT_IS_NODE) {
+#if ENVIRONMENT_MAY_BE_NODE
               WebSocketConstructor = require('ws');
+#endif ENVIRONMENT_MAY_BE_NODE
             } else if (ENVIRONMENT_IS_WEB) {
+#if ENVIRONMENT_MAY_BE_WEB
               WebSocketConstructor = window['WebSocket'];
+#endif // ENVIRONMENT_MAY_BE_WEB
             } else {
               WebSocketConstructor = WebSocket;
             }
@@ -482,6 +486,7 @@ mergeInto(LibraryManager.library, {
         if (!ENVIRONMENT_IS_NODE) {
           throw new FS.ErrnoError(ERRNO_CODES.EOPNOTSUPP);
         }
+#if ENVIRONMENT_MAY_BE_NODE
         if (sock.server) {
            throw new FS.ErrnoError(ERRNO_CODES.EINVAL);  // already listening
         }
@@ -535,6 +540,7 @@ mergeInto(LibraryManager.library, {
           Module['websocket'].emit('error', [sock.stream.fd, sock.error, 'EHOSTUNREACH: Host is unreachable']);
           // don't throw
         });
+#endif // ENVIRONMENT_MAY_BE_NODE
       },
       accept: function(listensock) {
         if (!listensock.server) {

src/library_uuid.js

@@ -30,11 +30,13 @@ mergeInto(LibraryManager.library, {
     var uuid = null;
 
     if (ENVIRONMENT_IS_NODE) {
+#if ENVIRONMENT_MAY_BE_NODE
       // If Node.js try to use crypto.randomBytes
       try {
         var rb = require('crypto')['randomBytes'];
         uuid = rb(16);
       } catch(e) {}
+#endif // ENVIRONMENT_MAY_BE_NODE
     } else if (ENVIRONMENT_IS_WEB &&
                typeof(window.crypto) !== 'undefined' &&
                typeof(window.crypto.getRandomValues) !== 'undefined') {

src/settings.js

@@ -318,6 +318,17 @@ var LEGACY_VM_SUPPORT = 0; // Enable this to get support for non-modern browsers
                            //  * Add polyfilling for Math.clz32, Math.trunc, Math.imul, Math.fround.
                            //  * Disable WebAssembly.
 
+var ENVIRONMENT = ''; // By default, emscripten output will run on the web, in a web worker,
+                      // in node.js, or in a JS shell like d8, js, or jsc. You can set this option to
+                      // specify that the output should only run in one particular environment, which
+                      // must be one of
+                      //    'web'    - the normal web environment.
+                      //    'worker' - a web worker environment.
+                      //    'node'   - Node.js.
+                      //    'shell'  - a JS shell like d8, js, or jsc.
+                      // There is also a 'pthread' environment, see shell.js, but it cannot be specified
+                      // manually yet TODO
+
 var LZ4 = 0; // Enable this to support lz4-compressed file packages. They are stored compressed in memory, and
              // decompressed on the fly, avoiding storing the entire decompressed data in memory at once.
              // If you run the file packager separately, you still need to build the main program with this flag,
@@ -924,3 +935,11 @@ var MEM_INIT_IN_WASM = 0; // for internal use only
 
 var SUPPORT_BASE64_EMBEDDING = 0; // If set to 1, src/base64Utils.js will be included in the bundle.
                                   // This is set internally when needed (SINGLE_FILE)
+
+// For internal use only, the possible environments the code may run in.
+var ENVIRONMENT_MAY_BE_WEB = 1;
+var ENVIRONMENT_MAY_BE_WORKER = 1;
+var ENVIRONMENT_MAY_BE_NODE = 1;
+var ENVIRONMENT_MAY_BE_SHELL = 1;
+var ENVIRONMENT_MAY_BE_WEB_OR_WORKER = 1;
+

src/shell.js

@@ -46,6 +46,14 @@ Module['quit'] = function(status, toThrow) {
 Module['preRun'] = [];
 Module['postRun'] = [];
 
+#if ENVIRONMENT
+
+var ENVIRONMENT_IS_WEB = {{{ ENVIRONMENT === 'web' }}};
+var ENVIRONMENT_IS_WORKER = {{{ ENVIRONMENT === 'worker' }}};
+var ENVIRONMENT_IS_NODE = {{{ ENVIRONMENT === 'node' }}};
+var ENVIRONMENT_IS_SHELL = {{{ ENVIRONMENT === 'shell' }}};
+
+#else // ENVIRONMENT
 // The environment setup code below is customized to use Module.
 // *** Environment setup code ***
 var ENVIRONMENT_IS_WEB = false;
@@ -76,6 +84,7 @@ if (Module['ENVIRONMENT']) {
   ENVIRONMENT_IS_NODE = typeof process === 'object' && typeof require === 'function' && !ENVIRONMENT_IS_WEB && !ENVIRONMENT_IS_WORKER;
   ENVIRONMENT_IS_SHELL = !ENVIRONMENT_IS_WEB && !ENVIRONMENT_IS_NODE && !ENVIRONMENT_IS_WORKER;
 }
+#endif // ENVIRONMENT
 
 #if USE_PTHREADS
 var ENVIRONMENT_IS_PTHREAD;
@@ -85,6 +94,7 @@ if (!ENVIRONMENT_IS_PTHREAD) PthreadWorkerInit = {};
 var currentScriptUrl = (typeof document !== 'undefined' && document.currentScript) ? document.currentScript.src : undefined;
 #endif
 
+#if ENVIRONMENT_MAY_BE_NODE
 if (ENVIRONMENT_IS_NODE) {
   // Expose functionality in the same simple way that the shells work
   // Note that we pollute the global namespace here, otherwise we break in node
@@ -148,8 +158,10 @@ if (ENVIRONMENT_IS_NODE) {
   });
 
   Module['inspect'] = function () { return '[Emscripten Module object]'; };
-}
-else if (ENVIRONMENT_IS_SHELL) {
+} else
+#endif // ENVIRONMENT_MAY_BE_NODE
+#if ENVIRONMENT_MAY_BE_SHELL
+if (ENVIRONMENT_IS_SHELL) {
   if (typeof read != 'undefined') {
     Module['read'] = function shell_read(f) {
 #if SUPPORT_BASE64_EMBEDDING
@@ -189,8 +201,10 @@ else if (ENVIRONMENT_IS_SHELL) {
       quit(status);
     }
   }
-}
-else if (ENVIRONMENT_IS_WEB || ENVIRONMENT_IS_WORKER) {
+} else
+#endif // ENVIRONMENT_MAY_BE_SHELL
+#if ENVIRONMENT_MAY_BE_WEB_OR_WORKER
+if (ENVIRONMENT_IS_WEB || ENVIRONMENT_IS_WORKER) {
   Module['read'] = function shell_read(url) {
 #if SUPPORT_BASE64_EMBEDDING
     try {
@@ -255,13 +269,13 @@ else if (ENVIRONMENT_IS_WEB || ENVIRONMENT_IS_WORKER) {
   };
 
   Module['setWindowTitle'] = function(title) { document.title = title };
-}
+} else
+#endif // ENVIRONMENT_MAY_BE_WEB_OR_WORKER
+{
 #if ASSERTIONS
-else {
-  // Unreachable because SHELL is dependent on the others
-  throw new Error('unknown runtime environment');
-}
+  throw new Error('not compiled with support for this runtime environment (did you build to HTML and try to run it not on the web, or set ENVIRONMENT to something - like node - and run it someplace else - like on the web?)');
 #endif // ASSERTIONS
+}
 
 // console.log is checked first, as 'print' on the web will open a print dialogue
 // printErr is preferable to console.warn (works better in shells)

tests/test_core.py

@@ -7625,6 +7625,32 @@ def test_mallinfo(self):
   def test_wrap_malloc(self):
     self.do_run(open(path_from_root('tests', 'wrap_malloc.cpp')).read(), 'OK.')
 
+  def test_environment(self):
+    for engine in JS_ENGINES:
+      for work in (1, 0):
+        for assertions in (0, 1):
+          if work and assertions: continue # we care about assertions when we fail
+          # set us to test in just this engine
+          self.banned_js_engines = [e for e in JS_ENGINES if e != engine]
+          # tell the compiler to build with just that engine
+          if engine == NODE_JS and work:
+            Settings.ENVIRONMENT = 'node'
+          else:
+            Settings.ENVIRONMENT = 'shell'
+          Settings.ASSERTIONS = assertions
+          print(engine, work, Settings.ENVIRONMENT, assertions)
+          try:
+            self.do_run_in_out_file_test('tests', 'core', 'test_hello_world')
+          except Exception as e:
+            if not work:
+              if assertions:
+                # with assertions, an error should be shown
+                self.assertContained('not compiled with support for this runtime environment', str(e))
+            else:
+              raise
+          js = open('src.cpp.o.js').read()
+          assert ('require(' in js) == (Settings.ENVIRONMENT == 'node'), 'we should have require() calls only if node js specified'
+
 # Generate tests for everything
 def make_run(fullname, name=-1, compiler=-1, embetter=0, quantum_size=0,
     typed_arrays=0, emcc_args=None, env=None):