Enable real dynamic linking with -shared by default

This change essentially disables `FAKE_DYLIBS` by default, which in
turn means `-shared` will now produce dynamic libraries by default.

If you want the old behaviour you now need `-sFAKE_DYLIBS`.

Author: sbc100

ChangeLog.md

@@ -49,6 +49,12 @@ See docs/process.md for more on how version tagging works.
   e.g. Intel x64 Macs and Windows-on-ARM, downloading Java SE Development Kit
   21.0.11 from https://www.oracle.com/europe/java/technologies/downloads/#java21
   is required in order to use Emscripten's Closure Compiler integration.
+  Closure compiler now provides a native macOS arm64 binary for Apple Silicon.
+- The `FAKE_DYLIBS` setting is now disabled by default. This means that
+  `-shared` will produce real dynamic libraries by default (`-sSIDE_MODULE` is
+  implied).  Also, if you include real dynamic libraries in your link comment
+  emscripten will now automatically produce a dynamically linked program
+  (`-sMAIN_MODULE=2` is implied). (#25930)
 
 5.0.7 - 04/30/26
 ----------------

site/source/docs/compiling/Dynamic-Linking.rst

@@ -111,7 +111,8 @@ before your application starts to run.
 -  Build one part of your code as the main module, linking it using
    ``-sMAIN_MODULE`` (See :ref:`MAIN_MODULE`).
 -  Build other parts of your code as side modules, linking it using
-   ``-sSIDE_MODULE`` (See :ref:`SIDE_MODULE`).
+   ``-shared``.  You can also used the emscripten-specific :ref:`SIDE_MODULE`
+   setting which does the same thing by default.
 
 For the main module the output suffix should be ``.js`` (the WebAssembly
 file will be generated alongside it just like normal).  For the side
@@ -149,19 +150,17 @@ Building Dynamic Libraries using ``-shared``
 ============================================
 
 In traditional toolchains the ``-shared`` flag is used to generated dynamic
-libraries.  However, because dynamic linking in Emscripten comes with caveats
-and has some overhead, Emscripten does not currently produce real dynamic
-libraries when this flag is used.  Instead, Emscripten will produce a fake
-dynamic library (along with a warning) that is actually a single static object
-file.  When your main program is linked against this fake dynamic library it
-gets linked into your main program like any other object file.
+libraries.  Historically, due to early limitations, Emscripten would produce a
+fake dynamic library (along with a warning) when the ``-shared`` flag was used.
+When your main program is linked against these fake dynamic library they would
+be linked into your main program like regular static other object files.
 
-The reason for this behaviour is to allow projects (and build systems) that
-assume a working ``-shared`` flag to build successfully (albeit using static
-linking).
+These days Emscripten will produce real dynamic libraries by default and
+``-shared`` is essentially the same as ``-sSIDE_MODULE``.
 
 This behaviour can be controlled using the :ref:`FAKE_DYLIBS` settings.  If you
-disable `FAKE_DYLIBS` then ``-shared`` will act like ``-sSIDE_MODULE``.
+prefer the older behaviour with fake dynamic libraryies you can enable this
+setting.
 
 Code Size
 =========

site/source/docs/tools_reference/settings_reference.rst

@@ -3356,13 +3356,13 @@ Default value: false
 FAKE_DYLIBS
 ===========
 
-This setting changes the behaviour of the ``-shared`` flag.  The default
-setting of ``true`` means the ``-shared`` flag actually produces a normal
-object file (i.e. ``ld -r``).  Setting this to false will cause ``-shared``
-to behave like :ref:`SIDE_MODULE` and produce a dynamically linked
-library.
+This setting changes the behaviour of the ``-shared`` flag.  When set to true
+you get the old emscripten behaviour where the ``-shared`` flag actually
+produces a normal object file (i.e. ``ld -r``).  When set to true (the
+default) the ``-shared`` flag is equivelent to :ref:`SIDE_MODULE` and will
+produce a Wasn dynamic library.
 
-Default value: true
+Default value: false
 
 .. _executable:
 

src/settings.js

@@ -2201,12 +2201,12 @@ var GROWABLE_ARRAYBUFFERS = false;
 // indirectly using `importScripts`
 var CROSS_ORIGIN = false;
 
-// This setting changes the behaviour of the ``-shared`` flag.  The default
-// setting of ``true`` means the ``-shared`` flag actually produces a normal
-// object file (i.e. ``ld -r``).  Setting this to false will cause ``-shared``
-// to behave like :ref:`SIDE_MODULE` and produce a dynamically linked
-// library.
-var FAKE_DYLIBS = true;
+// This setting changes the behaviour of the ``-shared`` flag.  When set to true
+// you get the old emscripten behaviour where the ``-shared`` flag actually
+// produces a normal object file (i.e. ``ld -r``).  When set to true (the
+// default) the ``-shared`` flag is equivelent to :ref:`SIDE_MODULE` and will
+// produce a Wasn dynamic library.
+var FAKE_DYLIBS = false;
 
 // Add a #! line to generated JS file and make it executable.  This is useful
 // for building command line tools that run under node.

test/common.py

@@ -1517,7 +1517,7 @@ def get_poppler_library(self, env_init=None):
 
     return poppler + freetype
 
-  def get_zlib_library(self, cmake, cflags=None):
+  def get_zlib_library(self, cmake, cflags=None, target='libz.a'):
     assert cmake or not WINDOWS, 'on windows, get_zlib_library only supports cmake'
 
     old_args = self.cflags.copy()
@@ -1531,12 +1531,12 @@ def get_zlib_library(self, cmake, cflags=None):
     # https://github.com/emscripten-core/emscripten/issues/16908 is fixed
     self.cflags.append('-Wno-pointer-sign')
     if cmake:
-      rtn = self.get_library(os.path.join('third_party', 'zlib'), os.path.join('libz.a'),
+      rtn = self.get_library(os.path.join('third_party', 'zlib'), target,
                              configure=['cmake', '.'],
                              make=['cmake', '--build', '.', '--'],
                              make_args=[])
     else:
-      rtn = self.get_library(os.path.join('third_party', 'zlib'), os.path.join('libz.a'), make_args=['libz.a'])
+      rtn = self.get_library(os.path.join('third_party', 'zlib'), target, make_args=['libz.a', target])
     self.cflags = old_args
     return rtn
 

test/test_core.py

@@ -4051,8 +4051,8 @@ def dylink_testf(self, main, side=None, expected=None, force_c=False, main_cflag
 
     shutil.move(so_file, so_file + '.orig')
 
-    # Verify that building with -sSIDE_MODULE is essentially the same as building with `-shared -fPIC -sFAKE_DYLIBS=0`.
-    flags = ['-shared', '-fPIC', '-sFAKE_DYLIBS=0']
+    # Verify that building with -sSIDE_MODULE is essentially the same as building with `-shared -fPIC`
+    flags = ['-shared', '-fPIC']
     if isinstance(side, list):
       # side is just a library
       self.run_process([EMCC] + side + self.get_cflags() + flags + ['-o', so_file])
@@ -5079,7 +5079,8 @@ def do_run(src, expected_output, cflags=None):
 
   @with_dylink_reversed
   def test_dylink_dot_a(self):
-    # .a linking must force all .o files inside it, when in a shared module
+    # Tests that it's possible to link a .a archive into a dynamic library using
+    # `-Wl,--whole-archive`
     create_file('third.c', 'int sidef() { return 36; }')
     create_file('fourth.c', 'int sideg() { return 17; }')
 
@@ -5097,7 +5098,7 @@ def test_dylink_dot_a(self):
       }
     ''',
                      # contents of libfourth.a must be included, even if they aren't referred to!
-                     side=['libfourth.a', 'third.o'],
+                     side=['-Wl,--whole-archive', 'libfourth.a', '-Wl,--no-whole-archive', 'third.o'],
                      expected=['sidef: 36, sideg: 17.\n'], force_c=True)
 
   @with_dylink_reversed
@@ -5141,16 +5142,25 @@ def test_dylink_spaghetti(self):
 '''])
 
   @needs_make('mingw32-make')
