From 58b0bcd16df83d914fe4d538e6be88cac9574906 Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Wed, 5 May 2021 10:31:33 +0200 Subject: Use @defmac on eval-{and,when}-compile * doc/lispref/compile.texi (Eval During Compile): Use @defmac instead of @defspec on two macros (bug#47862). --- doc/lispref/compile.texi | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/lispref/compile.texi') diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 66242343157..bf420040950 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -361,7 +361,7 @@ it does nothing. It always returns @var{function}. These features permit you to write code to be evaluated during compilation of a program. -@defspec eval-and-compile body@dots{} +@defmac eval-and-compile body@dots{} This form marks @var{body} to be evaluated both when you compile the containing code and when you run it (whether compiled or not). @@ -386,9 +386,9 @@ If functions are defined programmatically (with @code{fset} say), then @code{eval-and-compile} can be used to have that done at compile-time as well as run-time, so calls to those functions are checked (and warnings about ``not known to be defined'' suppressed). -@end defspec +@end defmac -@defspec eval-when-compile body@dots{} +@defmac eval-when-compile body@dots{} This form marks @var{body} to be evaluated at compile time but not when the compiled program is loaded. The result of evaluation by the compiler becomes a constant which appears in the compiled program. If @@ -434,7 +434,7 @@ with other versions of Emacs. Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp @samp{#.} reader macro (but not when interpreting) is closer to what @code{eval-when-compile} does. -@end defspec +@end defmac @node Compiler Errors @section Compiler Errors -- cgit v1.2.3 From 79e2d0486c89c6c452df33792976ea6fdf825185 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 8 May 2021 16:26:41 +0300 Subject: Document native-compilation * doc/lispref/loading.texi (How Programs Do Loading) (Library Search): Update for native-compilation features. * doc/lispref/compile.texi (Native Compilation) (Native-Compilation Functions, Native-Compilation Variables): New chapter and sections. * doc/lispref/elisp.texi (Top): Update the top-level menus. * etc/NEWS: Add a reference to the ELisp manual. --- doc/lispref/compile.texi | 245 +++++++++++++++++++++++++++++++++++++++++++++++ doc/lispref/elisp.texi | 6 ++ doc/lispref/loading.texi | 33 ++++++- etc/NEWS | 5 +- 4 files changed, 286 insertions(+), 3 deletions(-) (limited to 'doc/lispref/compile.texi') diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index bf420040950..f0787795cac 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -793,3 +793,248 @@ The @code{silly-loop} function is somewhat more complex: 17 return ; @r{Return value of the top of stack.} @end group @end example + +@node Native Compilation +@chapter Compilation of Lisp to Native Code +@cindex native compilation +@cindex compilation to native code (Emacs Lisp) + +@cindex native code + In addition to the byte-compilation, described in @ref{Byte +Compilation, previous chapter}, Emacs can also optionally compile Lisp +function definitions into a true compiled code, known as @dfn{native +code}. This feature uses the @file{libgccjit} library, which is part +of the GCC distribution, and requires that Emacs be built with support +for using that library. It also requires to have GCC and Binutils +(the assembler and linker) available on your system 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 +@code{native-comp-available-p} (@pxref{Native-Compilation Functions}). + + Unlike byte-compiled code, natively-compiled Lisp code is executed +directly by the machine's hardware, and therefore runs at full speed +that the host CPU can provide. The resulting speedup generally +depends on what the Lisp code does, but is usually 2.5 to 5 times +faster than the corresponding byte-compiled code. + + Since native code is generally incompatible between different +systems, the natively-compiled code is @emph{not} transportable from +one machine to another, it can only be used on the same machine where +it was produced or on very similar ones (having the same CPU and +run-time libraries). The transportability of natively-compiled code +is the same as that of shared libraries (@file{.so} or @file{.dll} +files). + + Libraries of natively-compiled code include crucial dependencies on +Emacs Lisp primitives (@pxref{What Is a Function}) and their calling +conventions, and thus Emacs usually won't load natively-compiled code +produced by earlier or later Emacs versions; native compilation of the +same Lisp code by a different Emacs version will usually produce a +natively-compiled library under a unique file name that only that +version of Emacs will be able to load. However, the use of unique +file names allows to have in the same directory several versions of +the same Lisp library natively-compiled by several different versions +of Emacs. + +@vindex no-native-compile + A non-@code{nil} file-local variable binding of +@code{no-byte-compile} (@pxref{Byte Compilation}) also disables the +native compilation of that file. In addition, a similar variable +@code{no-native-compile} disables just the native compilation of the +file. If both @code{no-byte-compile} and @code{no-native-compile} are +specified, the former takes precedence. + +@menu +* Native-Compilation Functions:: Functions to natively-compile Lisp. +* Native-Compilation Variables:: Variables controlling native compilation. +@end menu + +@node Native-Compilation Functions +@section Native-Compilation Functions +@cindex native-compilation functions + + Native-Compilation is implemented as side effect of +byte-compilation (@pxref{Byte Compilation}). Thus, compiling Lisp +code natively always produces its byte code as well, and therefore all +the rules and caveats of preparing Lisp code for byte compilation +(@pxref{Compilation Functions}) are valid for native-compilation as +well. + + You can natively-compile either a single function or macro +definition, or a whole file of Lisp code, with the +@code{native-compile} function. Natively-compiling a file will +produce both the corresponding @file{.elc} file with byte code and the +@file{.eln} file with native code. + +@findex native-comp-limple-mode +@vindex native-comp-verbose + Native compilation might produce warning or error messages; these +are normally recorded in the buffer called +@file{*Native-compile-Log*}. In interactive sessions, it uses the +special LIMPLE mode (@code{native-comp-limple-mode}), which sets up +@code{font-lock} as appropriate for this log, and is otherwise the +same as Fundamental mode. Logging of messages resulting from +native-compilation can be controlled by the @code{native-comp-verbose} +variable (@pxref{Native-Compilation Variables}). + + When Emacs is run non-interactively, messages produced by +native-compilation are reported by calling @code{message} +(@pxref{Displaying Messages}), and are usually displayed on the +standard error stream of the terminal from which Emacs was invoked. + +@defun native-compile function-or-file &optional output +This function compiles @var{function-or-file} into native code. The +argument @var{function-or-file} can be a function symbol, a Lisp form, +or a name (a string) of the file which contains the Emacs Lisp source +code to compile. If the optional argument @var{output} is provided, +it must be a string specifying the name of the file to write the +compiled code. Otherwise, if @var{function-or-file} is a function or +a Lisp form, this function returns the compiled object, and if +@var{function-or-file} is a file name, the function returns the full +absolute name of the file it created for the compiled code. The +output file is by default given the @file{.eln} extension. + +This function runs the final phase of the native compilation, which +invokes GCC via @file{libgccjit}, in a separate sub-process, which +invokes the same Emacs executable as the process that called this +function. +@end defun + +@defun batch-native-compile +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. +@end defun + +Native compilation can be run entirely asynchronously, in a +sub-process 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. + +@defun native-compile-async files &optional recursively load selector +This function compiles the named @var{files} asynchronously. The +argument @var{files} should be a single file name (a string) or a list +of one or more file and/or directory names. If directories are +present in the list, the optional argument @var{recursively} should be +non-@code{nil} to cause the compilation to recurse into those +directories. If @var{load} is non-@code{nil}, Emacs will load each +file that it succeeded to compile. The optional argument +@var{selector} allows control of which of @var{files} will be +compiled; it can have one of the following values: + +@table @asis +@item @code{nil} or omitted +Select all the files and directories in @var{files}. +@item a regular expression string +Select the files and directories whose names match the regexp. +@item a function +A predicate function, which will be called with each file and +directory in @var{files}, and should return non-@code{nil} if the file +or the directory should be selected for compilation. +@end table + +On systems with multiple CPU execution units, when @var{files} names +more than one file, this function will normally start several +compilation sub-processes in parallel, under the control of +@code{native-comp-async-jobs-number} (@pxref{Native-Compilation +Variables}). +@end defun + + The following function allows Lisp program to test whether +native-compilation is available at runtime. + +@defun native-comp-available-p +This function returns non-@code{nil} if the running Emacs process has +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 + +@node Native-Compilation Variables +@section Native-Compilation Variables +@cindex native-compilation variable + + This section documents the variables that control +native-compilation. + +@defopt native-comp-speed +This variable specifies the optimization level for native compilation. +Its value should be a number between @minus{}1 and 3. Values between +0 and 3 specify the optimization levels equivalent to the +corresponding compiler @option{-O0}, @option{-O1}, etc.@: command-line +options of the compiler. The value @minus{}1 means disable +native-compilation; functions and files will be only byte-compiled. +The default value is 2. +@end defopt + +@defopt native-comp-debug +This variable specifies the level of debugging information produced by +native-compilation. Its value should be a number between zero and 3, +with the following meaning: + +@table @asis +@item 0 +No debugging output. This is the default. +@item 1 +Emit debugging symbols with the native code. This allows easier +debugging of the native code with debuggers such as @command{gdb}. +@item 2 +Like 1, and in addition dump pseudo-C code. +@item 3 +Like 2, and in addition dump the GCC intermediate passes and +@file{libgccjit} log file. +@end table +@end defopt + +@defopt native-comp-verbose +This variable controls the verbosity of native-compilation by +suppressing some or all of the log messages emitted by it. If its +value is zero, the default, all of the log messages are suppressed. +Setting it to a value between 1 and 3 will allow logging of the +messages whose level is above the value. The values have the +following interpretations: + +@table @asis +@item 0 +No logging. This is the default. +@item 1 +Log the final @acronym{LIMPLE} representation of the code. +@item 2 +Log the @acronym{LAP}, the final @acronym{LIMPLE}, and some additional +pass info. +@item 3 +Maximum verbosity: log everything. +@end table +@end defopt + +@defopt native-comp-async-jobs-number +This variable determines the maximum number of native-compilation +subprocesses that will be started simultaneously. It should be a +non-negative number. The default value is zero, which means use half +the number of the CPU execution units, or 1 if the CPU has only one +execution unit. +@end defopt + +@defopt native-comp-async-report-warnings-errors +If this variable's value is non-@code{nil}, warnings and errors from +asynchronous native-compilation subprocesses are reported in the main +Emacs session. The default is @code{t}. +@end defopt + +@defopt native-comp-async-query-on-exit +If this variable's value is non-nil, Emacs will query upon exiting +whether to exit and kill any asynchronous native-compilation +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 diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index be0c835b035..8b440c79774 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -197,6 +197,7 @@ To view this manual in other formats, click * Loading:: Reading files of Lisp code into Lisp. * Byte Compilation:: Compilation makes programs run faster. +* Native Compilation:: Compile Lisp into native machine code. * Debugging:: Tools and tips for debugging Lisp programs. * Read and Print:: Converting Lisp objects to text and back. @@ -646,6 +647,11 @@ Byte Compilation * Byte-Code Objects:: The data type used for byte-compiled functions. * Disassembly:: Disassembling byte-code; how to read byte-code. +Native Compilation + +* Native-Compilation Functions:: Functions to natively-compile Lisp. +* Native-Compilation Variables:: Variables controlling native compilation. + Debugging Lisp Programs * Debugger:: A debugger for the Emacs Lisp evaluator. diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index e68a1ef314a..4d683da1ad3 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -71,7 +71,11 @@ forms in it, and closes the file. To find the file, @code{load} first looks for a file named @file{@var{filename}.elc}, that is, for a file whose name is @var{filename} with the extension @samp{.elc} appended. If such a -file exists, it is loaded. If there is no file by that name, then +file exists, and Emacs was compiled with native-compilation support +(@pxref{Native Compilation}), @code{load} attempts to find a +corresponding @samp{.eln} file, and if found, loads it instead of +@file{@var{filename}.elc}. Otherwise, it loads +@file{@var{filename}.elc}. If there is no file by that name, then @code{load} looks for a file named @file{@var{filename}.el}. If that file exists, it is loaded. If Emacs was compiled with support for dynamic modules (@pxref{Dynamic Modules}), @code{load} next looks for @@ -109,6 +113,8 @@ explicit directory name. If the option @code{load-prefer-newer} is non-@code{nil}, then when searching suffixes, @code{load} selects whichever version of a file (@samp{.elc}, @samp{.el}, etc.)@: has been modified most recently. +In this case, @code{load} doesn't load the @samp{.eln} +natively-compiled file even if it exists. If @var{filename} is a relative file name, such as @file{foo} or @file{baz/foo.bar}, @code{load} searches for the file using the variable @@ -153,7 +159,8 @@ during compilation. @xref{Compiling Macros}. Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear in the echo area during loading unless @var{nomessage} is -non-@code{nil}. +non-@code{nil}. If a natively-compiled @samp{.eln} file is loaded, +the message says so. @cindex load errors Any unhandled errors while loading a file terminate loading. If the @@ -430,6 +437,28 @@ optional argument @code{stringp} is non-@code{nil}, it instead returns the shadowed files as a string. @end deffn + If Emacs was compiled with support for native compilation +(@pxref{Native Compilation}), then when a @samp{.elc} byte-compiled +file is found by searching @code{load-path}, Emacs will try to look +for a corresponding @samp{.eln} file holding the corresponding +natively-compiled code. The natively-compiled files are looked up in +the directories listed by the @code{native-comp-eln-load-path}. + +@vindex comp-native-version-dir +@defvar native-comp-eln-load-path +This variable holds a list of directories where Emacs looks for +natively-compiled @samp{.eln} files. File names in the list that are +not absolute are interpreted as relative to @code{invocation-directory} +(@pxref{System Environment}). The last directory in the list is the +system directory, i.e.@: the directory with @samp{.eln} files +installed by the Emacs build and installation procedure. In each of +the directories in the list, Emacs looks for @samp{.eln} files in a +subdirectory whose name is constructed from the Emacs version and an +8-character hash that depends on the current native-compilation +@acronym{ABI}; the name of this subdirectory is stored in the variable +@code{comp-native-version-dir}. +@end defvar + @node Loading Non-ASCII @section Loading Non-@acronym{ASCII} Characters @cindex loading, and non-ASCII characters diff --git a/etc/NEWS b/etc/NEWS index 9f4ded3aaba..6efadfec6f9 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -26,7 +26,10 @@ applies, and please also update docstrings as needed. ** Emacs now optionally supports native compilation of Lisp files. To enable this, configure Emacs with the '--with-native-compilation' option. -This requires the libgccjit library to be installed and functional. +This requires the libgccjit library to be installed and functional, +and also requires GCC and Binutils to be available when Lisp code is +natively compiled. See the Info node "(elisp) Native Compilation" for +more details. --- ** Support for building with Motif has been removed. -- cgit v1.2.3 From bb8b8d717f91a85ca41de9e82246e6975e1ed719 Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" Date: Sat, 8 May 2021 17:53:41 +0100 Subject: Tiny fixes to recent native compilation docs For discussion, see the following thread: https://lists.gnu.org/r/emacs-devel/2021-05/msg00347.html * doc/lispref/compile.texi (Native Compilation): Fix grammar in @ref online label. (Native-Compilation Functions): Consistently unhyphenate 'sub-process'. Fix grammar. (Native-Compilation Variables): Fix @cindex entry. --- doc/lispref/compile.texi | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) (limited to 'doc/lispref/compile.texi') diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index f0787795cac..ee31b17af72 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -801,13 +801,13 @@ The @code{silly-loop} function is somewhat more complex: @cindex native code In addition to the byte-compilation, described in @ref{Byte -Compilation, previous chapter}, Emacs can also optionally compile Lisp -function definitions into a true compiled code, known as @dfn{native -code}. This feature uses the @file{libgccjit} library, which is part -of the GCC distribution, and requires that Emacs be built with support -for using that library. It also requires to have GCC and Binutils -(the assembler and linker) available on your system for you to be able -to native-compile Lisp code. +Compilation, the previous chapter}, Emacs can also optionally compile +Lisp function definitions into a true compiled code, known as +@dfn{native code}. This feature uses the @file{libgccjit} library, +which is part of the GCC distribution, and requires that Emacs be +built with support for using that library. It also requires to have +GCC and Binutils (the assembler and linker) available on your system +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 @@ -857,7 +857,7 @@ specified, the former takes precedence. @section Native-Compilation Functions @cindex native-compilation functions - Native-Compilation is implemented as side effect of + Native-Compilation is implemented as a side effect of byte-compilation (@pxref{Byte Compilation}). Thus, compiling Lisp code natively always produces its byte code as well, and therefore all the rules and caveats of preparing Lisp code for byte compilation @@ -892,14 +892,14 @@ argument @var{function-or-file} can be a function symbol, a Lisp form, or a name (a string) of the file which contains the Emacs Lisp source code to compile. If the optional argument @var{output} is provided, it must be a string specifying the name of the file to write the -compiled code. Otherwise, if @var{function-or-file} is a function or -a Lisp form, this function returns the compiled object, and if -@var{function-or-file} is a file name, the function returns the full -absolute name of the file it created for the compiled code. The +compiled code into. Otherwise, if @var{function-or-file} is a +function or a Lisp form, this function returns the compiled object, +and if @var{function-or-file} is a file name, the function returns the +full absolute name of the file it created for the compiled code. The output file is by default given the @file{.eln} extension. This function runs the final phase of the native compilation, which -invokes GCC via @file{libgccjit}, in a separate sub-process, which +invokes GCC via @file{libgccjit}, in a separate subprocess, which invokes the same Emacs executable as the process that called this function. @end defun @@ -913,12 +913,12 @@ attempt to compile all the other files, and will terminate with a non-zero status code. @end defun -Native compilation can be run entirely asynchronously, in a -sub-process 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. +Native compilation can be run entirely asynchronously, in a subprocess +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. @defun native-compile-async files &optional recursively load selector This function compiles the named @var{files} asynchronously. The @@ -944,12 +944,12 @@ or the directory should be selected for compilation. On systems with multiple CPU execution units, when @var{files} names more than one file, this function will normally start several -compilation sub-processes in parallel, under the control of +compilation subprocesses in parallel, under the control of @code{native-comp-async-jobs-number} (@pxref{Native-Compilation Variables}). @end defun - The following function allows Lisp program to test whether + The following function allows Lisp programs to test whether native-compilation is available at runtime. @defun native-comp-available-p @@ -962,7 +962,7 @@ whether native-compilation is available should use this predicate. @node Native-Compilation Variables @section Native-Compilation Variables -@cindex native-compilation variable +@cindex native-compilation variables This section documents the variables that control native-compilation. -- cgit v1.2.3 From 43fd13770a8ac8452669e4de3281e9189cb36c5a Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" Date: Sat, 22 May 2021 13:22:29 +0100 Subject: Fix native-comp-async-report-warnings-errors :type * doc/lispref/compile.texi (Native-Compilation Variables): Document 'silent' alternative of native-comp-async-report-warnings-errors. * lisp/emacs-lisp/comp.el (native-comp-async-report-warnings-errors): Fix quoting in :type expression (bug#48586). --- doc/lispref/compile.texi | 5 ++++- lisp/emacs-lisp/comp.el | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) (limited to 'doc/lispref/compile.texi') diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index ee31b17af72..f48f4f47e8b 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -1028,7 +1028,10 @@ execution unit. @defopt native-comp-async-report-warnings-errors If this variable's value is non-@code{nil}, warnings and errors from asynchronous native-compilation subprocesses are reported in the main -Emacs session. The default is @code{t}. +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}. @end defopt @defopt native-comp-async-query-on-exit diff --git a/lisp/emacs-lisp/comp.el b/lisp/emacs-lisp/comp.el index 8c638312b05..b09739cb92e 100644 --- a/lisp/emacs-lisp/comp.el +++ b/lisp/emacs-lisp/comp.el @@ -154,7 +154,7 @@ buffer." :type '(choice (const :tag "Do not report warnings" nil) (const :tag "Report and display warnings" t) - (const :tag "Report but do not display warnings" 'silent)) + (const :tag "Report but do not display warnings" silent)) :version "28.1") (defcustom native-comp-async-query-on-exit nil -- cgit v1.2.3