Deprecate --bind in favor of just -lembind. NFC

ChangeLog.md

@@ -24,6 +24,9 @@ See docs/process.md for more on how version tagging works.
   `emcc` now uses this mode when the `--embed-file` option is used.  If you
   use `file_packager` directly it is recommended that you switch to the new mode
   by adding `--obj-output` to the command line. (#16050)
+- The `--bind` flag used to enable embind has been deprecated in favor of
+  `-lembind`.  The semantics have not changed and the old flag continues to
+  work. (#16087)
 
 3.1.2 - 20/01/2022
 ------------------

docs/emcc.txt

@@ -388,8 +388,8 @@ Options that are modified or new in *emcc* are listed below:
    script to be run.
 
 "--bind"
-   [link] Compiles the source code using the Embind bindings to
-   connect C/C++ and JavaScript.
+   [link] Links against embind library.  Deprecated: Use "-lembind"
+   instead.
 
 "--ignore-dynamic-linking"
    [link] Tells the compiler to ignore dynamic linking (the user will

emcc.py

@@ -1935,9 +1935,6 @@ def default_setting(name, new_default):
     settings.FULL_ES2 = 1
     settings.MAX_WEBGL_VERSION = max(2, settings.MAX_WEBGL_VERSION)
 
-  if settings.EMBIND:
-    state.forced_stdlibs.append('libembind')
-
   settings.REQUIRED_EXPORTS += ['stackSave', 'stackRestore', 'stackAlloc']
   if not settings.STANDALONE_WASM:
     # in standalone mode, crt1 will call the constructors from inside the wasm
@@ -2153,6 +2150,9 @@ def check_memory_setting(setting):
   if not settings.DECLARE_ASM_MODULE_EXPORTS or '-lexports.js' in [x for _, x in state.link_flags]:
     settings.MINIFY_ASMJS_EXPORT_NAMES = 0
 
+  if '-lembind' in [x for _, x in state.link_flags]:
+    settings.EMBIND = 1
+
   # Enable minification of wasm imports and exports when appropriate, if we
   # are emitting an optimized JS+wasm combo (then the JS knows how to load the minified names).
   # Things that process the JS after this operation would be done must disable this.
@@ -2918,6 +2918,11 @@ def parse_args(newargs):
       skip = False
       continue
 
+    # Support legacy '--bind' flag, by mapping to `-lembind` which now
+    # has the same effect
+    if newargs[i] == '--bind':
+      newargs[i] = '-lembind'
+
     arg = newargs[i]
     arg_value = None
 
@@ -3064,10 +3069,6 @@ def consume_arg_file():
     elif check_flag('--emit-symbol-map'):
       options.emit_symbol_map = True
       settings.EMIT_SYMBOL_MAP = 1
-    elif check_flag('--bind'):
-      settings.EMBIND = 1
-      settings.JS_LIBRARIES.append((0, os.path.join('embind', 'emval.js')))
-      settings.JS_LIBRARIES.append((0, os.path.join('embind', 'embind.js')))
     elif check_arg('--embed-file'):
       options.embed_files.append(consume_arg())
     elif check_arg('--preload-file'):

site/source/docs/porting/connecting_cpp_and_javascript/embind.rst

@@ -56,7 +56,7 @@ the simple C++ ``lerp()`` :cpp:func:`function` to JavaScript.
 To compile the above example using *embind*, we invoke *emcc* with the
 :ref:`bind <emcc-bind>` option::
 
-   emcc --bind -o quick_example.js quick_example.cpp
+   emcc -lembind -o quick_example.js quick_example.cpp
 
 The resulting **quick_example.js** file can be loaded as a node module
 or via a ``<script>`` tag:
@@ -107,7 +107,7 @@ the object file.
 For example, to generate bindings for a hypothetical **library.a** compiled
 with Emscripten run *emcc* with ``--whole-archive`` compiler flag::
 
-   emcc --bind -o library.js -Wl,--whole-archive library.a -Wl,--no-whole-archive
+   emcc -lembind -o library.js -Wl,--whole-archive library.a -Wl,--no-whole-archive
 
 Classes
 =======
@@ -875,7 +875,7 @@ and then play the tone.
 
 The example can be compiled on the Linux/macOS terminal with::
 
-   emcc -O2 -Wall -Werror --bind -o oscillator.html oscillator.cpp
+   emcc -O2 -Wall -Werror -lembind -o oscillator.html oscillator.cpp
 
 
 Built-in type conversions

site/source/docs/tools_reference/emcc.rst

@@ -341,7 +341,7 @@ Options that are modified or new in *emcc* are listed below:
 
 ``--bind``
   [link]
-  Compiles the source code using the :ref:`embind` bindings to connect C/C++ and JavaScript.
+  Links against embind library.  Deprecated: Use ``-lembind`` instead.
 
 ``--ignore-dynamic-linking``
   [link]

src/settings.js

@@ -1202,7 +1202,7 @@ var EXPORT_NAME = 'Module';
 // When this flag is set, the following features (linker flags) are unavailable:
 //  -s RELOCATABLE=1: the function Runtime.loadDynamicLibrary would need to eval().
 // and some features may fall back to slower code paths when they need to:
-//  --bind: Embind uses eval() to jit functions for speed.
+// Embind: uses eval() to jit functions for speed.
 //
 // Additionally, the following Emscripten runtime functions are unavailable when
 // DYNAMIC_EXECUTION=0 is set, and an attempt to call them will throw an exception:

tests/test_core.py

@@ -6928,9 +6928,9 @@ def test2():
     do_test(test2, level=2, prefix='hello_libcxx')
 
   def test_embind(self):
-    self.emcc_args += ['--bind']
-
-    create_file('test_embind.cpp', r'''
+    # Very that both the old `--bind` arg and the new `-lembind` arg work
+    for args in [['-lembind'], ['--bind']]:
+      create_file('test_embind.cpp', r'''
       #include <stdio.h>
       #include <emscripten/val.h>
 
@@ -6945,11 +6945,11 @@ def test_embind(self):
 
         return 0;
       }
-    ''')
-    self.do_runf('test_embind.cpp', 'abs(-10): 10\nabs(-11): 11')
+      ''')
+      self.do_runf('test_embind.cpp', 'abs(-10): 10\nabs(-11): 11', emcc_args=args)
 
   def test_embind_2(self):
-    self.emcc_args += ['--bind', '--post-js', 'post.js']
+    self.emcc_args += ['-lembind', '--post-js', 'post.js']
     create_file('post.js', '''
       function printLerp() {
           out('lerp ' + Module.lerp(100, 200, 66) + '.');
@@ -6974,7 +6974,7 @@ def test_embind_2(self):
     self.do_runf('test_embind_2.cpp', 'lerp 166')
 
   def test_embind_3(self):
-    self.emcc_args += ['--bind', '--post-js', 'post.js']
+    self.emcc_args += ['-lembind', '--post-js', 'post.js']
     create_file('post.js', '''
       function ready() {
         try {
@@ -7002,7 +7002,7 @@ def test_embind_3(self):
     self.do_runf('test_embind_3.cpp', 'UnboundTypeError: Cannot call compute due to unbound types: Pi')
 
   def test_embind_4(self):
-    self.emcc_args += ['--bind', '--post-js', 'post.js']
+    self.emcc_args += ['-lembind', '--post-js', 'post.js']
     create_file('post.js', '''
       function printFirstElement() {
         out(Module.getBufferView()[0]);
@@ -7034,46 +7034,46 @@ def test_embind_4(self):
     self.do_runf('test_embind_4.cpp', '107')
 
   def test_embind_5(self):
-    self.emcc_args += ['--bind']
+    self.emcc_args += ['-lembind']
     self.set_setting('EXIT_RUNTIME')
     self.do_core_test('test_embind_5.cpp')
 
   def test_embind_custom_marshal(self):
-    self.emcc_args += ['--bind', '--pre-js', test_file('embind/test_custom_marshal.js')]
+    self.emcc_args += ['-lembind', '--pre-js', test_file('embind/test_custom_marshal.js')]
     self.do_run_in_out_file_test('embind/test_custom_marshal.cpp', assert_identical=True)
 
   def test_embind_float_constants(self):
-    self.emcc_args += ['--bind']
+    self.emcc_args += ['-lembind']
     self.do_run_in_out_file_test('embind/test_float_constants.cpp')
 
   def test_embind_negative_constants(self):
-    self.emcc_args += ['--bind']
+    self.emcc_args += ['-lembind']
     self.do_run_in_out_file_test('embind/test_negative_constants.cpp')
 
   @also_with_wasm_bigint
   def test_embind_unsigned(self):
-    self.emcc_args += ['--bind']
+    self.emcc_args += ['-lembind']
     self.do_run_in_out_file_test('embind/test_unsigned.cpp')
 
   def test_embind_val(self):
-    self.emcc_args += ['--bind']
+    self.emcc_args += ['-lembind']
     self.do_run_in_out_file_test('embind/test_val.cpp')
 
   def test_embind_val_assignment(self):
-    err = self.expect_fail([EMCC, test_file('embind/test_val_assignment.cpp'), '--bind', '-c'])
+    err = self.expect_fail([EMCC, test_file('embind/test_val_assignment.cpp'), '-lembind', '-c'])
     self.assertContained('candidate function not viable: expects an lvalue for object argument', err)
 
   @no_wasm2js('wasm_bigint')
   def test_embind_i64_val(self):
     self.set_setting('WASM_BIGINT')
-    self.emcc_args += ['--bind']
+    self.emcc_args += ['-lembind']
     self.node_args += ['--experimental-wasm-bigint']
     self.do_run_in_out_file_test('embind/test_i64_val.cpp', assert_identical=True)
 
   @no_wasm2js('wasm_bigint')
   def test_embind_i64_binding(self):
     self.set_setting('WASM_BIGINT')
-    self.emcc_args += ['--bind']
+    self.emcc_args += ['-lembind']
     self.node_args += ['--experimental-wasm-bigint']
     self.do_run_in_out_file_test('embind/test_i64_binding.cpp', assert_identical=True)
 
@@ -7102,11 +7102,11 @@ def test_embind_no_rtti(self):
         emscripten::function("dotest", &test);
       }
     ''')
-    self.emcc_args += ['--bind', '-fno-rtti', '-DEMSCRIPTEN_HAS_UNBOUND_TYPE_NAMES=0']
+    self.emcc_args += ['-lembind', '-fno-rtti', '-DEMSCRIPTEN_HAS_UNBOUND_TYPE_NAMES=0']
     self.do_runf('main.cpp', '418\ndotest returned: 42\n')
 
   def test_embind_polymorphic_class_no_rtti(self):
-    self.emcc_args += ['--bind', '-fno-rtti', '-DEMSCRIPTEN_HAS_UNBOUND_TYPE_NAMES=0']
+    self.emcc_args += ['-lembind', '-fno-rtti', '-DEMSCRIPTEN_HAS_UNBOUND_TYPE_NAMES=0']
     self.do_core_test('test_embind_polymorphic_class_no_rtti.cpp')
 
   def test_embind_no_rtti_followed_by_rtti(self):
@@ -7134,7 +7134,7 @@ def test_embind_no_rtti_followed_by_rtti(self):
         emscripten::function("dotest", &test);
       }
     '''
-    self.emcc_args += ['--bind', '-fno-rtti', '-frtti']
+    self.emcc_args += ['-lembind', '-fno-rtti', '-frtti']
     self.do_run(src, '418\ndotest returned: 42\n')
 
   @parameterized({
@@ -8544,7 +8544,7 @@ def test_pthread_create_embind_stack_check(self):
     # embind should work with stack overflow checks (see #12356)
     self.set_setting('STACK_OVERFLOW_CHECK', 2)
     self.set_setting('EXIT_RUNTIME')
-    self.emcc_args += ['--bind']
+    self.emcc_args += ['-lembind']
     self.do_run_in_out_file_test('core/pthread/create.cpp')
 
   @node_pthreads
@@ -8814,7 +8814,7 @@ def test_abort_on_exceptions(self):
     self.set_setting('EXIT_RUNTIME', 0)
     self.set_setting('ABORT_ON_WASM_EXCEPTIONS')
     self.set_setting('EXPORTED_RUNTIME_METHODS', ['ccall', 'cwrap'])
-    self.emcc_args += ['--bind', '--post-js', test_file('core/test_abort_on_exception_post.js')]
+    self.emcc_args += ['-lembind', '--post-js', test_file('core/test_abort_on_exception_post.js')]
     self.do_core_test('test_abort_on_exception.cpp', interleaved_output=False)
 
   @needs_dylink
@@ -8856,7 +8856,7 @@ def test_emscripten_async_call(self):
   def test_embind_lib_with_asyncify(self, args):
     self.uses_es6 = True
     self.emcc_args += [
-      '--bind',
+      '-lembind',
       '-sASYNCIFY',
       '-sASYNCIFY_IMPORTS=["sleep_and_return"]',
       '--post-js', test_file('core/embind_lib_with_asyncify.test.js'),

tests/test_other.py

@@ -824,7 +824,7 @@ def test_incorrect_c_detection(self):
     # For linking you need to use `em++` or pass `-x c++`
     create_file('test.c', 'foo\n')
     for compiler in [EMCC, EMXX]:
-      self.run_process([compiler, '-c', '--bind', '--embed-file', 'test.c', test_file('hello_world.cpp')])
+      self.run_process([compiler, '-c', '-lembind', '--embed-file', 'test.c', test_file('hello_world.cpp')])
 
   def test_odd_suffixes(self):
     for suffix in ['CPP', 'c++', 'C++', 'cxx', 'CXX', 'cc', 'CC']:
@@ -1081,7 +1081,7 @@ def test(compiler, main_name, lib_args, err_expected):
         return 0;
       }
     ''')
-    test(EMXX, 'main.cpp', ['-Wl,--start-group', lib_name, '-Wl,--end-group', '--bind'], None)
+    test(EMXX, 'main.cpp', ['-Wl,--start-group', lib_name, '-Wl,--end-group', '-lembind'], None)
 
   def test_whole_archive(self):
     # Verify that -Wl,--whole-archive includes the static constructor from the
@@ -2362,7 +2362,7 @@ def test_embind_asyncify(self):
           function("sleep", &emscripten_sleep);
       }
     ''')
-    self.run_process([EMXX, 'main.cpp', '--bind', '-sASYNCIFY', '--post-js', 'post.js'])
+    self.run_process([EMXX, 'main.cpp', '-lembind', '-sASYNCIFY', '--post-js', 'post.js'])
     self.assertContained('done', self.run_js('a.out.js'))
 
   def test_embind_closure_no_dynamic_execution(self):
@@ -2387,18 +2387,18 @@ def test_embind_closure_no_dynamic_execution(self):
         emscripten::function("bar", &bar);
       }
     ''')
-    self.run_process([EMXX, 'main.cpp', '--bind', '-O2', '--closure', '1',
+    self.run_process([EMXX, 'main.cpp', '-lembind', '-O2', '--closure', '1',
                       '-sNO_DYNAMIC_EXECUTION', '--post-js', 'post.js'])
     self.assertContained('10\nok\n', self.run_js('a.out.js'))
 
   @is_slow_test
   @with_env_modify({'EMCC_CLOSURE_ARGS': '--externs ' + shlex.quote(test_file('embind/underscore-externs.js'))})
   def test_embind(self):
     test_cases = [
-        (['--bind']),
-        (['--bind', '-O1']),
-        (['--bind', '-O2']),
-        (['--bind', '-O2', '-sALLOW_MEMORY_GROWTH', test_file('embind/isMemoryGrowthEnabled=true.cpp')]),
+        (['-lembind']),
+        (['-lembind', '-O1']),
+        (['-lembind', '-O2']),
+        (['-lembind', '-O2', '-sALLOW_MEMORY_GROWTH', test_file('embind/isMemoryGrowthEnabled=true.cpp')]),
     ]
     without_utf8_args = ['-sEMBIND_STD_STRING_IS_UTF8=0']
     test_cases_without_utf8 = []
@@ -2407,7 +2407,7 @@ def test_embind(self):
     test_cases += test_cases_without_utf8
     test_cases.extend([(args[:] + ['-sDYNAMIC_EXECUTION=0']) for args in test_cases])
     # closure compiler doesn't work with DYNAMIC_EXECUTION=0
-    test_cases.append((['--bind', '-O2', '--closure=1']))
+    test_cases.append((['-lembind', '-O2', '--closure=1']))
     for args in test_cases:
       print(args)
       self.clear()
@@ -4460,7 +4460,7 @@ def test(args=[]):
       self.assertContained('%d %d %d __attribute__((used))' % (shared.EMSCRIPTEN_VERSION_MAJOR, shared.EMSCRIPTEN_VERSION_MINOR, shared.EMSCRIPTEN_VERSION_TINY), out)
 
     test()
-    test(['--bind'])
+    test(['-lembind'])
 
   def test_dashE_respect_dashO(self):
     # issue #3365
@@ -10754,7 +10754,7 @@ def test_deps_info(self):
       if 'emscripten_pc_get_function' in function:
         cmd.append('-sUSE_OFFSET_CONVERTER')
       if 'embind' in function:
-        cmd.append('--bind')
+        cmd.append('-lembind')
       if 'websocket' in function:
         cmd += ['-sPROXY_POSIX_SOCKETS', '-lwebsocket.js']
       if function == 'Mix_LoadWAV_RW':

tools/building.py

@@ -1362,6 +1362,7 @@ def map_to_js_libs(library_name):
   """
   # Some native libraries are implemented in Emscripten as system side JS libraries
   library_map = {
+    'embind': ['embind/embind.js', 'embind/emval.js'],
     'EGL': ['library_egl.js'],
     'GL': ['library_webgl.js', 'library_html5_webgl.js'],
     'webgl.js': ['library_webgl.js', 'library_html5_webgl.js'],
@@ -1390,6 +1391,7 @@ def map_to_js_libs(library_name):
   }
   # And some are hybrid and require JS and native libraries to be included
   native_library_map = {
+    'embind': 'libembind',
     'GL': 'libGL',
   }