Update documentation on the -shared flag

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 <Dynamic-Linking>` 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 <Dynamic-Linking>` for more information if your
+project requires dynamic linking.
 
 
 Configure may run checks that appear to fail

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
 =========