From 8ad67d21a90d454d20c2b5a7d62626af5d6c3b7f Mon Sep 17 00:00:00 2001 From: Sam Clegg Date: Sat, 22 Aug 2026 16:17:06 -0700 Subject: [PATCH] [docs] Update descriptions for undefined symbol settings. NFC Update and clarify the doc comments in `src/settings.js` for `ERROR_ON_UNDEFINED_SYMBOLS` and `WARN_ON_UNDEFINED_SYMBOLS`, and regenerate `site/source/docs/tools_reference/settings_reference.rst`. --- .../tools_reference/settings_reference.rst | 28 ++++++++++--------- src/settings.js | 28 ++++++++++--------- 2 files changed, 30 insertions(+), 26 deletions(-) diff --git a/site/source/docs/tools_reference/settings_reference.rst b/site/source/docs/tools_reference/settings_reference.rst index aaccc9b8823b2..2168ea8ea4f8c 100644 --- a/site/source/docs/tools_reference/settings_reference.rst +++ b/site/source/docs/tools_reference/settings_reference.rst @@ -1784,14 +1784,9 @@ Default value: false WARN_ON_UNDEFINED_SYMBOLS ========================= -If set to 1, we will warn on any undefined symbols that are not resolved by -the ``library_*.js`` files. Note that it is common in large projects to not -implement everything, when you know what is not going to actually be called -(and don't want to mess with the existing buildsystem), and functions might -be implemented later on, say in --pre-js, so you may want to build with -s -WARN_ON_UNDEFINED_SYMBOLS=0 to disable the warnings if they annoy you. See -also ERROR_ON_UNDEFINED_SYMBOLS. Any undefined symbols that are listed in -EXPORTED_FUNCTIONS will also be reported. +Like ``ERROR_ON_UNDEFINED_SYMBOLS`` but can be used to also disable warnings. +Disabling this setting is not advised as it can hide genuine errors in your +build. Default value: true @@ -1800,11 +1795,18 @@ Default value: true ERROR_ON_UNDEFINED_SYMBOLS ========================== -If set to 1, we will give a link-time error on any undefined symbols (see -WARN_ON_UNDEFINED_SYMBOLS). To allow undefined symbols at link time set this -to 0, in which case if an undefined function is called a runtime error will -occur. Any undefined symbols that are listed in EXPORTED_FUNCTIONS will also -be reported. +Disable this setting to allow undefined functions at link time. Instead of +of a link error you will see a runtime error if an undefined function is ever +called. +This setting allows projects to link with undefined function symbols, +which can be safe if you know those functions will never be called (and don't +want to mess with the existing build system), or if they are implemented +outside of the compiler (e.g. in ``--pre-js``). +Disabling this setting will turn the errors to warnings. If you don't +want warnings about undefined symbols you can also disable +``WARN_ON_UNDEFINED_SYMBOLS``. +Disabling this setting is not advised as it can hide genuine errors in your +build. Default value: true diff --git a/src/settings.js b/src/settings.js index 8101b4662c3d8..85f6530d99a1a 100644 --- a/src/settings.js +++ b/src/settings.js @@ -1220,22 +1220,24 @@ var IGNORE_MISSING_MAIN = true; // [link] var STRICT_JS = false; -// If set to 1, we will warn on any undefined symbols that are not resolved by -// the ``library_*.js`` files. Note that it is common in large projects to not -// implement everything, when you know what is not going to actually be called -// (and don't want to mess with the existing buildsystem), and functions might -// be implemented later on, say in --pre-js, so you may want to build with -s -// WARN_ON_UNDEFINED_SYMBOLS=0 to disable the warnings if they annoy you. See -// also ERROR_ON_UNDEFINED_SYMBOLS. Any undefined symbols that are listed in -// EXPORTED_FUNCTIONS will also be reported. +// Like ``ERROR_ON_UNDEFINED_SYMBOLS`` but can be used to also disable warnings. +// Disabling this setting is not advised as it can hide genuine errors in your +// build. // [link] var WARN_ON_UNDEFINED_SYMBOLS = true; -// If set to 1, we will give a link-time error on any undefined symbols (see -// WARN_ON_UNDEFINED_SYMBOLS). To allow undefined symbols at link time set this -// to 0, in which case if an undefined function is called a runtime error will -// occur. Any undefined symbols that are listed in EXPORTED_FUNCTIONS will also -// be reported. +// Disable this setting to allow undefined functions at link time. Instead of +// of a link error you will see a runtime error if an undefined function is ever +// called. +// This setting allows projects to link with undefined function symbols, +// which can be safe if you know those functions will never be called (and don't +// want to mess with the existing build system), or if they are implemented +// outside of the compiler (e.g. in ``--pre-js``). +// Disabling this setting will turn the errors to warnings. If you don't +// want warnings about undefined symbols you can also disable +// ``WARN_ON_UNDEFINED_SYMBOLS``. +// Disabling this setting is not advised as it can hide genuine errors in your +// build. // [link] var ERROR_ON_UNDEFINED_SYMBOLS = true;