diff --git a/site/source/docs/tools_reference/settings_reference.rst b/site/source/docs/tools_reference/settings_reference.rst index 2f3f8044c2ca1..85f053734d054 100644 --- a/site/source/docs/tools_reference/settings_reference.rst +++ b/site/source/docs/tools_reference/settings_reference.rst @@ -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]) diff --git a/src/settings.js b/src/settings.js index 8707f5001edec..7624d4a25fdc1 100644 --- a/src/settings.js +++ b/src/settings.js @@ -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'], -]; diff --git a/tools/maint/update_settings_docs.py b/tools/maint/update_settings_docs.py index 238a5914cdb78..16bb3ac02b8b3 100755 --- a/tools/maint/update_settings_docs.py +++ b/tools/maint/update_settings_docs.py @@ -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: @@ -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') @@ -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 = [] @@ -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: diff --git a/tools/settings.py b/tools/settings.py index 15919f1247ab0..f01b75fd7d63c 100644 --- a/tools/settings.py +++ b/tools/settings.py @@ -162,6 +162,98 @@ ('CROSS_ORIGIN', 'NO_PTHREADS', None), ] +# 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). +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'], +] + user_settings: Dict[str, str] = {} @@ -213,7 +305,7 @@ def read_js_settings(filename, attrs): # Special handling for LEGACY_SETTINGS. See src/setting.js for more # details - for legacy in self.attrs['LEGACY_SETTINGS']: + for legacy in LEGACY_SETTINGS: if len(legacy) == 2: name, new_name = legacy self.legacy_settings[name] = (None, 'setting renamed to ' + new_name)