Add verification step for metadata tags in settings.js. NFC (#25677)

At this point we could also consider removing these tags but I think it
makes reading the settings.js directly more useful to keep them for now.

This new code just checks that the tags are always in sync with the
lists and maps in `settings.py`.

Author: sbc100

site/source/docs/tools_reference/settings_reference.rst

@@ -1056,7 +1056,7 @@ This option is mutually exclusive with EXCEPTION_CATCHING_ALLOWED.
 This option only applies to Emscripten (JavaScript-based) exception handling
 and does not control the native Wasm exception handling.
 
-[compile+link] - affects user code at compile and system libraries at link
+.. note:: Applicable during both linking and compilation
 
 Default value: 1
 
@@ -1073,7 +1073,7 @@ This option is mutually exclusive with DISABLE_EXCEPTION_CATCHING.
 This option only applies to Emscripten (JavaScript-based) exception handling
 and does not control the native Wasm exception handling.
 
-[compile+link] - affects user code at compile and system libraries at link
+.. note:: Applicable during both linking and compilation
 
 Default value: []
 
@@ -1092,12 +1092,12 @@ time, then you will get errors on undefined symbols, as the exception
 throwing code is not linked in. If so you should either unset the option (if
 you do want exceptions) or fix the compilation of the source files so that
 indeed no exceptions are used).
-TODO(sbc): Move to settings_internal (current blocked due to use in test
-code).
 
 This option only applies to Emscripten (JavaScript-based) exception handling
 and does not control the native Wasm exception handling.
 
+.. note:: Applicable during both linking and compilation
+
 Default value: false
 
 .. _export_exception_handling_helpers:
@@ -1628,6 +1628,8 @@ Automatically set for SIDE_MODULE or MAIN_MODULE.
 
 .. note:: Applicable during both linking and compilation
 
+.. note:: This setting is deprecated
+
 Default value: false
 
 .. _main_module:
@@ -1687,6 +1689,8 @@ PROXY_TO_WORKER
 If set to 1, we build the project into a js file that will run in a worker,
 and generate an html file that proxies input and output to/from it.
 
+.. note:: This setting is deprecated
+
 Default value: false
 
 .. _proxy_to_worker_filename:
@@ -1698,6 +1702,8 @@ If set, the script file name the main thread loads.  Useful if your project
 doesn't run the main emscripten- generated script immediately but does some
 setup before
 
+.. note:: This setting is deprecated
+
 Default value: ''
 
 .. _proxy_to_pthread:
@@ -1739,6 +1745,10 @@ to set this explicitly. Note that MAIN_MODULE and SIDE_MODULE mode 2 do
 *not* set this, so that we still do normal DCE on them, and in that case
 you must keep relevant things alive yourself using exporting.
 
+.. note:: Applicable during both linking and compilation
+
+.. note:: This setting is deprecated
+
 Default value: false
 
 .. _strict:
@@ -2442,6 +2452,8 @@ SDL2_IMAGE_FORMATS
 Formats to support in SDL2_image. Valid values: bmp, gif, lbm, pcx, png, pnm,
 tga, xcf, xpm, xv
 
+.. note:: Applicable during both linking and compilation
+
 Default value: []
 
 .. _sdl2_mixer_formats:
@@ -2451,6 +2463,8 @@ SDL2_MIXER_FORMATS
 
 Formats to support in SDL2_mixer. Valid values: ogg, mp3, mod, mid
 
+.. note:: Applicable during both linking and compilation
+
 Default value: ["ogg"]
 
 .. _use_sqlite3:
@@ -2471,7 +2485,8 @@ SHARED_MEMORY
 =============
 
 If 1, target compiling a shared Wasm Memory.
-[compile+link] - affects user code at compile and system libraries at link.
+
+.. note:: Applicable during both linking and compilation
 
 Default value: false
 
@@ -2483,7 +2498,8 @@ WASM_WORKERS
 Enables support for Wasm Workers.  Wasm Workers enable applications
 to create threads using a lightweight web-specific API that builds on top
 of Wasm SharedArrayBuffer + Atomics API.
-[compile+link] - affects user code at compile and system libraries at link.
+
+.. note:: Applicable during both linking and compilation
 
 Default value: 0
 
@@ -3004,9 +3020,10 @@ little bit of code size and performance when catching exceptions.
 - 1: Default setjmp/longjmp/handling, depending on the mode of exceptions.
   'wasm' if '-fwasm-exceptions' is used, 'emscripten' otherwise.
 
-[compile+link] - at compile time this enables the transformations needed for
-longjmp support at codegen time, while at link it allows linking in the
-library support.
+At compile time this enables the transformations needed for longjmp support
+at codegen time, while at link it allows linking in the library support.
+
+.. note:: Applicable during both linking and compilation
 
 Default value: true
 