-  @with_dylink_reversed
-  def test_dylink_zlib(self):
-    zlib_archive = self.get_zlib_library(cmake=WINDOWS, cflags=['-fPIC'])
+  @needs_dylink
+  @parameterized({
+    # Cmake support for dyanamic libraries is currently broken.
+    # We set `TARGET_SUPPORTS_SHARED_LIBS` to `FALSE` in in cmake/Modules/Platform/Emscripten.cmake
+    # which means cmake won't build shared libraries yet.
+    # https://gitlab.kitware.com/cmake/cmake/-/work_items/27240
+    # 'cmake': (True,),
+    'configure': (False,),
+  })
+  def test_dylink_zlib(self, cmake):
+    zlib_archive = self.get_zlib_library(cmake=cmake, target='libz.so.1.2.5', cflags=['-fPIC'])[0]
+    zlib_basename = os.path.basename(zlib_archive)
+    shutil.copyfile(zlib_archive, zlib_basename)
     # example.c uses K&R style function declarations
     self.cflags.append('-Wno-deprecated-non-prototype')
     self.cflags.append('-I' + test_file('third_party/zlib'))
-    self.dylink_test(main=read_file(test_file('third_party/zlib/example.c')),
-                     side=zlib_archive,
-                     expected=read_file(test_file('core/test_zlib.out')),
-                     force_c=True)
+    self.do_runf(test_file('third_party/zlib/example.c'),
+                 read_file(test_file('core/test_zlib.out')),
+                 cflags=['-L.', zlib_archive])
 
   # @with_dylink_reversed
   # def test_dylink_bullet(self):

