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 both the corresponding .elc file with byte code and 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
variable (see Native-Compilation Variables).
When Emacs is run non-interactively, messages produced by
native-compilation are reported by calling
(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 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
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 natively-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 natively-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
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:
Select 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).
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
(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
(see The Init File).