From 240803cc3e1f361baf5665f91e4d0bd9576956a7 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Thu, 8 Jun 2023 08:50:54 +0300
Subject: [PATCH] Document 'startup-redirect-eln-cache'

* doc/lispref/compile.texi (Native Compilation)
(Native-Compilation Functions): Document
'startup-redirect-eln-cache'.

* etc/PROBLEMS: Fix last change.
* etc/NEWS: Mark 'startup-redirect-eln-cache' as documented.
---
 doc/lispref/compile.texi | 21 ++++++++++++++++++++-
 etc/NEWS                 |  2 +-
 etc/PROBLEMS             |  3 +--
 3 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 6ae6755ad76..a51691bddcf 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -854,7 +854,10 @@ that the latter technique might still produce a small number of
 @file{*.eln} files if Emacs needs to generate @dfn{trampolines}, which
 are used if Lisp primitives are advised or redefined in your Lisp code
 that is being natively compiled.  @xref{Native-Compilation Variables,
-trampolines}.
+trampolines}.  Alternatively, you can specify that the @file{*.eln}
+files are written to a non-default directory using the
+@code{startup-redirect-eln-cache} function; @pxref{Native-Compilation
+Functions}.
 
 @menu
 * Native-Compilation Functions::  Functions to natively-compile Lisp.
@@ -977,6 +980,22 @@ the native-compilation support compiled into it.  On systems that load
 @file{libgccjit} dynamically, it also makes sure that library is
 available and can be loaded.  Lisp programs that need to know up front
 whether native-compilation is available should use this predicate.
+@end defun
+
+  By default, asynchronous native compilation writes the @file{*.eln}
+files it produces to a subdirectory of the first writable directory
+specified by the @code{native-comp-eln-load-path} variable
+(@pxref{Native-Compilation Variables}).  You can change this by using
+the following function in your startup files:
+
+@defun startup-redirect-eln-cache cache-directory
+This function arranges for the asynchronous native compilation to
+write the produced @file{*.eln} files to @var{cache-directory}, which
+must be a single directory, a string.  It also destructively modifies
+@code{native-comp-eln-load-path} such that its first element is
+@var{cache-directory}.  If @var{cache-directory} is not an absolute
+file name, it is interpreted relative to @code{user-emacs-directory}
+(@pxref{Init File}).
 @end defun
 
 @node Native-Compilation Variables
diff --git a/etc/NEWS b/etc/NEWS
index d3146fab8eb..ca0d602e9ad 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -226,7 +226,7 @@ ones for the current Emacs version).  Note that subdirectories of the
 system directory where the "*.eln" files are installed (usually, the
 last entry in 'native-comp-eln-load-path') are not deleted.
 
----
++++
 *** New function 'startup-redirect-eln-cache'.
 This function can be called in your init files to change the
 user-specific directory where Emacs stores the "*.eln" files produced
diff --git a/etc/PROBLEMS b/etc/PROBLEMS
index 561b116c9bd..e5baa8ee18a 100644
--- a/etc/PROBLEMS
+++ b/etc/PROBLEMS
@@ -2755,8 +2755,7 @@ one, you could use the following workarounds:
     directory to that new home directory.
   . Move all the *.eln files from ~/.emacs.d/eln-cache to a directory
     out of the C:\Users tree, and customize Emacs to use that
-    directory for *.eln files.  This requires to add that directory to
-    the value of native-comp-eln-load-path, and also call the function
+    directory for *.eln files.  This requires to call the function
     startup-redirect-eln-cache in your init file, to force Emacs to
     write *.eln files compiled at run time to that directory.
   . Delete all *.eln files in your ~/.emacs.d/eln-cache directory, and
-- 
2.39.2