test/test_other.py

@@ -932,7 +932,8 @@ def test_cmake_explicit_generator(self):
     # use -Wno-dev to suppress an irrelevant warning about the test files only.
     cmd = [EMCMAKE, 'cmake', '-GNinja', '-Wno-dev', test_file('cmake/cpp_lib')]
     self.run_process(cmd)
-    self.assertExists(self.get_dir() + '/build.ninja')
+    self.assertExists('build.ninja')
+    self.run_process(['ninja', '-v'])
 
   # Tests that it's possible to pass C++17 or GNU++17 build modes to CMake by building code that
   # needs C++17 (embind)
@@ -1175,7 +1176,7 @@ def test_odd_suffixes(self):
     for suffix in ('lo',):
       self.clear()
       print(suffix)
-      self.run_process([EMCC, test_file('hello_world.c'), '-shared', '-o', 'binary.' + suffix])
+      self.run_process([EMCC, test_file('hello_world.c'), '-shared', '-fPIC', '-o', 'binary.' + suffix])
       self.run_process([EMCC, 'binary.' + suffix])
       self.assertContained('Hello, world!', self.run_js('a.out.js'))
 
@@ -1360,11 +1361,11 @@ def test_multiply_defined_libsymbols(self):
     # we model shared libraries using regular object files.  Without special handling
     # fake `libA.so` could get linked multiple times.
     self.cflags.remove('-Werror')
-    self.emcc('libA.c', ['-shared', '-o', 'libA.so'])
+    self.emcc('libA.c', ['-sFAKE_DYLIBS', '-shared', '-fPIC', '-o', 'libA.so'])
 
-    err = self.emcc('a2.c', ['-shared', '-L.', '-lA', '-o', 'liba2.so'], stderr=PIPE).stderr
+    err = self.emcc('a2.c', ['-sFAKE_DYLIBS', '-shared', '-fPIC', '-L.', '-lA', '-o', 'liba2.so'], stderr=PIPE).stderr
     self.assertContained('emcc: warning: ignoring dynamic library libA.so when generating an object file', err)
-    err = self.emcc('b2.c', ['-shared', '-L.', '-lA', '-o', 'libb2.so'], stderr=PIPE).stderr
+    err = self.emcc('b2.c', ['-sFAKE_DYLIBS', '-shared', '-fPIC', '-L.', '-lA', '-o', 'libb2.so'], stderr=PIPE).stderr
     self.assertContained('emcc: warning: ignoring dynamic library libA.so when generating an object file', err)
 
     self.do_runf('main.c', 'result: 1', cflags=['-L.', '-lA', 'liba2.so', 'libb2.so'])
@@ -1495,7 +1496,12 @@ def test_link_group_bitcode(self):
   # We deliberately ignore duplicate input files in order to allow
   # "libA.so" on the command line twice. This is not really .so support
   # and the .so files are really object files.
-  def test_redundant_link(self):
+  @parameterized({
+    '': ([],),
+    'fake_dylibs': (['-sFAKE_DYLIBS'],),
+  })
+  def test_redundant_link(self, args):
+    self.cflags += args
     create_file('libA.c', 'int mult() { return 1; }')
     create_file('main.c', r'''
       #include <stdio.h>
@@ -1507,7 +1513,7 @@ def test_redundant_link(self):
     ''')
 
     self.cflags.remove('-Werror')
-    self.emcc('libA.c', ['-shared', '-o', 'libA.so'])
+    self.emcc('libA.c', ['-fPIC', '-shared', '-o', 'libA.so'])
     self.emcc('main.c', ['libA.so', 'libA.so', '-o', 'a.out.js'])
     self.assertContained('result: 1', self.run_js('a.out.js'))
 
