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 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.
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 natively-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.