From 953e76e63e4d0407bd60ca79332b7baf51c68e80 Mon Sep 17 00:00:00 2001 From: Sam Clegg Date: Mon, 18 May 2026 15:23:37 -0700 Subject: [PATCH] Update documentation on the `-shared` flag In particular, mention the `FAKE_DYLIBS` setting. This is important especially since we are about the change the default behavior. See #25930 --- .../docs/compiling/Building-Projects.rst | 23 +++++-------------- .../source/docs/compiling/Dynamic-Linking.rst | 22 ++++++++++++++++-- 2 files changed, 26 insertions(+), 19 deletions(-) diff --git a/site/source/docs/compiling/Building-Projects.rst b/site/source/docs/compiling/Building-Projects.rst index 23d67267273ed..752bd8b135518 100644 --- a/site/source/docs/compiling/Building-Projects.rst +++ b/site/source/docs/compiling/Building-Projects.rst @@ -309,26 +309,15 @@ The simplest solution is usually to build the project twice: once natively, and In some cases it makes sense to modify the build scripts so that they build the generated executable natively. For example, this can be done by specifying two compilers in the build scripts, *emcc* and *gcc*, and using *gcc* just for generated executables. However, this can be more complicated than the previous solution because you need to modify the project build scripts, and you may have to work around cases where code is compiled and used both for the final result and for a generated executable. -Faux Dynamic Linking --------------------- +Dynamic Linking +--------------- Emscripten's goal is to generate the fastest and smallest possible code. For that reason it focuses on compiling an entire project into a single Wasm file, -avoiding dynamic linking when possible. - -By default, when the `-shared` flag is used to build a shared library, -Emscripten will produce an ``.so`` library that is actually just a regular -``.o`` object file (Under the hood it uses `ld -r` to combine objects into a -single larger object). When these faux "shared libraries" are linked into your -application they are effectively linked as static libraries. When building -these shared libraries *Emcc* will ignore other shared libraries on the command -line. This is to ensure that the same dynamic library is not linked multiple -times in intermediate build stages, which would result in duplicate symbol -errors. - -See :ref:`experimental support ` for how to build true dynamic -libraries, which can be linked together either at load time, or at runtime (via -dlopen). +and the recommendation is to avoiding dynamic linking in most cases. + +See :ref:`experimental support ` for more information if your +project requires dynamic linking. Configure may run checks that appear to fail diff --git a/site/source/docs/compiling/Dynamic-Linking.rst b/site/source/docs/compiling/Dynamic-Linking.rst index 81487447de38e..82cea6e8260f9 100644 --- a/site/source/docs/compiling/Dynamic-Linking.rst +++ b/site/source/docs/compiling/Dynamic-Linking.rst @@ -6,11 +6,11 @@ Dynamic Linking .. note:: This documentation is somewhat outdated and is in the process of being refreshed. -Emscripten supports linking object files (and ar archives that contain +Emscripten supports linking object files (and ``ar`` archives that contain object files) statically. This lets most build systems work with Emscripten with little or no changes (see :ref:`Building-Projects`). -In addition, Emscripten also has support for a form of **dynamic** linking of +In addition, Emscripten also has support for **dynamic** linking of WebAssembly modules. This can add overhead, so for best performance static linking should still be preferred. However, this overhead can be reduced with the use of certain command line flags. See below for details. @@ -145,6 +145,24 @@ it (except for ``dlopen(NULL)`` which means to open the current executable, which just works without filesystem integration). That’s basically it - you can then use ``dlopen(), dlsym()``, etc. normally. +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. + +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). + +This behaviour can be controlled using the :ref:`FAKE_DYLIBS` settings. If you +disable `FAKE_DYLIBS` then ``-shared`` will act like ``-sSIDE_MODULE``. + Code Size =========