@@ -2155,9 +2161,9 @@ def test_multidynamic_link(self, link_flags, lib_suffix):
     ''')
 
     # Build libfile normally into an .so
-    self.run_process([EMCC, 'libdir/libfile.c', '-shared', '-o', 'libdir/libfile.so' + lib_suffix])
+    self.run_process([EMCC, 'libdir/libfile.c', '-sFAKE_DYLIBS', '-shared', '-fPIC', '-o', 'libdir/libfile.so' + lib_suffix])
     # Build libother and dynamically link it to libfile
-    self.run_process([EMCC, '-Llibdir', 'libdir/libother.c'] + link_flags + ['-shared', '-o', 'libdir/libother.so'])
+    self.run_process([EMCC, '-Llibdir', 'libdir/libother.c'] + link_flags + ['-sFAKE_DYLIBS', '-shared', '-fPIC', '-o', 'libdir/libother.so'])
     # Build the main file, linking in both the libs
     self.run_process([EMCC, '-Llibdir', os.path.join('main.c')] + link_flags + ['-lother', '-c'])
     print('...')
@@ -2462,17 +2468,17 @@ def test_dylink_library_search(self):
       }
     ''')
 
-    # By deafult we use static linking and prefer libside.a
-    self.do_runf('main.c', 'static linking used\n', cflags=['-L.', '-lside'])
+    # By default we use dynamic linking
+    self.do_runf('main.c', 'dynamic linking used\n', cflags=['-L.', '-lside'])
 
-    # When using -sMAIN_MODULE we choose the dyanmic library
-    self.do_runf('main.c', 'dynamic linking used\n', cflags=['-sMAIN_MODULE=2', '-L.', '-lside'])
+    # When using -sMAIN_MODULE=0 we explictly opt out of dynammic linking
+    self.do_runf('main.c', 'static linking used\n', cflags=['-sMAIN_MODULE=0', '-L.', '-lside'])
 
-    # Same for `-sFAKE_DYLIBS=0
-    self.do_runf('main.c', 'dynamic linking used\n', cflags=['-sFAKE_DYLIBS=0', '-L.', '-lside'])
+    # Same for `-sFAKE_DYLIBS
+    self.do_runf('main.c', 'static linking used\n', cflags=['-sFAKE_DYLIBS', '-L.', '-lside'])
 
     # With can also force static linking using `-Bstatic` linker falgs
