In addition to the byte-compilation, described in the previous chapter, Emacs can also optionally compile Lisp function definitions into a true compiled code, known as native code. This feature uses the libgccjit library, which is part of the GCC distribution, and requires that Emacs be built with support for using that library. It also requires GCC and Binutils (the assembler and linker) to be available on your system for you to be able to native-compile Lisp code.
To determine whether the current Emacs process can produce and load
natively compiled Lisp code, call
native-comp-available-p (see Native-Compilation Functions).
Unlike byte-compiled code, native-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 native-compiled code is 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 native-compiled code is the same as that of shared libraries (.so or .dll files).
Libraries of native-compiled code include crucial dependencies on Emacs Lisp primitives (see What Is a Function?) and their calling conventions, and thus Emacs usually won’t load native-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 enables several versions of the same Lisp library natively compiled by several different versions of Emacs to be placed within the same directory.
A non-nil file-local variable binding of
no-byte-compile (see Byte Compilation) also disables the
native compilation of that file. In addition, a similar variable
no-native-compile disables just the native compilation of the
file. If both no-byte-compile and no-native-compile are
specified, the former takes precedence.
Sometimes there could be a need to prevent the native compilation
from writing its results, the *.eln files, into a subdirectory
of user-emacs-directory (see The Init File). You can do that
by either changing the value of native-comp-eln-load-path
(see Native-Compilation Variables) or by temporarily pointing the
HOME environment variable to a non-existing directory. Note
that the latter technique might still produce a small number of
*.eln files if Emacs needs to generate trampolines, which
are used if Lisp primitives are advised or redefined in your Lisp code
that is being natively compiled. See trampolines. Alternatively, you can specify that the *.eln
files are written to a non-default directory using the
startup-redirect-eln-cache function; see Native-Compilation Functions.
Native-Compilation is implemented as a side effect of byte-compilation (see 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 (see Byte-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
native-compile function. Natively-compiling a file will
produce the .eln file with native code.
Native compilation might produce warning or error messages; these
are normally recorded in the buffer called
*Native-compile-Log*. In interactive sessions, it uses the
special LIMPLE mode (native-comp-limple-mode), which sets up
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 native-comp-verbose
variable (see Native-Compilation Variables).
When Emacs is run non-interactively, messages produced by
native-compilation are reported by calling message
(see Displaying Messages in the Echo Area), and are usually displayed on the
standard error stream of the terminal from which Emacs was invoked.
This function compiles function-or-file into native code. The argument 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 output is provided, it must be a string specifying the name of the file to write the compiled code into. Otherwise, if function-or-file is a function or a Lisp form, this function returns the compiled object, and if 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 .eln extension.
This function runs the final phase of the native compilation, which invokes GCC via libgccjit, in a separate subprocess, which invokes the same Emacs executable as the process that called this function.
This function recursively searches for .el files in
directory and any subdirectories thereof, and runs
native-compilation on any that have not already been compiled. To
determine whether a file has already been compiled, it searches for a
corresponding .eln in the native-comp-eln-load-path
variable (see Native-Compilation Variables).
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. The optional argument for-tarball, if
non-nil, tells the function to place the resulting .eln
files in the last directory mentioned in
native-comp-eln-load-path (see Library Search); this is
meant to be used as part of building an Emacs source tarball for the
first time, when the native-compiled files, which are absent from
the source tarball, should be generated in the build tree instead of
the user’s cache directory.
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 native-compiled file for it
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
native-comp-async-report-warnings-errors in see Native-Compilation Variables for more details.
This function compiles the named files asynchronously. The
argument 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 recursively should be
non-nil to cause the compilation to recurse into those
directories. If load is non-nil, Emacs will load each
file that it succeeded to compile. The optional argument
selector allows control of which of files will be
compiled; it can have one of the following values:
nil or omittedSelect all the files and directories in files.
Select the files and directories whose names match the regexp.
A predicate function, which will be called with each file and
directory in files, and should return non-nil if the file
or the directory should be selected for compilation.
On systems with multiple CPU execution units, when files names
more than one file, this function will normally start several
compilation subprocesses in parallel, under the control of
native-comp-async-jobs-number (see Native-Compilation Variables).
This function compiles into native code all the *.el files in the
specified directory and, recursively, in all of its
subdirectories, if a corresponding .eln file could not be found
in any of the directories mentioned in the
native-comp-eln-load-path list (see Library Search).
This command compiles the file visited by the current buffer into native code, if the file was changed since the last time it was natively compiled.
This command compiles the file visited by the current buffer into
native code, like emacs-lisp-native-compile, but it also loads
the native code when the compilation finishes.
The following function allows Lisp programs to test whether native-compilation is available at runtime.
This function returns non-nil if the running Emacs process has
the native-compilation support compiled into it. On systems that load
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.
By default, asynchronous native compilation writes the *.eln
files it produces to a subdirectory of the first writable directory
specified by the native-comp-eln-load-path variable
(see Native-Compilation Variables). You can change this by using
the following function in your startup files:
This function arranges for the asynchronous native compilation to
write the produced *.eln files to cache-directory, which
must be a single directory, a string. It also destructively modifies
native-comp-eln-load-path such that its first element is
cache-directory. If cache-directory is not an absolute
file name, it is interpreted relative to user-emacs-directory
(see The Init File).
This section documents the variables that control native-compilation.
This variable specifies the optimization level for native compilation.
Its value should be a number between −1 and 3. Values between
0 and 3 specify the optimization levels equivalent to the
corresponding compiler -O0, -O1, etc. command-line
options of the compiler. The value −1 means disable
native-compilation: functions and files will be only byte-compiled;
however, the *.eln files will still be produced, they will just
contain the compiled code in bytecode form. (This can be achieved at
function granularity by using the (declare (speed -1))
form, see The declare Form.)
The default value is 2.
This variable specifies the safety level to be used for the emitted native code. The value should be a number, either 0 or 1 with the following meanings:
Emitted code can misbehave (up to even crashing Emacs) if a function’s declaration does not describe correctly what the function does or how it is called, and the function is natively compiled.
Emitted code must be generated in a safe manner even if functions are mis-declared.
This can also be controlled at a function granularity, by using the
safety declare form, see The declare Form.
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:
No debugging output. This is the default.
Emit debugging symbols with the native code. This allows easier
debugging of the native code with debuggers such as gdb.
Like 1, and in addition dump pseudo-C code.
Like 2, and in addition dump the GCC intermediate passes and libgccjit log file.
When generated, the pseudo-C code is deposited in the same directory as the corresponding .eln file.
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:
No logging. This is the default.
Log the final LIMPLE representation of the code.
Log the LAP, the final LIMPLE, and some additional pass info.
Maximum verbosity: log everything.
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.
If this variable’s value is non-nil, warnings and errors from
asynchronous native-compilation subprocesses are reported in the main
Emacs session in a buffer named *Warnings*. The default value
t means display the resulting buffer. To log warnings without
popping up the *Warnings* buffer, set this variable to
silent.
A common cause for asynchronous native-compilation to produce
warnings is compiling a file that is missing some 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.
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
.eln files from being written. If the value is nil, the
default, Emacs will kill these subprocesses without querying.
The variable native-comp-eln-load-path holds the list of
directories where Emacs looks for the *.eln files
(see Library Search); in that role it is the equivalent of
load-path used to look for *.el and *.elc files.
The directories in this list are also used for writing the
*.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.
This variable, if non-nil, enables asynchronous (a.k.a.
just-in-time, or JIT) native compilation of the
*.elc files loaded by Emacs for which the corresponding
*.eln files do not already exist. This JIT compilation uses
separate Emacs sub-processes running in batch mode, according to the
value of native-comp-async-jobs-number. When the JIT
compilation of a Lisp file finishes successfully, the resulting
.eln file is loaded and its code replaces the definition of
functions provided by the .elc file.
Setting the value of native-comp-jit-compilation to nil
disables JIT native compilation. However, even when JIT native
compilation is disabled, Emacs might still need to start asynchronous
native compilation subprocesses to produce trampolines. To
control this, use a separate variable, described below.
This variable controls generation of trampolines. A trampoline is a
small piece of native code required to allow calling Lisp primitives,
which were advised or redefined, from Lisp code that was
natively compiled with native-comp-speed set to 2 or greater.
Emacs stores the generated trampolines on separate *.eln files.
By default, this variable’s value is t, which enables the
generation of trampoline files; setting it to nil disables the
generation of trampolines. Note that if a trampoline needed for
advising or redefining a primitive is not available and cannot be
generated, calls to that primitive from native-compiled Lisp will
ignore redefinitions and advices, and will behave as if the primitive
was called directly from C. Therefore, we don’t recommend disabling
the trampoline generation, unless you know that all the trampolines
needed by your Lisp programs are already compiled and accessible to
Emacs.
The value of this variable can also be a string, in which case it
specifies the name of a directory in which to store the generated
trampoline *.eln files, overriding the directories in
native-comp-eln-load-path. This is useful if you want the
trampolines to be generated as needed, but don’t want to store them
under the user’s HOME directory or in the other public
directories where *.eln files are kept. However, unlike with
directories in native-comp-eln-load-path, the trampolines will
be stored in the directory given by the value of this variable, not in
its version-specific subdirectory. If the name of this directory is
not absolute, it is interpreted relative to
invocation-directory (see Operating System Environment)
If this variable is non-nil, and Emacs needs to produce a
trampoline, but it cannot find any writable directory to store the
trampoline, it will store it inside temporary-file-directory
(see Generating Unique File Names).
Trampolines produced when no writable directory is found to store them, or when this variable is a string, will only be available for the duration of the current Emacs session, because Emacs doesn’t look for trampolines in either of these places.