Skip to content

[docs] Update descriptions for undefined symbol settings. NFC #27598

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sbc100 wants to merge 1 commit into
base: main
Choose a base branch
from
+30 −26
Open

[docs] Update descriptions for undefined symbol settings. NFC #27598

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 15 additions & 13 deletions site/source/docs/tools_reference/settings_reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down
28 changes: 15 additions & 13 deletions src/settings.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
Loading