@@ -3200,6 +3217,8 @@ fed into wasm-split (the binaryen tool).
 As well as this the generated JS code will contains help functions
 to loading split modules.
 
+.. note:: This is an experimental setting
+
 Default value: false
 
 .. _autoload_dylibs:
@@ -3306,6 +3325,8 @@ This is only currently implemented in the pre-release/nightly version of node,
 and not yet supported by browsers.
 Requires EXPORT_ES6
 
+.. note:: This is an experimental setting
+
 Default value: false
 
 .. _wasm_esm_integration:
@@ -3316,6 +3337,8 @@ WASM_ESM_INTEGRATION
 Experimental support for wasm ESM integration.
 Requires EXPORT_ES6 and MODULARIZE=instance
 
+.. note:: This is an experimental setting
+
 Default value: false
 
 .. _js_base64_api:
@@ -3354,6 +3377,8 @@ Experimental support for WebAssembly js-types proposal.
 It's currently only available under a flag in certain browsers,
 so we disable it by default to save on code size.
 
+.. note:: This is an experimental setting
+
 Default value: false
 
 .. _cross_origin:

src/settings.js

@@ -709,7 +709,7 @@ var LZ4 = false;
 // This option only applies to Emscripten (JavaScript-based) exception handling
 // and does not control the native Wasm exception handling.
 //
-// [compile+link] - affects user code at compile and system libraries at link
+// [compile+link]
 var DISABLE_EXCEPTION_CATCHING = 1;
 
 // Enables catching exception but only in the listed functions.  This
@@ -720,7 +720,7 @@ var DISABLE_EXCEPTION_CATCHING = 1;
 // This option only applies to Emscripten (JavaScript-based) exception handling
 // and does not control the native Wasm exception handling.
 //
-// [compile+link] - affects user code at compile and system libraries at link
+// [compile+link]
 var EXCEPTION_CATCHING_ALLOWED = [];
 
 // Internal: Tracks whether Emscripten should link in exception throwing (C++
@@ -733,13 +733,11 @@ var EXCEPTION_CATCHING_ALLOWED = [];
 // throwing code is not linked in. If so you should either unset the option (if
 // you do want exceptions) or fix the compilation of the source files so that
 // indeed no exceptions are used).
-// TODO(sbc): Move to settings_internal (current blocked due to use in test
-// code).
 //
 // This option only applies to Emscripten (JavaScript-based) exception handling
 // and does not control the native Wasm exception handling.
 //
-// [link]
+// [compile+link]
 var DISABLE_EXCEPTION_THROWING = false;
 
 // Make the exception message printing function, 'getExceptionMessage' available
@@ -1118,6 +1116,7 @@ var INCLUDE_FULL_LIBRARY = false;
 // globals and function pointers are all offset (by gb and fp, respectively)
 // Automatically set for SIDE_MODULE or MAIN_MODULE.
 // [compile+link]
+// [deprecated]
 var RELOCATABLE = false;
 
 // A main module is a file compiled in a way that allows us to link it to
@@ -1148,12 +1147,14 @@ var BUILD_AS_WORKER = false;
 // If set to 1, we build the project into a js file that will run in a worker,
 // and generate an html file that proxies input and output to/from it.
 // [link]
+// [deprecated]
 var PROXY_TO_WORKER = false;
 
 // If set, the script file name the main thread loads.  Useful if your project
 // doesn't run the main emscripten- generated script immediately but does some
 // setup before
 // [link]
+// [deprecated]
 var PROXY_TO_WORKER_FILENAME = '';
 
 // If set to 1, compiles in a small stub main() in between the real main() which
@@ -1184,7 +1185,8 @@ var PROXY_TO_PTHREAD = false;
 // to set this explicitly. Note that MAIN_MODULE and SIDE_MODULE mode 2 do
 // *not* set this, so that we still do normal DCE on them, and in that case
 // you must keep relevant things alive yourself using exporting.
-// [link]
+// [compile+link]
+// [deprecated]
 var LINKABLE = false;
 
 // Emscripten 'strict' build mode: Drop supporting any deprecated build options.
@@ -1607,11 +1609,11 @@ var USE_MODPLUG = false;
 
 // Formats to support in SDL2_image. Valid values: bmp, gif, lbm, pcx, png, pnm,
 // tga, xcf, xpm, xv
-// [link]
+// [compile+link]
 var SDL2_IMAGE_FORMATS = [];
 
 // Formats to support in SDL2_mixer. Valid values: ogg, mp3, mod, mid
-// [link]
+// [compile+link]
 var SDL2_MIXER_FORMATS = ["ogg"];
 
 // 1 = use sqlite3 from emscripten-ports
