18.2 Native-Compilation Variables

This section documents the variables that control native-compilation.

User Option: native-comp-speed

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.

User Option: 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:


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.

User Option: 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:


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.

User Option: 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.

User Option: native-comp-async-report-warnings-errors

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.

User Option: 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 .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.

Variable: native-comp-jit-compilation

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.

Variable: native-comp-enable-subr-trampolines

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.