Go to the previous, next section.
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.
When you run the byte compiler, you may get warnings in a buffer called `*Compile-Log*'. These report usage in your program that suggest a problem, but are not necessarily erroneous.
Be careful when byte-compiling code that uses macros. Macro calls are expanded when they are compiled, so the macros must already be defined for proper compilation. For more details, see section Macros and Byte Compilation.
While byte-compiling a file, any require calls at top-level are
executed. One way to ensure that necessary macro definitions are
available during compilation is to require the file that defines them.
See section Features.
A byte-compiled function is not as efficient as a primitive function written in C, but runs much faster than the version written in Lisp. For a rough comparison, consider the example below:
(defun silly-loop (n)
"Return time before and after N iterations of a loop."
(let ((t1 (current-time-string)))
(while (> (setq n (1- n))
0))
(list t1 (current-time-string))))
=> silly-loop
(silly-loop 100000)
=> ("Thu Jan 12 20:18:38 1989"
"Thu Jan 12 20:19:29 1989") ; 51 seconds
(byte-compile 'silly-loop)
=> [Compiled code not shown]
(silly-loop 100000)
=> ("Thu Jan 12 20:21:04 1989"
"Thu Jan 12 20:21:17 1989") ; 13 seconds
In this example, the interpreted code required 51 seconds to run, whereas the byte-compiled code required 13 seconds. These results are representative, but actual results will vary greatly.
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;
i.e., the compiler does not follow indirection to another symbol.
byte-compile does not compile macros. byte-compile
returns the new, compiled definition of symbol.
(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."]
The result is a compiled function object. The string it contains is the actual byte-code; each character in it is an instruction. The vector contains all the constants, variable names and function names used by the function, except for certain primitives that are coded as special instructions.
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.
Command: byte-compile-file filename
This function compiles a file of Lisp code named filename into a file of byte-code. The output file's name is made by appending `c' 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. When called interactively, it prompts
for the file name.
% ls -l push*
-rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
(byte-compile-file "~/emacs/push.el")
=> t
% ls -l push*
-rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
-rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc
Command: byte-recompile-directory directory flag
This function recompiles every `.el' file in directory that needs recompilation. A file needs recompilation if a `.elc' file exists but is older than the `.el' file.
If a `.el' file exists, but there is no corresponding `.elc'
file, then flag is examined. If it is nil, the file is
ignored. If it is non-nil, the user is asked whether the file
should be compiled.
The returned value of this command is unpredictable.
This function runs byte-compile-file on the files remaining 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. (The file which gets the
error will not, of course, produce any compiled code.)
% emacs -batch -f batch-byte-compile *.el
Function: byte-code code-string data-vector max-stack
This function actually interprets byte-code. A byte-compiled function
is actually defined with a body that calls byte-code. Don't call
this function yourself. Only the byte compiler knows how to generate
valid calls to this function.
In newer Emacs versions (19 and up), byte-code is usually executed as
part of a compiled function object, and only rarely as part of a call to
byte-code.
Go to the previous, next section.