Skip to content

Move LEGACY_SETTINGS into settings.py #25596

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
wants to merge 1 commit into
base: main
Choose a base branch
from
+236 −95
Open

Move LEGACY_SETTINGS into settings.py #25596

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
104 changes: 104 additions & 0 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 @@ -3353,3 +3353,107 @@ CROSS_ORIGIN uses an inline worker to instead load the worker script
indirectly using `importScripts`

Default value: false

.. _deprecated-settings:

===================
Deprecated Settings
===================

The following settings have been proposed for removal from emscripten. These settings
still function but may be removed in a future version. If your project is using of
the these settings please open a bug (or reply to one of the existing bugs).

- ``RUNTIME_LINKED_LIBS``: you can simply list the libraries directly on the commandline now
- ``CLOSURE_WARNINGS``: use -Wclosure/-Wno-closure instead
- ``LEGALIZE_JS_FFI``: to disable JS type legalization use `-sWASM_BIGINT` or `-sSTANDALONE_WASM`
- ``ASYNCIFY_EXPORTS``: please use JSPI_EXPORTS instead
- ``LINKABLE``: under consideration for removal (https://github.com/emscripten-core/emscripten/issues/25262)
- ``RELOCATABLE``: under consideration for removal (https://github.com/emscripten-core/emscripten/issues/25262)
- ``PROXY_TO_WORKER``: under consideration for removal (See https://github.com/emscripten-core/emscripten/issues/25440)
- ``PROXY_TO_WORKER_FILENAME``: under consideration for removal (See https://github.com/emscripten-core/emscripten/issues/25440)

.. _legacy-settings:

===============
Legacy Settings
===============

The following settings no longer have any effect but are still accepted by emscripten
for backwards compatbility with older versions:

- ``BINARYEN``: Valid values: WASM
- ``TOTAL_STACK``: Valid values: STACK_SIZE
- ``BINARYEN_ASYNC_COMPILATION``: Valid values: WASM_ASYNC_COMPILATION
- ``UNALIGNED_MEMORY``: forced unaligned memory not supported in fastcomp (Valid values: [0])
- ``FORCE_ALIGNED_MEMORY``: forced aligned memory is not supported in fastcomp (Valid values: [0])
- ``PGO``: pgo no longer supported (Valid values: [0])
- ``QUANTUM_SIZE``: altering the QUANTUM_SIZE is not supported (Valid values: [4])
- ``FUNCTION_POINTER_ALIGNMENT``: Starting from Emscripten 1.37.29, no longer available (https://github.com/emscripten-core/emscripten/pull/6091) (Valid values: [2])
- ``RESERVED_FUNCTION_POINTERS``: Valid values: ALLOW_TABLE_GROWTH
- ``BUILD_AS_SHARED_LIB``: Starting from Emscripten 1.38.16, no longer available (https://github.com/emscripten-core/emscripten/pull/7433) (Valid values: [0])
- ``SAFE_SPLIT_MEMORY``: Starting from Emscripten 1.38.19, SAFE_SPLIT_MEMORY codegen is no longer available (https://github.com/emscripten-core/emscripten/pull/7465) (Valid values: [0])
- ``SPLIT_MEMORY``: Starting from Emscripten 1.38.19, SPLIT_MEMORY codegen is no longer available (https://github.com/emscripten-core/emscripten/pull/7465) (Valid values: [0])
- ``BINARYEN_METHOD``: Starting from Emscripten 1.38.23, Emscripten now always builds either to Wasm (-sWASM - default), or to JavaScript (-sWASM=0), other methods are not supported (https://github.com/emscripten-core/emscripten/pull/7836) (Valid values: ['native-wasm'])
- ``BINARYEN_TRAP_MODE``: The wasm backend does not support a trap mode (it always clamps, in effect) (Valid values: [-1])
- ``PRECISE_I64_MATH``: Starting from Emscripten 1.38.26, PRECISE_I64_MATH is always enabled (https://github.com/emscripten-core/emscripten/pull/7935) (Valid values: [1, 2])
- ``MEMFS_APPEND_TO_TYPED_ARRAYS``: Starting from Emscripten 1.38.26, MEMFS_APPEND_TO_TYPED_ARRAYS=0 is no longer supported. MEMFS no longer supports using JS arrays for file data (https://github.com/emscripten-core/emscripten/pull/7918) (Valid values: [1])
- ``ERROR_ON_MISSING_LIBRARIES``: missing libraries are always an error now (Valid values: [1])
- ``EMITTING_JS``: The new STANDALONE_WASM flag replaces this (replace EMITTING_JS=0 with STANDALONE_WASM=1) (Valid values: [1])
- ``SKIP_STACK_IN_SMALL``: SKIP_STACK_IN_SMALL is no longer needed as the backend can optimize it directly (Valid values: [0, 1])
- ``SAFE_STACK``: Replace SAFE_STACK=1 with STACK_OVERFLOW_CHECK=2 (Valid values: [0])
- ``MEMORY_GROWTH_STEP``: Valid values: MEMORY_GROWTH_LINEAR_STEP
- ``ELIMINATE_DUPLICATE_FUNCTIONS``: Duplicate function elimination for wasm is handled automatically by binaryen (Valid values: [0, 1])
- ``ELIMINATE_DUPLICATE_FUNCTIONS_DUMP_EQUIVALENT_FUNCTIONS``: Duplicate function elimination for wasm is handled automatically by binaryen (Valid values: [0])
- ``ELIMINATE_DUPLICATE_FUNCTIONS_PASSES``: Duplicate function elimination for wasm is handled automatically by binaryen (Valid values: [5])
- ``WASM_OBJECT_FILES``: For LTO, use -flto or -fto=thin instead; to disable LTO, just do not pass WASM_OBJECT_FILES=1 as 1 is the default anyhow (Valid values: [0, 1])
- ``TOTAL_MEMORY``: Valid values: INITIAL_MEMORY
- ``WASM_MEM_MAX``: Valid values: MAXIMUM_MEMORY
- ``BINARYEN_MEM_MAX``: Valid values: MAXIMUM_MEMORY
- ``BINARYEN_PASSES``: Use BINARYEN_EXTRA_PASSES to add additional passes (Valid values: [''])
- ``SWAPPABLE_ASM_MODULE``: Fully swappable asm modules are no longer supported (Valid values: [0])
- ``ASM_JS``: asm.js output is not supported anymore (Valid values: [1])
- ``FINALIZE_ASM_JS``: asm.js output is not supported anymore (Valid values: [0, 1])
- ``ASYNCIFY_WHITELIST``: Valid values: ASYNCIFY_ONLY
- ``ASYNCIFY_BLACKLIST``: Valid values: ASYNCIFY_REMOVE
- ``EXCEPTION_CATCHING_WHITELIST``: Valid values: EXCEPTION_CATCHING_ALLOWED
- ``SEPARATE_ASM``: Separate asm.js only made sense for fastcomp with asm.js output (Valid values: [0])
- ``SEPARATE_ASM_MODULE_NAME``: Separate asm.js only made sense for fastcomp with asm.js output (Valid values: [''])
- ``FAST_UNROLLED_MEMCPY_AND_MEMSET``: The wasm backend implements memcpy/memset in C (Valid values: [0, 1])
- ``DOUBLE_MODE``: The wasm backend always implements doubles normally (Valid values: [0, 1])
- ``PRECISE_F32``: The wasm backend always implements floats normally (Valid values: [0, 1, 2])
- ``ALIASING_FUNCTION_POINTERS``: The wasm backend always uses a single index space for function pointers, in a single Table (Valid values: [0, 1])
- ``AGGRESSIVE_VARIABLE_ELIMINATION``: Wasm ignores asm.js-specific optimization flags (Valid values: [0, 1])
- ``SIMPLIFY_IFS``: Wasm ignores asm.js-specific optimization flags (Valid values: [1])
- ``DEAD_FUNCTIONS``: The wasm backend does not support dead function removal (Valid values: [[]])
- ``WASM_BACKEND``: Only the wasm backend is now supported (note that setting it as -s has never been allowed anyhow) (Valid values: [-1])
- ``EXPORT_BINDINGS``: No longer needed (Valid values: [0, 1])
- ``RUNNING_JS_OPTS``: Fastcomp cared about running JS which could alter asm.js validation, but not upstream (Valid values: [0])
- ``EXPORT_FUNCTION_TABLES``: No longer needed (Valid values: [0])
- ``BINARYEN_SCRIPTS``: No longer needed (Valid values: [''])
- ``WARN_UNALIGNED``: No longer needed (Valid values: [0, 1])
- ``ASM_PRIMITIVE_VARS``: No longer needed (Valid values: [[]])
- ``WORKAROUND_IOS_9_RIGHT_SHIFT_BUG``: Wasm2JS does not support iPhone 4s, iPad 2, iPad 3, iPad Mini 1, Pod Touch 5 (devices with end-of-life at iOS 9.3.5) and older (Valid values: [0])
- ``RUNTIME_FUNCS_TO_IMPORT``: No longer needed (Valid values: [[]])
- ``LIBRARY_DEPS_TO_AUTOEXPORT``: No longer needed (Valid values: [[]])
- ``EMIT_EMSCRIPTEN_METADATA``: No longer supported (Valid values: [0])
- ``SHELL_FILE``: No longer supported (Valid values: [''])
- ``LLD_REPORT_UNDEFINED``: Disabling is no longer supported (Valid values: [1])
- ``MEM_INIT_METHOD``: No longer supported (Valid values: [0])
- ``USE_PTHREADS``: No longer needed. Use -pthread instead (Valid values: [0, 1])
- ``USES_DYNAMIC_ALLOC``: No longer supported. Use -sMALLOC=none (Valid values: [1])
- ``REVERSE_DEPS``: No longer needed (Valid values: ['auto', 'all', 'none'])
- ``RUNTIME_LOGGING``: Valid values: RUNTIME_DEBUG
- ``MIN_EDGE_VERSION``: No longer supported (Valid values: [2147483647])
- ``MIN_IE_VERSION``: No longer supported (Valid values: [2147483647])
- ``WORKAROUND_OLD_WEBGL_UNIFORM_UPLOAD_IGNORED_OFFSET_BUG``: No longer supported (Valid values: [0])
- ``AUTO_ARCHIVE_INDEXES``: No longer needed (Valid values: [0, 1])
- ``USE_ES6_IMPORT_META``: Disabling is no longer supported (Valid values: [1])
- ``EXTRA_EXPORTED_RUNTIME_METHODS``: No longer supported, use EXPORTED_RUNTIME_METHODS (Valid values: [[]])
- ``SUPPORT_ERRNO``: No longer supported (Valid values: [0])
- ``DEMANGLE_SUPPORT``: No longer supported (Valid values: [0])
- ``MAYBE_WASM2JS``: No longer supported (use -sWASM=2) (Valid values: [0])
- ``HEADLESS``: No longer supported, use headless browsers or Node.js with JSDOM (Valid values: [0])
- ``USE_OFFSET_COVERTER``: No longer supported, not needed with modern v8 versions (Valid values: [0])
- ``ASYNCIFY_LAZY_LOAD_CODE``: No longer supported (Valid values: [0])
- ``USE_WEBGPU``: No longer supported; replaced by --use-port=emdawnwebgpu, which implements a newer (but incompatible) version of webgpu.h - see tools/ports/emdawnwebgpu.py (Valid values: [0])
92 changes: 0 additions & 92 deletions src/settings.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2192,95 +2192,3 @@ var WASM_JS_TYPES = false;
// CROSS_ORIGIN uses an inline worker to instead load the worker script
// indirectly using `importScripts`
var CROSS_ORIGIN = false;

// For renamed settings the format is:
// [OLD_NAME, NEW_NAME]
// For removed settings (which now effectively have a fixed value and can no
// longer be changed) the format is:
// [OPTION_NAME, POSSIBLE_VALUES, ERROR_EXPLANATION], where POSSIBLE_VALUES is
// an array of values that will still be silently accepted by the compiler.
// First element in the list is the canonical/fixed value going forward.
// This allows existing build systems to keep specifying one of the supported
// settings, for backwards compatibility.
// When a setting has been removed, and we want to error on all values of it,
// we can set POSSIBLE_VALUES to an impossible value (like "disallowed" for a
// numeric setting, or -1 for a string setting).
var LEGACY_SETTINGS = [
['BINARYEN', 'WASM'],
['TOTAL_STACK', 'STACK_SIZE'],
['BINARYEN_ASYNC_COMPILATION', 'WASM_ASYNC_COMPILATION'],
['UNALIGNED_MEMORY', [0], 'forced unaligned memory not supported in fastcomp'],
['FORCE_ALIGNED_MEMORY', [0], 'forced aligned memory is not supported in fastcomp'],
['PGO', [0], 'pgo no longer supported'],
['QUANTUM_SIZE', [4], 'altering the QUANTUM_SIZE is not supported'],
['FUNCTION_POINTER_ALIGNMENT', [2], 'Starting from Emscripten 1.37.29, no longer available (https://github.com/emscripten-core/emscripten/pull/6091)'],
// Reserving function pointers is not needed - allowing table growth allows any number of new functions to be added.
['RESERVED_FUNCTION_POINTERS', 'ALLOW_TABLE_GROWTH'],
['BUILD_AS_SHARED_LIB', [0], 'Starting from Emscripten 1.38.16, no longer available (https://github.com/emscripten-core/emscripten/pull/7433)'],
['SAFE_SPLIT_MEMORY', [0], 'Starting from Emscripten 1.38.19, SAFE_SPLIT_MEMORY codegen is no longer available (https://github.com/emscripten-core/emscripten/pull/7465)'],
['SPLIT_MEMORY', [0], 'Starting from Emscripten 1.38.19, SPLIT_MEMORY codegen is no longer available (https://github.com/emscripten-core/emscripten/pull/7465)'],
['BINARYEN_METHOD', ['native-wasm'], 'Starting from Emscripten 1.38.23, Emscripten now always builds either to Wasm (-sWASM - default), or to JavaScript (-sWASM=0), other methods are not supported (https://github.com/emscripten-core/emscripten/pull/7836)'],
['BINARYEN_TRAP_MODE', [-1], 'The wasm backend does not support a trap mode (it always clamps, in effect)'],
['PRECISE_I64_MATH', [1, 2], 'Starting from Emscripten 1.38.26, PRECISE_I64_MATH is always enabled (https://github.com/emscripten-core/emscripten/pull/7935)'],
['MEMFS_APPEND_TO_TYPED_ARRAYS', [1], 'Starting from Emscripten 1.38.26, MEMFS_APPEND_TO_TYPED_ARRAYS=0 is no longer supported. MEMFS no longer supports using JS arrays for file data (https://github.com/emscripten-core/emscripten/pull/7918)'],
['ERROR_ON_MISSING_LIBRARIES', [1], 'missing libraries are always an error now'],
['EMITTING_JS', [1], 'The new STANDALONE_WASM flag replaces this (replace EMITTING_JS=0 with STANDALONE_WASM=1)'],
['SKIP_STACK_IN_SMALL', [0, 1], 'SKIP_STACK_IN_SMALL is no longer needed as the backend can optimize it directly'],
['SAFE_STACK', [0], 'Replace SAFE_STACK=1 with STACK_OVERFLOW_CHECK=2'],
['MEMORY_GROWTH_STEP', 'MEMORY_GROWTH_LINEAR_STEP'],
['ELIMINATE_DUPLICATE_FUNCTIONS', [0, 1], 'Duplicate function elimination for wasm is handled automatically by binaryen'],
['ELIMINATE_DUPLICATE_FUNCTIONS_DUMP_EQUIVALENT_FUNCTIONS', [0], 'Duplicate function elimination for wasm is handled automatically by binaryen'],
['ELIMINATE_DUPLICATE_FUNCTIONS_PASSES', [5], 'Duplicate function elimination for wasm is handled automatically by binaryen'],
// WASM_OBJECT_FILES is handled in emcc.py, supporting both 0 and 1 for now.
['WASM_OBJECT_FILES', [0, 1], 'For LTO, use -flto or -fto=thin instead; to disable LTO, just do not pass WASM_OBJECT_FILES=1 as 1 is the default anyhow'],
['TOTAL_MEMORY', 'INITIAL_MEMORY'],
['WASM_MEM_MAX', 'MAXIMUM_MEMORY'],
['BINARYEN_MEM_MAX', 'MAXIMUM_MEMORY'],
['BINARYEN_PASSES', [''], 'Use BINARYEN_EXTRA_PASSES to add additional passes'],
['SWAPPABLE_ASM_MODULE', [0], 'Fully swappable asm modules are no longer supported'],
['ASM_JS', [1], 'asm.js output is not supported anymore'],
['FINALIZE_ASM_JS', [0, 1], 'asm.js output is not supported anymore'],
['ASYNCIFY_WHITELIST', 'ASYNCIFY_ONLY'],
['ASYNCIFY_BLACKLIST', 'ASYNCIFY_REMOVE'],
['EXCEPTION_CATCHING_WHITELIST', 'EXCEPTION_CATCHING_ALLOWED'],
['SEPARATE_ASM', [0], 'Separate asm.js only made sense for fastcomp with asm.js output'],
['SEPARATE_ASM_MODULE_NAME', [''], 'Separate asm.js only made sense for fastcomp with asm.js output'],
['FAST_UNROLLED_MEMCPY_AND_MEMSET', [0, 1], 'The wasm backend implements memcpy/memset in C'],
['DOUBLE_MODE', [0, 1], 'The wasm backend always implements doubles normally'],
['PRECISE_F32', [0, 1, 2], 'The wasm backend always implements floats normally'],
['ALIASING_FUNCTION_POINTERS', [0, 1], 'The wasm backend always uses a single index space for function pointers, in a single Table'],
['AGGRESSIVE_VARIABLE_ELIMINATION', [0, 1], 'Wasm ignores asm.js-specific optimization flags'],
['SIMPLIFY_IFS', [1], 'Wasm ignores asm.js-specific optimization flags'],
['DEAD_FUNCTIONS', [[]], 'The wasm backend does not support dead function removal'],
['WASM_BACKEND', [-1], 'Only the wasm backend is now supported (note that setting it as -s has never been allowed anyhow)'],
['EXPORT_BINDINGS', [0, 1], 'No longer needed'],
['RUNNING_JS_OPTS', [0], 'Fastcomp cared about running JS which could alter asm.js validation, but not upstream'],
['EXPORT_FUNCTION_TABLES', [0], 'No longer needed'],
['BINARYEN_SCRIPTS', [''], 'No longer needed'],
['WARN_UNALIGNED', [0, 1], 'No longer needed'],
['ASM_PRIMITIVE_VARS', [[]], 'No longer needed'],
['WORKAROUND_IOS_9_RIGHT_SHIFT_BUG', [0], 'Wasm2JS does not support iPhone 4s, iPad 2, iPad 3, iPad Mini 1, Pod Touch 5 (devices with end-of-life at iOS 9.3.5) and older'],
['RUNTIME_FUNCS_TO_IMPORT', [[]], 'No longer needed'],
['LIBRARY_DEPS_TO_AUTOEXPORT', [[]], 'No longer needed'],
['EMIT_EMSCRIPTEN_METADATA', [0], 'No longer supported'],
['SHELL_FILE', [''], 'No longer supported'],
['LLD_REPORT_UNDEFINED', [1], 'Disabling is no longer supported'],
['MEM_INIT_METHOD', [0], 'No longer supported'],
['USE_PTHREADS', [0, 1], 'No longer needed. Use -pthread instead'],
['USES_DYNAMIC_ALLOC', [1], 'No longer supported. Use -sMALLOC=none'],
['REVERSE_DEPS', ['auto', 'all', 'none'], 'No longer needed'],
['RUNTIME_LOGGING', 'RUNTIME_DEBUG'],
['MIN_EDGE_VERSION', [0x7FFFFFFF], 'No longer supported'],
['MIN_IE_VERSION', [0x7FFFFFFF], 'No longer supported'],
['WORKAROUND_OLD_WEBGL_UNIFORM_UPLOAD_IGNORED_OFFSET_BUG', [0], 'No longer supported'],
['AUTO_ARCHIVE_INDEXES', [0, 1], 'No longer needed'],
['USE_ES6_IMPORT_META', [1], 'Disabling is no longer supported'],
['EXTRA_EXPORTED_RUNTIME_METHODS', [[]], 'No longer supported, use EXPORTED_RUNTIME_METHODS'],
['SUPPORT_ERRNO', [0], 'No longer supported'],
['DEMANGLE_SUPPORT', [0], 'No longer supported'],
['MAYBE_WASM2JS', [0], 'No longer supported (use -sWASM=2)'],
['HEADLESS', [0], 'No longer supported, use headless browsers or Node.js with JSDOM'],
['USE_OFFSET_COVERTER', [0], 'No longer supported, not needed with modern v8 versions'],
['ASYNCIFY_LAZY_LOAD_CODE', [0], 'No longer supported'],
['USE_WEBGPU', [0], 'No longer supported; replaced by --use-port=emdawnwebgpu, which implements a newer (but incompatible) version of webgpu.h - see tools/ports/emdawnwebgpu.py'],
];
41 changes: 39 additions & 2 deletions tools/maint/update_settings_docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
sys.path.insert(0, root_dir)

from tools.utils import path_from_root, read_file, safe_ensure_dirs
from tools.settings import LEGACY_SETTINGS, DEPRECATED_SETTINGS

header = '''\
.. _settings-reference:
Expand Down Expand Up @@ -53,6 +54,31 @@
'deprecated': 'This setting is deprecated',
}

deprecated_header = '''
.. _deprecated-settings:
===================
Deprecated Settings
===================
The following settings have been proposed for removal from emscripten. These settings
still function but may be removed in a future version. If your project is using of
the these settings please open a bug (or reply to one of the existing bugs).
'''

legacy_header = '''
.. _legacy-settings:
===============
Legacy Settings
===============
The following settings no longer have any effect but are still accepted by emscripten
for backwards compatbility with older versions:
'''

output_file = path_from_root('site/source/docs/tools_reference/settings_reference.rst')


Expand Down Expand Up @@ -80,8 +106,6 @@ def write_file(f):
current_comment = []
current_tags = []
for line in read_file(path_from_root('src/settings.js')).splitlines():
if 'LEGACY_SETTINGS' in line:
break
if not line:
current_comment = []
current_tags = []
Expand All @@ -107,6 +131,19 @@ def write_file(f):
current_comment = []
current_tags = []

f.write(deprecated_header)

for name, desc in DEPRECATED_SETTINGS.items():
f.write(f' - ``{name}``: {desc}\n')

f.write(legacy_header)

for name, values, *extra_fields in LEGACY_SETTINGS:
desc = f'Valid values: {values}'
if extra_fields:
desc = f'{extra_fields[0]} ({desc})'
f.write(f' - ``{name}``: {desc}\n')


def main(args):
if '--check' in args:
Expand Down
Loading