-    self.do_runf('main.c', 'static linking used\n', cflags=['-sMAIN_MODULE=2', '-L.', '-Bstatic', '-lside'])
+    self.do_runf('main.c', 'static linking used\n', cflags=['-L.', '-Bstatic', '-lside'])
 
   def test_js_link(self):
     create_file('before.js', '''
@@ -4955,20 +4961,6 @@ def test_valid_abspath_2(self):
     self.run_process(cmd)
     self.assertContained('Hello, world!', self.run_js('a.out.js'))
 
-  def test_warn_dylibs(self):
-    shared_suffixes = ['.so', '.dylib', '.dll']
-
-    for suffix in ('.o', '.bc', '.so', '.dylib', '.js', '.html'):
-      print(suffix)
-      cmd = [EMCC, test_file('hello_world.c'), '-o', 'out' + suffix]
-      if suffix in {'.o', '.bc'}:
-        cmd.append('-c')
-      if suffix in {'.dylib', '.so'}:
-        cmd.append('-shared')
-      err = self.run_process(cmd, stderr=PIPE).stderr
-      warning = 'linking a library with `-shared` will emit a static object file'
-      self.assertContainedIf(warning, err, suffix in shared_suffixes)
-
   @crossplatform
   @parameterized({
     'O2': [['-O2']],
@@ -8464,12 +8456,12 @@ def test_side_module_ignore(self):
     self.run_process([EMCC, test_file('hello_world.c'), '-sSIDE_MODULE', '-o', 'libside.so'])
 
     # Attempting to link statically against a side module (libside.so) should fail.
-    self.assert_fail([EMCC, '-L.', '-lside'], 'wasm-ld: error: unable to find library -lside')
+    self.assert_fail([EMCC, '-L.', '-Bstatic', '-lside'], 'wasm-ld: error: unable to find library -lside')
 
     # But a static library in the same location (libside.a) should take precedence.
     self.run_process([EMCC, test_file('hello_world.c'), '-c'])
     self.run_process([EMAR, 'cr', 'libside.a', 'hello_world.o'])
-    self.run_process([EMCC, '-L.', '-lside'])
+    self.run_process([EMCC, '-L.', '-Bstatic', '-lside'])
     self.assertContained('Hello, world!', self.run_js('a.out.js'))
 
   @is_slow_test
@@ -12131,42 +12123,40 @@ def test_err(self):
   def test_euidaccess(self):
     self.do_other_test('test_euidaccess.c')
 
-  def test_shared_flag(self):
-    create_file('side.c', 'int foo;')
-    self.run_process([EMCC, '-shared', 'side.c', '-o', 'libother.so'])
+  def test_fake_dylibs(self):
+    create_file('other.c', 'int foo = 10;')
+    self.run_process([EMCC, '-shared', '-sFAKE_DYLIBS', '-fPIC', 'other.c', '-o', 'libother.so'])
+    self.assertIsObjectFile('libother.so')
 
-    # Test that `-shared` flag causes object file generation but gives a warning
-    err = self.run_process([EMCC, '-shared', test_file('hello_world.c'), '-o', 'out.foo', 'libother.so'], stderr=PIPE).stderr
-    self.assertContained('linking a library with `-shared` will emit a static object', err)
+    # Test that `-sFAKE_DYLIBS` flag causes object file generation and will generate a warning about
+    # dylink dependencies being ignored.
+    err = self.run_process([EMCC, '-shared', '-sFAKE_DYLIBS', '-fPIC', test_file('hello_world.c'), '-o', 'out.foo', 'libother.so'], stderr=PIPE).stderr
     self.assertContained('emcc: warning: ignoring dynamic library libother.so when generating an object file, this will need to be included explicitly in the final link', err)
     self.assertIsObjectFile('out.foo')
 
     # Test that adding `-sFAKE_DYLIBS=0` build a real side module
     err = self.run_process([EMCC, '-shared', '-fPIC', '-sFAKE_DYLIBS=0', test_file('hello_world.c'), '-o', 'out.foo', 'libother.so'], stderr=PIPE).stderr
-    self.assertNotContained('linking a library with `-shared` will emit a static object', err)
     self.assertNotContained('emcc: warning: ignoring dynamic library libother.so when generating an object file, this will need to be included explicitly in the final link', err)
     self.assertIsWasmDylib('out.foo')
 
     # Test that using an executable output name overrides the `-shared` flag, but produces a warning.
-    err = self.run_process([EMCC, '-shared', test_file('hello_world.c'), '-o', 'out.js'],
+    err = self.run_process([EMCC, '-shared', '-sFAKE_DYLIBS', '-fPIC', test_file('hello_world.c'), '-o', 'out.js'],
                            stderr=PIPE).stderr
     self.assertContained('warning: -shared/-r used with executable output suffix', err)
     self.run_js('out.js')
 
   def test_shared_soname(self):
-    self.run_process([EMCC, '-shared', '-Wl,-soname', '-Wl,libfoo.so.13', test_file('hello_world.c'), '-lc', '-o', 'libfoo.so'])
+    self.run_process([EMCC, '-shared', '-sFAKE_DYLIBS', '-Wl,-soname', '-Wl,libfoo.so.13', test_file('hello_world.c'), '-lc', '-o', 'libfoo.so'])
     self.run_process([EMCC, '-sSTRICT', 'libfoo.so'])
     self.assertContained('Hello, world!', self.run_js('a.out.js'))
 
-  def test_shared_and_side_module_flag(self):
-    # Test that `-shared` and `-sSIDE_MODULE` flag causes wasm dylib generation without a warning.
-    err = self.run_process([EMCC, '-shared', '-sSIDE_MODULE', test_file('hello_world.c'), '-o', 'out.foo'], stderr=PIPE).stderr
-    self.assertNotContained('linking a library with `-shared` will emit a static object', err)
+  def test_shared_flag(self):
+    # Test that `-shared` flag causes wasm dylib generation
+    self.run_process([EMCC, '-shared', '-fPIC', test_file('hello_world.c'), '-o', 'out.foo'])
     self.assertIsWasmDylib('out.foo')
 
-    # Test that `-shared` and `-sSIDE_MODULE` flag causes wasm dylib generation without a warning even if given executable output name.
-    err = self.run_process([EMCC, '-shared', '-sSIDE_MODULE', test_file('hello_world.c'), '-o', 'out.wasm'],
-                           stderr=PIPE).stderr
+    # Test that `-shared` causes wasm dylib generation warning even if given executable output name.
+    err = self.run_process([EMCC, '-shared', '-fPIC', test_file('hello_world.c'), '-o', 'out.wasm'], stderr=PIPE).stderr
     self.assertNotContained('warning: -shared/-r used with executable output suffix', err)
     self.assertIsWasmDylib('out.wasm')