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

All that the `--bind` flag does is enable the embind library (native
and JS portions), so I think its more clear if we just use the normal
`-l` method of including it.

Historically `--bind` has sounded to some (including myself) like a
verb rather than the name of a library leading to folks to believe that
the linker is actually doing the binding, whereas all the binding is
done either at compile time or at load time.  No "binding" happens
during linking.

Author: sbc100

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'
+
     # On Windows Vista (and possibly others), excessive spaces in the command line
     # leak into the items in this array, so trim e.g. 'foo.cpp ' -> 'foo.cpp'
     newargs[i] = newargs[i].strip()
@@ -3067,10 +3072,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

@@ -6924,9 +6924,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>
 
@@ -6941,11 +6941,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) + '.');
@@ -6970,7 +6970,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 {
@@ -6998,7 +6998,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]);
@@ -7030,46 +7030,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)
 
@@ -7098,11 +7098,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):
@@ -7130,7 +7130,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({
@@ -8540,7 +8540,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
@@ -8810,7 +8810,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
@@ -8852,7 +8852,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
@@ -2358,7 +2358,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):
@@ -2383,18 +2383,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 = []
@@ -2403,7 +2403,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()
@@ -4456,7 +4456,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
@@ -10751,7 +10751,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',
   }