elisp: Compilation Functions
16.2 Byte-Compilation Functions
===============================
You can byte-compile an individual function or macro definition with the
‘byte-compile’ function. You can compile a whole file with
‘byte-compile-file’, or several files with ‘byte-recompile-directory’ or
‘batch-byte-compile’.
Sometimes, the byte compiler produces warning and/or error messages
(
Compiler Errors, for details). These messages are normally
recorded in a buffer called ‘*Compile-Log*’, which uses Compilation
mode. (emacs)Compilation Mode. However, if the variable
‘byte-compile-debug’ is non-nil, error message will be signaled as Lisp
errors instead (Errors).
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 ‘require’ forms
which specify the files containing the needed macro definitions (
Named Features). Normally, the byte compiler does not evaluate the
code that it is compiling, but it handles ‘require’ forms specially, by
loading the specified libraries. To avoid loading the macro definition
files when someone _runs_ the compiled program, write
‘eval-when-compile’ around the ‘require’ calls (Eval During
Compile). For more details, Compiling Macros.
Inline (‘defsubst’) 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.
-- Function: byte-compile symbol
This function byte-compiles the function definition of SYMBOL,
replacing the previous definition with the compiled one. The
function definition of SYMBOL must be the actual code for the
function; ‘byte-compile’ does not handle function indirection. The
return value is the byte-code function object which is the compiled
definition of SYMBOL (Byte-Code Objects).
(defun factorial (integer)
"Compute factorial of INTEGER."
(if (= 1 integer) 1
(* integer (factorial (1- integer)))))
⇒ factorial
(byte-compile 'factorial)
⇒
#[(integer)
"^H\301U\203^H^@\301\207\302^H\303^HS!\"\207"
[integer 1 * factorial]
4 "Compute factorial of INTEGER."]
If SYMBOL’s definition is a byte-code function object,
‘byte-compile’ does nothing and returns ‘nil’. 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.
The argument to ‘byte-compile’ can also be a ‘lambda’ expression.
In that case, the function returns the corresponding compiled code
but does not store it anywhere.
-- Command: compile-defun &optional arg
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.
‘compile-defun’ normally displays the result of evaluation in the
echo area, but if ARG is non-‘nil’, it inserts the result in the
current buffer after the form it compiled.
-- Command: byte-compile-file filename &optional load
This function compiles a file of Lisp code named FILENAME into a
file of byte-code. The output file’s name is made by changing the
‘.el’ suffix into ‘.elc’; if FILENAME does not end in ‘.el’, it
adds ‘.elc’ to the end of FILENAME.
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.
This command returns ‘t’ if there were no errors and ‘nil’
otherwise. When called interactively, it prompts for the file
name.
If LOAD is non-‘nil’, this command loads the compiled file after
compiling it. Interactively, LOAD is the prefix argument.
$ ls -l push*
-rw-r--r-- 1 lewis lewis 791 Oct 5 20:31 push.el
(byte-compile-file "~/emacs/push.el")
⇒ t
$ 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
-- Command: byte-recompile-directory directory &optional flag force
This command recompiles every ‘.el’ file in DIRECTORY (or its
subdirectories) that needs recompilation. A file needs
recompilation if a ‘.elc’ file exists but is older than the ‘.el’
file.
When a ‘.el’ file has no corresponding ‘.elc’ file, FLAG says what
to do. If it is ‘nil’, this command ignores these files. If FLAG
is 0, it compiles them. If it is neither ‘nil’ nor 0, it asks the
user whether to compile each such file, and asks about each
subdirectory as well.
Interactively, ‘byte-recompile-directory’ prompts for DIRECTORY and
FLAG is the prefix argument.
If FORCE is non-‘nil’, this command recompiles every ‘.el’ file
that has a ‘.elc’ file.
The returned value is unpredictable.
-- Function: batch-byte-compile &optional noforce
This function runs ‘byte-compile-file’ 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.
If NOFORCE is non-‘nil’, this function does not recompile files
that have an up-to-date ‘.elc’ file.
$ emacs -batch -f batch-byte-compile *.el
Info Catalog
elisp: Speed of Byte-Code
elisp: Byte Compilation
elisp: Docs and Compilation