doc: extend documentation on temporary directory for onefile programs

Extend the help message for `--runtime-tmpdir` with a note that
on POSIX, bootloader does not perform environment variable
expansion and that specifying environment variables in the path
will not work.

In `Defining the Extraction Location` section, describe the
possibility of setting environment variable(s) that control
the temporary directory, as an alternative to `--runtime-tmpdir`.
This also documents which environment variables are used under
POSIX and in what order; for Windows, we add reference to
GetTempPathW, whose reference page also documents the temporary
directory selection.

PyInstaller/building/makespec.py

@@ -640,9 +640,11 @@ def __add_options(parser):
         "--runtime-tmpdir",
         dest="runtime_tmpdir",
         metavar="PATH",
-        help="Where to extract libraries and support files in `onefile`-mode. If this option is given, the bootloader "
+        help="Where to extract libraries and support files in `onefile` mode. If this option is given, the bootloader "
         "will ignore any temp-folder location defined by the run-time OS. The ``_MEIxxxxxx``-folder will be created "
-        "here. Please use this option only if you know what you are doing.",
+        "here. Please use this option only if you know what you are doing. Note that on POSIX systems, PyInstaller's "
+        "bootloader does NOT perform shell-style environment variable expansion on the given path string. Therefore, "
+        "using environment variables (e.g., ``~`` or ``$HOME``) in path will NOT work.",
     )
     g.add_argument(
         "--bootloader-ignore-signals",

doc/operating-mode.rst

@@ -214,7 +214,9 @@ to mount the ``/tmp`` folder with a "no-execution" option.
 That option is not compatible with a PyInstaller
 one-file bundle. It needs to execute code out of :file:`/tmp`.
 If you know the target environment,
-:option:`--runtime-tmpdir` might be a workaround.)
+:option:`--runtime-tmpdir` might be a workaround. Alternatively,
+you can set the environment variable that controls the temporary
+directory before launching the program. See :ref:`defining the extraction location`).
 
 Because the program makes a temporary folder with a unique name,
 you can run multiple copies of the app;

doc/usage.rst

@@ -272,12 +272,66 @@ For a detailed description see :ref:`pyi_splash Module`.
 Defining the Extraction Location
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In rare cases, when you bundle to a single executable
-(see :ref:`Bundling to One File` and :ref:`how the one-file program works`),
-you may want to control the location of the temporary directory at compile
-time. This can be done using the :option:`--runtime-tmpdir` option. If this option is
-given, the bootloader will ignore any temp-folder location defined by the
-run-time OS. Please use this option only if you know what you are doing.
+When building your application in ``onefile`` mode (see :ref:`Bundling to
+One File` and :ref:`how the one-file program works`), you might encounter
+situations where you want to control the location of the temporary directory
+where the application unpacks itself. For example:
+
+- your application is supposed to be running for long periods of time,
+  and you need to prevent its files from being deleted by the OS that
+  performs periodic clean-up in standard temporary directories.
+
+- your target POSIX system does not use standard temporary directory
+  location (i.e., ``/tmp``) and the standard environment variables for
+  temporary directory are not set in the environment.
+
+- the default temporary directory on the target POSIX system is mounted
+  with ``noexec`` option, which prevents the frozen application from
+  loading the unpacked shared libraries.
+
+The location of the temporary directory can be overridden dynamically,
+by setting corresponding environment variable(s) before launching the
+application, or set statically, using the :option:`--runtime-tmpdir` option
+during the build process.
+
+Using environment variables
+---------------------------
+
+The extraction location can be controlled dynamically, by setting the
+environment variable(s) that PyInstaller uses to determine the temporary
+directory. This can, for example, be done in a wrapper shell script that
+sets the environment variable(s) before running the frozen application's
+executable.
+
+On POSIX systems, the environment variables used for temporary
+directory location are ``TMPDIR``, ``TEMP``, and ``TMP``, in that
+order; if none are defined (or the corresponding directories do not
+exist or cannot be used), ``/tmp``, ``/var/tmp``, and ``/usr/tmp`` are
+used as hard-coded fall-backs, in the specified order. The directory
+specified via the environment variable must exist (i.e., the application
+attempts to create only its own directory under the base temporary directory).
+
+On Windows, the default temporary directory location is determined via
+`GetTempPathW <https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-gettemppathw>`_
+function (which looks at ``TMP`` and ``TEMP`` environment variables for
+initial temporary directory candidates).
+
+Using the :option:`--runtime-tmpdir` option
+-------------------------------------------
+
+The location of the temporary directory can be set statically, at compile
+time, using the :option:`--runtime-tmpdir` option. If this option is used,
+the bootloader will ignore temporary directory locations defined by
+the OS, and use the specified path. The path can be either absolute
+or relative (which makes it relative to the current working directory).
+
+Please use this option only if you know what you are doing.
+
+.. note::
+    On POSIX systems, PyInstaller's bootloader does **not** perform shell-style
+    environment variable expansion on the path string given via
+    :option:`--runtime-tmpdir` option. Therefore, using environment
+    variables (e.g., ``~`` or ``$HOME``) in the path will **not** work.
 
 
 .. _supporting multiple platforms: