new repository

1 files changed, 52 insertions, 0 deletions

diff --git a/devdocs/elisp/compilation-functions.html b/devdocs/elisp/compilation-functions.html
new file mode 100644
index 00000000..00c5e5e0
--- /dev/null
+++ b/devdocs/elisp/compilation-functions.html
@@ -0,0 +1,52 @@
+ <h3 class="section">Byte-Compilation Functions</h3>  <p>You can byte-compile an individual function or macro definition with the <code>byte-compile</code> function. You can compile a whole file with <code>byte-compile-file</code>, or several files with <code>byte-recompile-directory</code> or <code>batch-byte-compile</code>. </p>  <p>Sometimes, the byte compiler produces warning and/or error messages (see <a href="compiler-errors">Compiler Errors</a>, for details). These messages are normally recorded in a buffer called <samp>*Compile-Log*</samp>, which uses Compilation mode. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Compilation-Mode.html#Compilation-Mode">Compilation Mode</a> in <cite>The GNU Emacs Manual</cite>. However, if the variable <code>byte-compile-debug</code> is non-<code>nil</code>, error messages will be signaled as Lisp errors instead (see <a href="errors">Errors</a>). </p>  <p>Be careful when writing macro calls in files that you intend to byte-compile. Since macro calls are expanded when they are compiled, the macros need to be loaded into Emacs or the byte compiler will not do the right thing. The usual way to handle this is with <code>require</code> forms which specify the files containing the needed macro definitions (see <a href="named-features">Named Features</a>). Normally, the byte compiler does not evaluate the code that it is compiling, but it handles <code>require</code> forms specially, by loading the specified libraries. To avoid loading the macro definition files when someone <em>runs</em> the compiled program, write <code>eval-when-compile</code> around the <code>require</code> calls (see <a href="eval-during-compile">Eval During Compile</a>). For more details, See <a href="compiling-macros">Compiling Macros</a>. </p> <p>Inline (<code>defsubst</code>) functions are less troublesome; if you compile a call to such a function before its definition is known, the call will still work right, it will just run slower. </p> <dl> <dt id="byte-compile">Function: <strong>byte-compile</strong> <em>symbol</em>
+</dt> <dd>
+<p>This function byte-compiles the function definition of <var>symbol</var>, replacing the previous definition with the compiled one. The function definition of <var>symbol</var> must be the actual code for the function; <code>byte-compile</code> does not handle function indirection. The return value is the byte-code function object which is the compiled definition of <var>symbol</var> (see <a href="byte_002dcode-objects">Byte-Code Objects</a>). </p> <div class="example"> <pre class="example">(defun factorial (integer)
+  "Compute factorial of INTEGER."
+  (if (= 1 integer) 1
+    (* integer (factorial (1- integer)))))
+⇒ factorial
+</pre>
+
+<pre class="example">(byte-compile 'factorial)
+⇒
+#[(integer)
+  "^H\301U\203^H^@\301\207\302^H\303^HS!\"\207"
+  [integer 1 * factorial]
+  4 "Compute factorial of INTEGER."]
+</pre>
+</div> <p>If <var>symbol</var>’s definition is a byte-code function object, <code>byte-compile</code> does nothing and returns <code>nil</code>. It does not compile the symbol’s definition again, since the original (non-compiled) code has already been replaced in the symbol’s function cell by the byte-compiled code. </p> <p>The argument to <code>byte-compile</code> can also be a <code>lambda</code> expression. In that case, the function returns the corresponding compiled code but does not store it anywhere. </p>
+</dd>
+</dl> <dl> <dt id="compile-defun">Command: <strong>compile-defun</strong> <em>&amp;optional arg</em>
+</dt> <dd>
+<p>This command reads the defun containing point, compiles it, and evaluates the result. If you use this on a defun that is actually a function definition, the effect is to install a compiled version of that function. </p> <p><code>compile-defun</code> normally displays the result of evaluation in the echo area, but if <var>arg</var> is non-<code>nil</code>, it inserts the result in the current buffer after the form it has compiled. </p>
+</dd>
+</dl> <dl> <dt id="byte-compile-file">Command: <strong>byte-compile-file</strong> <em>filename</em>
+</dt> <dd>
+<p>This function compiles a file of Lisp code named <var>filename</var> into a file of byte-code. The output file’s name is made by changing the ‘<samp>.el</samp>’ suffix into ‘<samp>.elc</samp>’; if <var>filename</var> does not end in ‘<samp>.el</samp>’, it adds ‘<samp>.elc</samp>’ to the end of <var>filename</var>. </p> <p>Compilation works by reading the input file one form at a time. If it is a definition of a function or macro, the compiled function or macro definition is written out. Other forms are batched together, then each batch is compiled, and written so that its compiled code will be executed when the file is read. All comments are discarded when the input file is read. </p> <p>This command returns <code>t</code> if there were no errors and <code>nil</code> otherwise. When called interactively, it prompts for the file name. </p> <div class="example"> <pre class="example">$ ls -l push*
+-rw-r--r-- 1 lewis lewis 791 Oct  5 20:31 push.el
+</pre>
+
+<pre class="example">(byte-compile-file "~/emacs/push.el")
+     ⇒ t
+</pre>
+
+<pre class="example">$ ls -l push*
+-rw-r--r-- 1 lewis lewis 791 Oct  5 20:31 push.el
+-rw-rw-rw- 1 lewis lewis 638 Oct  8 20:25 push.elc
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="byte-recompile-directory">Command: <strong>byte-recompile-directory</strong> <em>directory &amp;optional flag force follow-symlinks</em>
+</dt> <dd>
+ <p>This command recompiles every ‘<samp>.el</samp>’ file in <var>directory</var> (or its subdirectories) that needs recompilation. A file needs recompilation if a ‘<samp>.elc</samp>’ file exists but is older than the ‘<samp>.el</samp>’ file. </p> <p>When a ‘<samp>.el</samp>’ file has no corresponding ‘<samp>.elc</samp>’ file, <var>flag</var> says what to do. If it is <code>nil</code>, this command ignores these files. If <var>flag</var> is 0, it compiles them. If it is neither <code>nil</code> nor 0, it asks the user whether to compile each such file, and asks about each subdirectory as well. </p> <p>Interactively, <code>byte-recompile-directory</code> prompts for <var>directory</var> and <var>flag</var> is the prefix argument. </p> <p>If <var>force</var> is non-<code>nil</code>, this command recompiles every ‘<samp>.el</samp>’ file that has a ‘<samp>.elc</samp>’ file. </p> <p>This command will normally not compile ‘<samp>.el</samp>’ files that are symlinked. If the optional <var>follow-symlink</var> parameter is non-<code>nil</code>, symlinked ‘<samp>.el</samp>’ will also be compiled. </p> <p>The returned value is unpredictable. </p>
+</dd>
+</dl> <dl> <dt id="batch-byte-compile">Function: <strong>batch-byte-compile</strong> <em>&amp;optional noforce</em>
+</dt> <dd>
+<p>This function runs <code>byte-compile-file</code> on files specified on the command line. This function must be used only in a batch execution of Emacs, as it kills Emacs on completion. An error in one file does not prevent processing of subsequent files, but no output file will be generated for it, and the Emacs process will terminate with a nonzero status code. </p> <p>If <var>noforce</var> is non-<code>nil</code>, this function does not recompile files that have an up-to-date ‘<samp>.elc</samp>’ file. </p> <div class="example"> <pre class="example">$ emacs -batch -f batch-byte-compile *.el
+</pre>
+</div> </dd>
+</dl><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 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/Compilation-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Compilation-Functions.html</a>
+  </p>
+</div>