document how to invoke system programs

doc/runtime-information.rst

@@ -101,6 +101,36 @@ symbolic link::
 
 
 
+LD_LIBRARY_PATH / LIBPATH considerations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This environment variable is used to discover libraries, it is the library
+search path - on Linux and *BSD `LD_LIBRARY_PATH` is used, on AIX it is
+`LIBPATH`.
+
+PyInstaller saves the original value to `*_ORIG`, then modifies the search
+path so that the bundled libraries are found first by the bundled code.
+
+But if your code executes a system program, you often do not want that this
+system program loads your bundled libraries (that are maybe not compatible
+with your system program) - it rather should load the correct libraries from
+the system locations like it usually does.
+
+Thus you need to restore the original path before creating the subprocess
+with the system program.
+
+::
+
+    env = dict(os.environ)  # make a copy of the environment
+    lp_key = 'LD_LIBRARY_PATH'  # for Linux and *BSD.
+    lp_orig = env.get(lp_key + '_ORIG')  # pyinstaller >= 20160820 has this
+    if lp_orig is not None:
+        env[lp_key] = lp_orig  # restore the original, unmodified value
+    else:
+        env.pop(lp_key, None)  # last resort: remove the env var
+    p = Popen(system_cmd, ..., env=env)  # create the process
+
+
 .. include:: _common_definitions.txt
 
 .. Emacs config: