22.3.2 Compiling Libraries

Emacs Lisp code can be compiled into byte-code which loads faster, takes up less space when loaded, and executes faster.

M-x batch-byte-compile

Run byte-compile-file on the files remaining on the command line.

M-x byte-compile-buffer &optional buffer

Byte-compile and evaluate contents of buffer (default is current buffer).

M-x byte-compile-file

Compile a file of Lisp code named filename into a file of byte code.

M-x byte-compile-and-load-file filename

Compile a file of Lisp code named filename into a file of byte code and load it.

M-x byte-recompile-directory directory

Recompile every .el file in directory that needs recompilation.

M-x disassemble

Print disassembled code for object on (optional) stream.

M-x make-obsolete function new

Make the byte-compiler warn that function is obsolete and new should be used instead.

byte-compile-file creates a byte-code compiled file from an Emacs-Lisp source file. The default argument for this function is the file visited in the current buffer. The function reads the specified file, compiles it into byte code, and writes an output file whose name is made by appending c to the input file name. Thus, the file rmail.el would be compiled into rmail.elc. To compile a file of Lisp code named filename into a file of byte code and then load it, use byte-compile-and-load-file. To compile and evaluate Lisp code in a given buffer, use byte-compile-buffer.

To recompile all changed Lisp files in a directory, use M-x byte-recompile-directory. Specify just the directory name as an argument. Each .el file that has been byte-compiled before is byte-compiled again if it has changed since the previous compilation. A numeric argument to this command tells it to offer to compile each .el file that has not been compiled yet. You must answer y or n to each offer.

You can use the function batch-byte-compile to invoke Emacs non-interactively from the shell to do byte compilation. When you use this function, the files to be compiled are specified with command-line arguments. Use a shell command of the form:

emacs -batch -f batch-byte-compile files...

Directory names may also be given as arguments; in that case, byte-recompile-directory is invoked on each such directory. batch-byte-compile uses all remaining command-line arguments as file or directory names, then kills the Emacs process.

M-x disassemble explains the result of byte compilation. Its argument is a function name. It displays the byte-compiled code in a help window in symbolic form, one instruction per line. If the instruction refers to a variable or constant, that is shown, too.