emacs-28 4bd3dd505e: Document how to control where the *.eln files are written

[Eli Zaretskii]

branch: emacs-28
commit 4bd3dd505e4ae3094237a554587ffa509ed4db4e
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Document how to control where the *.eln files are written
    
    * doc/lispref/compile.texi (Native Compilation): Document the
    trick of pointing $HOME to a non-existent directory.
    (Native-Compilation Variables): Document the role of
    'native-comp-eln-load-path' in determining where *.eln files are
    written.
---
 doc/lispref/compile.texi | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index f336753a6c..1b75ae2884 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -847,6 +847,14 @@ native compilation of that file.  In addition, a similar 
variable
 file.  If both @code{no-byte-compile} and @code{no-native-compile} are
 specified, the former takes precedence.
 
+@cindex native compilation, prevent writing @file{*.eln} files
+  Sometimes there could be a need to prevent the native compilation
+from writing its results, the @file{*.eln} files, into a subdirectory
+of @code{user-emacs-directory} (@pxref{Init File}).  You can do that
+by either changing the value of @code{native-comp-eln-load-path}
+(@pxref{Native-Compilation Variables}) or by temporarily pointing the
+@env{HOME} environment variable to a non-existing directory.
+
 @menu
 * Native-Compilation Functions::  Functions to natively-compile Lisp.
 * Native-Compilation Variables::  Variables controlling native compilation.
@@ -1061,3 +1069,13 @@ subprocesses that are still running, thus preventing the 
corresponding
 @file{.eln} files from being written.  If the value is @code{nil}, the
 default, Emacs will kill these subprocesses without querying.
 @end defopt
+
+The variable @code{native-comp-eln-load-path} holds the list of
+directories where Emacs looks for the @file{*.eln} files
+(@pxref{Library Search}); in that role it is the equivalent of
+@code{load-path} used to look for @file{*.el} and @file{*.elc} files.
+The directories in this list are also used for writing the
+@file{*.eln} files produced by asynchronous native-compilation;
+specifically, Emacs will write these files into the first writable
+directory in the list.  Thus, you can control where native-compilation
+stores the results by changing the value of this variable.