1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
<h3 class="section">Native-Compilation Functions</h3> <p>Native-Compilation is implemented as a side effect of byte-compilation (see <a href="byte-compilation">Byte Compilation</a>). 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 <a href="compilation-functions">Compilation Functions</a>) are valid for native-compilation as well. </p> <p>You can natively-compile either a single function or macro definition, or a whole file of Lisp code, with the <code>native-compile</code> function. Natively-compiling a file will produce both the corresponding <samp>.elc</samp> file with byte code and the <samp>.eln</samp> file with native code. </p> <p>Native compilation might produce warning or error messages; these are normally recorded in the buffer called <samp>*Native-compile-Log*</samp>. In interactive sessions, it uses the special LIMPLE mode (<code>native-comp-limple-mode</code>), which sets up <code>font-lock</code> 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</code> variable (see <a href="native_002dcompilation-variables">Native-Compilation Variables</a>). </p> <p>When Emacs is run non-interactively, messages produced by native-compilation are reported by calling <code>message</code> (see <a href="displaying-messages">Displaying Messages</a>), and are usually displayed on the standard error stream of the terminal from which Emacs was invoked. </p> <dl> <dt id="native-compile">Function: <strong>native-compile</strong> <em>function-or-file &optional output</em>
</dt> <dd>
<p>This function compiles <var>function-or-file</var> into native code. The argument <var>function-or-file</var> 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</var> is provided, it must be a string specifying the name of the file to write the compiled code into. Otherwise, if <var>function-or-file</var> is a function or a Lisp form, this function returns the compiled object, and if <var>function-or-file</var> 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 <samp>.eln</samp> extension. </p> <p>This function runs the final phase of the native compilation, which invokes GCC via <samp>libgccjit</samp>, in a separate subprocess, which invokes the same Emacs executable as the process that called this function. </p>
</dd>
</dl> <dl> <dt id="batch-native-compile">Function: <strong>batch-native-compile</strong> <em>&optional for-tarball</em>
</dt> <dd><p>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 <var>for-tarball</var>, if non-<code>nil</code>, tells the function to place the resulting <samp>.eln</samp> files in the last directory mentioned in <code>native-comp-eln-load-path</code> (see <a href="library-search">Library Search</a>); 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. </p></dd>
</dl> <p>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 <code>native-comp-async-report-warnings-errors</code> in see <a href="native_002dcompilation-variables">Native-Compilation Variables</a> for more details. </p> <dl> <dt id="native-compile-async">Function: <strong>native-compile-async</strong> <em>files &optional recursively load selector</em>
</dt> <dd>
<p>This function compiles the named <var>files</var> asynchronously. The argument <var>files</var> 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</var> should be non-<code>nil</code> to cause the compilation to recurse into those directories. If <var>load</var> is non-<code>nil</code>, Emacs will load each file that it succeeded to compile. The optional argument <var>selector</var> allows control of which of <var>files</var> will be compiled; it can have one of the following values: </p> <dl compact> <dt>
<code>nil</code> or omitted</dt> <dd><p>Select all the files and directories in <var>files</var>. </p></dd> <dt>a regular expression string</dt> <dd><p>Select the files and directories whose names match the regexp. </p></dd> <dt>a function</dt> <dd><p>A predicate function, which will be called with each file and directory in <var>files</var>, and should return non-<code>nil</code> if the file or the directory should be selected for compilation. </p></dd> </dl> <p>On systems with multiple CPU execution units, when <var>files</var> names more than one file, this function will normally start several compilation subprocesses in parallel, under the control of <code>native-comp-async-jobs-number</code> (see <a href="native_002dcompilation-variables">Native-Compilation Variables</a>). </p>
</dd>
</dl> <p>The following function allows Lisp programs to test whether native-compilation is available at runtime. </p> <dl> <dt id="native-comp-available-p">Function: <strong>native-comp-available-p</strong>
</dt> <dd><p>This function returns non-<code>nil</code> if the running Emacs process has the native-compilation support compiled into it. On systems that load <samp>libgccjit</samp> 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. </p></dd>
</dl><div class="_attribution">
<p class="_attribution-p">
Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
<a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Native_002dCompilation-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Native_002dCompilation-Functions.html</a>
</p>
</div>
|