@@ -1620,13 +1622,13 @@ var SDL2_MIXER_FORMATS = ["ogg"];
 var USE_SQLITE3 = false;
 
 // If 1, target compiling a shared Wasm Memory.
-// [compile+link] - affects user code at compile and system libraries at link.
+// [compile+link]
 var SHARED_MEMORY = false;
 
 // Enables support for Wasm Workers.  Wasm Workers enable applications
 // to create threads using a lightweight web-specific API that builds on top
 // of Wasm SharedArrayBuffer + Atomics API.
-// [compile+link] - affects user code at compile and system libraries at link.
+// [compile+link]
 var WASM_WORKERS = 0;
 
 // If true, enables targeting Wasm Web Audio AudioWorklets. Check out the
@@ -1978,9 +1980,9 @@ var MINIMAL_RUNTIME_STREAMING_WASM_INSTANTIATION = false;
 // - 1: Default setjmp/longjmp/handling, depending on the mode of exceptions.
 //   'wasm' if '-fwasm-exceptions' is used, 'emscripten' otherwise.
 //
-// [compile+link] - at compile time this enables the transformations needed for
-// longjmp support at codegen time, while at link it allows linking in the
-// library support.
+// At compile time this enables the transformations needed for longjmp support
+// at codegen time, while at link it allows linking in the library support.
+// [compile+link]
 var SUPPORT_LONGJMP = true;
 
 // If set to 1, disables old deprecated HTML5 API event target lookup behavior.
@@ -2107,6 +2109,7 @@ var IMPORTED_MEMORY = false;
 // As well as this the generated JS code will contains help functions
 // to loading split modules.
 // [link]
+// [experimental]
 var SPLIT_MODULE = false;
 
 // For MAIN_MODULE builds, automatically load any dynamic library dependencies
@@ -2169,11 +2172,13 @@ var SIGNATURE_CONVERSIONS = [];
 // and not yet supported by browsers.
 // Requires EXPORT_ES6
 // [link]
+// [experimental]
 var SOURCE_PHASE_IMPORTS = false;
 
 // Experimental support for wasm ESM integration.
 // Requires EXPORT_ES6 and MODULARIZE=instance
 // [link]
+// [experimental]
 var WASM_ESM_INTEGRATION = false;
 
 // Enable use of the JS arraybuffer-base64 API:
@@ -2194,6 +2199,7 @@ var GROWABLE_ARRAYBUFFERS = false;
 // Experimental support for WebAssembly js-types proposal.
 // It's currently only available under a flag in certain browsers,
 // so we disable it by default to save on code size.
+// [experimental]
 var WASM_JS_TYPES = false;
 
 // If the emscripten-generated program is hosted on separate origin then

tools/maint/update_settings_docs.py

@@ -25,8 +25,13 @@
 
 sys.path.insert(0, root_dir)
 
-from tools.settings import DEPRECATED_SETTINGS, LEGACY_SETTINGS
-from tools.utils import path_from_root, read_file, safe_ensure_dirs
+from tools.settings import (
+  COMPILE_TIME_SETTINGS,
+  DEPRECATED_SETTINGS,
+  EXPERIMENTAL_SETTINGS,
+  LEGACY_SETTINGS,
+)
+from tools.utils import exit_with_error, path_from_root, read_file, safe_ensure_dirs
 
 header = '''\
 .. _settings-reference:
@@ -82,6 +87,16 @@
 output_file = path_from_root('site/source/docs/tools_reference/settings_reference.rst')
 
 
+def check_tags(setting_name, tags):
+  if setting_name in COMPILE_TIME_SETTINGS and 'compile' not in tags and 'compile+link' not in tags:
+    print(tags)
+    exit_with_error(f'setting {setting_name} in COMPILE_TIME_SETTINGS but missing [compile] tag')
+  if setting_name in DEPRECATED_SETTINGS and 'deprecated' not in tags:
+    exit_with_error(f'setting {setting_name} in DEPRECATED_SETTINGS but missing [deprecated] tag')
+  if setting_name in EXPERIMENTAL_SETTINGS and 'experimental' not in tags:
+    exit_with_error(f'setting {setting_name} in EXPERIMENTAL_SETTINGS but missing [experimental] tag')
+
+
 def write_setting(f, setting_name, setting_default, comment, tags):
   # Convert markdown backticks to rst double backticks
   f.write('\n.. _' + setting_name.lower() + ':\n')
@@ -127,6 +142,7 @@ def write_file(f):
       # Split it and strip the final ';'.
       _, setting_name, _, setting_default = line.strip(';').split(None, 3)
       comment = '\n'.join(current_comment).strip()
+      check_tags(setting_name, current_tags)
       write_setting(f, setting_name, setting_default, comment, current_tags)
       current_comment = []
       current_tags = []