Clarify setting of library environment variables in module examples (#3730)

Co-authored-by: Hugo Locurcio <hugo.locurcio@hugo.pro>

development/cpp/binding_to_external_libraries.rst

@@ -8,8 +8,8 @@ Modules
 
 The Summator example in :ref:`doc_custom_modules_in_c++` is great for small,
 custom modules, but what if you want to use a larger, external library?
-Let's look at an example using Festival, a speech synthesis (text-to-speech)
-library written in C++.
+Let's look at an example using `Festival <http://www.cstr.ed.ac.uk/projects/festival/>`_,
+a speech synthesis (text-to-speech) library written in C++.
 
 To bind to an external library, set up a module directory similar to the Summator example:
 
@@ -163,11 +163,20 @@ environment's paths:
 
 .. code-block:: python
 
-    env_tts.Append(CPPPATH=["speech_tools/include", "festival/src/include"]) # this is a path relative to /modules/tts/
-    # http://www.cstr.ed.ac.uk/projects/festival/manual/festival_28.html#SEC132 <-- Festival library documentation
-    env_tts.Append(LIBPATH=['libpath']) # this is a path relative to /modules/tts/ where your .a library files reside
-    # You should check with the documentation of the external library to see which library files should be included/linked
-    env_tts.Append(LIBS=['Festival', 'estools', 'estbase', 'eststring'])
+    # These paths are relative to /modules/tts/
+    env_tts.Append(CPPPATH=["speech_tools/include", "festival/src/include"])
+
+    # LIBPATH and LIBS need to be set on the real "env" (not the clone)
+    # to link the specified libraries to the Godot executable.
+
+    # This is a path relative to /modules/tts/ where your .a libraries reside.
+    # If you are compiling the module externally (not in the godot source tree),
+    # these will need to be full paths.
+    env.Append(LIBPATH=['libpath'])
+
+    # Check with the documentation of the external library to see which library
+    # files should be included/linked.
+    env.Append(LIBS=['Festival', 'estools', 'estbase', 'eststring'])
 
 If you want to add custom compiler flags when building your module, you need to clone
 `env` first, so it won't add those flags to whole Godot build (which can cause errors).

development/cpp/custom_modules_in_cpp.rst

@@ -418,22 +418,30 @@ library that will be dynamically loaded when starting our game's binary.
 
     # First, create a custom env for the shared library.
     module_env = env.Clone()
-    module_env.Append(CCFLAGS=['-fPIC'])  # Needed to compile shared library
-    # We don't want godot's dependencies to be injected into our shared library.
+
+    # Position-independent code is required for a shared library.
+    module_env.Append(CCFLAGS=['-fPIC'])
+
+    # Don't inject Godot's dependencies into our shared library.
     module_env['LIBS'] = []
 
-    # Now define the shared library. Note that by default it would be built
-    # into the module's folder, however it's better to output it into `bin`
-    # next to the Godot binary.
+    # Define the shared library. By default, it would be built in the module's
+    # folder, however it's better to output it into `bin` next to the
+    # Godot binary.
     shared_lib = module_env.SharedLibrary(target='#bin/summator', source=sources)
 
-    # Finally, notify the main env it has our shared library as a new dependency.
-    # To do so, SCons wants the name of the lib with it custom suffixes
+    # Finally, notify the main build environment it now has our shared library
+    # as a new dependency.
+
+    # LIBPATH and LIBS need to be set on the real "env" (not the clone)
+    # to link the specified libraries to the Godot executable.
+
+    env.Append(LIBPATH=['#bin'])
+
+    # SCons wants the name of the library with it custom suffixes
     # (e.g. ".linuxbsd.tools.64") but without the final ".so".
-    # We pass this along with the directory of our library to the main env.
     shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0]
     env.Append(LIBS=[shared_lib_shim])
-    env.Append(LIBPATH=['#bin'])
 
 Once compiled, we should end up with a ``bin`` directory containing both the
 ``godot*`` binary and our ``libsummator*.so``. However given the .so is not in