diff options
Diffstat (limited to 'doc/lispref/compile.texi')
| -rw-r--r-- | doc/lispref/compile.texi | 26 |
1 files changed, 21 insertions, 5 deletions
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index f48f4f47e8b..1ca1f66b95d 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -811,8 +811,7 @@ for you to be able to native-compile Lisp code. @vindex native-compile@r{, a Lisp feature} To determine whether the current Emacs process can produce and load -natively-compiled Lisp code, test whether the @code{native-compile} -feature is available (@pxref{Named Features}). Alternatively, call +natively-compiled Lisp code, call @code{native-comp-available-p} (@pxref{Native-Compilation Functions}). Unlike byte-compiled code, natively-compiled Lisp code is executed @@ -904,13 +903,20 @@ invokes the same Emacs executable as the process that called this function. @end defun -@defun batch-native-compile +@defun batch-native-compile &optional for-tarball This function runs native-compilation on files specified on the Emacs command line in batch mode. It must be used only in a batch execution of Emacs, as it kills Emacs upon completion of the compilation. If one or more of the files fail to compile, the Emacs process will attempt to compile all the other files, and will terminate with a -non-zero status code. +non-zero status code. The optional argument @var{for-tarball}, if +non-@code{nil}, tells the function to place the resulting @file{.eln} +files in the last directory mentioned in +@code{native-comp-eln-load-path} (@pxref{Library Search}); this is +meant to be used as part of building an Emacs source tarball for the +first time, when the natively-compiled files, which are absent from +the source tarball, should be generated in the build tree instead of +the user's cache directory. @end defun Native compilation can be run entirely asynchronously, in a subprocess @@ -918,7 +924,11 @@ of the main Emacs process. This leaves the main Emacs process free to use while the compilation runs in the background. This is the method used by Emacs to natively-compile any Lisp file or byte-compiled Lisp file that is loaded into Emacs, when no natively-compiled file for it -is available. +is available. Note that because of this use of a subprocess, native +compilation may produce warning and errors which byte-compilation does +not, and lisp code may thus need to be modified to work correctly. See +@code{native-comp-async-report-warnings-errors} in @pxref{Native-Compilation +Variables} for more details. @defun native-compile-async files &optional recursively load selector This function compiles the named @var{files} asynchronously. The @@ -1032,6 +1042,12 @@ Emacs session in a buffer named @file{*Warnings*}. The default value @code{t} means display the resulting buffer. To log warnings without popping up the @file{*Warnings*} buffer, set this variable to @code{silent}. + + A common cause for asynchronous native-compilation to produce +warnings is compiling a file that is missing some @code{require} of a +necessary feature. The feature may be loaded into the main emacs, but +because native compilation always starts from a subprocess with a +pristine environment, that may not be true for the subprocess. @end defopt @defopt native-comp-async-query-on-exit |