16.2 The 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.

The byte compiler produces error messages and warnings about each file in a buffer called `*Compile-Log*'. These report things in your program that suggest a problem but are not necessarily erroneous.

Be careful when writing macro calls in files that you may someday byte-compile. Macro calls are expanded when they are compiled, so the macros must already be defined for proper compilation. For more details, see 13.3 Macros and Byte Compilation. If a program does not work the same way when compiled as it does when interpreted, erroneous macro definitions are one likely cause (see section 13.6 Common Problems Using Macros).

Normally, compiling a file does not evaluate the file's contents or load the file. But it does execute any require calls at top level in the file. One way to ensure that necessary macro definitions are available during compilation is to require the file that defines them (see section 15.6 Features). To avoid loading the macro definition files when someone runs the compiled program, write eval-when-compile around the require calls (see section 16.5 Evaluation During Compilation).

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; i.e., the compiler does not follow indirection to another symbol. byte-compile returns the new, compiled definition of symbol.

If symbol's definition is a byte-code function object, byte-compile does nothing and returns nil. Lisp records only one function definition for any symbol, and if that is already compiled, non-compiled code is not available anywhere. So there is no way to "compile the same definition again."

(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 byte-code function object. The string it contains is the actual byte-code; each character in it is an instruction or an operand of 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.

Command: compile-defun

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 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. 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.

When a `.el' file has no corresponding `.elc' file, flag says what to do. If it is nil, these files are ignored. If it is non-nil, the user is asked whether to compile each such file.

The returned value of this command is unpredictable.

Function: batch-byte-compile

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.

% 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 Emacs version 18, byte-code was always executed by way of a call to the function byte-code. Nowadays, byte-code is usually executed as part of a byte-code function object, and only rarely through an explicit call to byte-code.