Treat ENVIRONMENT setting as a list. NFC (#24545)

This should not be a user-visible change I hope since the existing
bespoke format of comma-separated-list will parse just fine as a real
list too.

Author: sbc100

site/source/docs/tools_reference/settings_reference.rst

@@ -1011,9 +1011,9 @@ ones we identify at runtime using ``ENVIRONMENT_IS_*``. Specifically:
   at compile time, there is no runtime behavior change.
 
 Note that by default we do not include the 'shell' environment since direct
-usage of d8, js, jsc is extremely rare.
+usage of d8, spidermonkey and jsc is extremely rare.
 
-Default value: 'web,webview,worker,node'
+Default value: ['web', 'webview', 'worker', 'node']
 
 .. _lz4:
 

src/settings.js

@@ -662,9 +662,9 @@ var LEGACY_VM_SUPPORT = false;
 //   at compile time, there is no runtime behavior change.
 //
 // Note that by default we do not include the 'shell' environment since direct
-// usage of d8, js, jsc is extremely rare.
+// usage of d8, spidermonkey and jsc is extremely rare.
 // [link]
-var ENVIRONMENT = 'web,webview,worker,node';
+var ENVIRONMENT = ['web', 'webview', 'worker', 'node'];
 
 // 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.

src/shell.js

@@ -59,16 +59,16 @@ if (ENVIRONMENT_IS_AUDIO_WORKLET) ENVIRONMENT_IS_WASM_WORKER = true;
 // Determine the runtime environment we are in. You can customize this by
 // setting the ENVIRONMENT setting at compile time (see settings.js).
 
-#if ENVIRONMENT && !ENVIRONMENT.includes(',')
-var ENVIRONMENT_IS_WEB = {{{ ENVIRONMENT === 'web' }}};
+#if ENVIRONMENT.length == 1
+var ENVIRONMENT_IS_WEB = {{{ ENVIRONMENT[0] === 'web' }}};
 #if PTHREADS && ENVIRONMENT_MAY_BE_NODE
 // node+pthreads always supports workers; detect which we are at runtime
 var ENVIRONMENT_IS_WORKER = typeof WorkerGlobalScope != 'undefined';
 #else
-var ENVIRONMENT_IS_WORKER = {{{ ENVIRONMENT === 'worker' }}};
+var ENVIRONMENT_IS_WORKER = {{{ ENVIRONMENT[0] === 'worker' }}};
 #endif
-var ENVIRONMENT_IS_NODE = {{{ ENVIRONMENT === 'node' }}};
-var ENVIRONMENT_IS_SHELL = {{{ ENVIRONMENT === 'shell' }}};
+var ENVIRONMENT_IS_NODE = {{{ ENVIRONMENT[0] === 'node' }}};
+var ENVIRONMENT_IS_SHELL = {{{ ENVIRONMENT[0] === 'shell' }}};
 #else // ENVIRONMENT
 // Attempt to auto-detect the environment
 var ENVIRONMENT_IS_WEB = typeof window == 'object';
@@ -183,7 +183,7 @@ var readAsync, readBinary;
 
 #if ENVIRONMENT_MAY_BE_NODE
 if (ENVIRONMENT_IS_NODE) {
-#if ENVIRONMENT && ASSERTIONS
+#if ENVIRONMENT.length && ASSERTIONS
   const isNode = {{{ nodeDetectionCode() }}};
   if (!isNode) throw new Error('not compiled for this 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
@@ -265,7 +265,7 @@ if (ENVIRONMENT_IS_NODE) {
 #if ENVIRONMENT_MAY_BE_SHELL || ASSERTIONS
 if (ENVIRONMENT_IS_SHELL) {
 
-#if ENVIRONMENT && ASSERTIONS
+#if ENVIRONMENT.length && ASSERTIONS
   const isNode = {{{ nodeDetectionCode() }}};
   if (isNode || typeof window == 'object' || typeof WorkerGlobalScope != 'undefined') throw new Error('not compiled for this 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
@@ -345,7 +345,7 @@ if (ENVIRONMENT_IS_WEB || ENVIRONMENT_IS_WORKER) {
     // infer anything from them.
   }
 
-#if ENVIRONMENT && ASSERTIONS
+#if ENVIRONMENT.length && ASSERTIONS
   if (!(typeof window == 'object' || typeof WorkerGlobalScope != 'undefined')) throw new Error('not compiled for this 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
 

src/shell_minimal.js

@@ -45,8 +45,8 @@ var ENVIRONMENT_IS_SHELL = typeof read == 'function';
 #if ASSERTIONS || PTHREADS
 #if !ENVIRONMENT_MAY_BE_NODE && !ENVIRONMENT_MAY_BE_SHELL
 var ENVIRONMENT_IS_WEB = true
-#elif ENVIRONMENT && !ENVIRONMENT.includes(',')
-var ENVIRONMENT_IS_WEB = {{{ ENVIRONMENT === 'web' }}};
+#elif ENVIRONMENT.length == 1
+var ENVIRONMENT_IS_WEB = {{{ ENVIRONMENT[0] === 'web' }}};
 #elif ENVIRONMENT_MAY_BE_SHELL && ENVIRONMENT_MAY_BE_NODE
 var ENVIRONMENT_IS_WEB = !ENVIRONMENT_IS_NODE && !ENVIRONMENT_IS_SHELL;
 #elif ENVIRONMENT_MAY_BE_SHELL

tools/link.py

@@ -166,18 +166,17 @@ def setup_environment_settings():
   # Note: we need to actually modify ENVIRONMENTS variable here before the parsing,
   # because some JS code reads it back so modifying parsed info alone is not sufficient.
   if settings.SHARED_MEMORY and settings.ENVIRONMENT:
-    settings.ENVIRONMENT += ',worker'
+    settings.ENVIRONMENT.append('worker')
 
   # Environment setting based on user input
-  environments = settings.ENVIRONMENT.split(',')
-  if any(x for x in environments if x not in VALID_ENVIRONMENTS):
+  if any(x for x in settings.ENVIRONMENT if x not in VALID_ENVIRONMENTS):
     exit_with_error(f'Invalid environment specified in "ENVIRONMENT": {settings.ENVIRONMENT}. Should be one of: {",".join(VALID_ENVIRONMENTS)}')
 
-  settings.ENVIRONMENT_MAY_BE_WEB = not settings.ENVIRONMENT or 'web' in environments
-  settings.ENVIRONMENT_MAY_BE_WEBVIEW = not settings.ENVIRONMENT or 'webview' in environments
-  settings.ENVIRONMENT_MAY_BE_NODE = not settings.ENVIRONMENT or 'node' in environments
-  settings.ENVIRONMENT_MAY_BE_SHELL = not settings.ENVIRONMENT or 'shell' in environments
-  settings.ENVIRONMENT_MAY_BE_WORKER = not settings.ENVIRONMENT or 'worker' in environments
+  settings.ENVIRONMENT_MAY_BE_WEB = not settings.ENVIRONMENT or 'web' in settings.ENVIRONMENT
+  settings.ENVIRONMENT_MAY_BE_WEBVIEW = not settings.ENVIRONMENT or 'webview' in settings.ENVIRONMENT
+  settings.ENVIRONMENT_MAY_BE_NODE = not settings.ENVIRONMENT or 'node' in settings.ENVIRONMENT
+  settings.ENVIRONMENT_MAY_BE_SHELL = not settings.ENVIRONMENT or 'shell' in settings.ENVIRONMENT
+  settings.ENVIRONMENT_MAY_BE_WORKER = not settings.ENVIRONMENT or 'worker' in settings.ENVIRONMENT
 
   if not settings.ENVIRONMENT_MAY_BE_NODE:
     if 'MIN_NODE_VERSION' in user_settings:
@@ -2008,7 +2007,7 @@ def run_embind_gen(options, wasm_target, js_syms, extra_settings):
   settings.PRE_JS_FILES = []
   settings.POST_JS_FILES = []
   # Force node since that is where the tool runs.
-  settings.ENVIRONMENT = 'node'
+  settings.ENVIRONMENT = ['node']
   settings.MINIMAL_RUNTIME = 0
   # Required function to trigger TS generation.
   settings.DEFAULT_LIBRARY_FUNCS_TO_INCLUDE += ['$callRuntimeCallbacks']

tools/maint/update_settings_docs.py

@@ -101,7 +101,7 @@ def write_file(f):
       # Format:
       #   var NAME = DEFAULT;
       # Split it and strip the final ';'.
-      _, setting_name, _, setting_default = line.strip(';').split()
+      _, setting_name, _, setting_default = line.strip(';').split(None, 3)
       comment = '\n'.join(current_comment).strip()
       write_setting(f, setting_name, setting_default, comment, current_tags)
       current_comment = []