31.8 Libraries of Lisp Code for Emacs

Lisp code for Emacs editing commands is stored in files whose names conventionally end in .el. This ending tells Emacs to edit them in Emacs-Lisp mode (see Executing Lisp).

Emacs Lisp code can be compiled into byte-code, which loads faster, takes up less space, and executes faster. See Byte Compilation. By convention, the compiled code for a library goes in a separate file whose name ends in ‘.elc’. Thus, the compiled code for foo.el goes in foo.elc.

To execute a file of Emacs Lisp code, use M-x load-file. This command reads a file name using the minibuffer and then executes the contents of that file as Lisp code. It is not necessary to visit the file first; in any case, this command reads the file as found on disk, not text in an Emacs buffer.

Once a file of Lisp code is installed in the Emacs Lisp library directories, users can load it using M-x load-library. Programs can load it by calling load, a more primitive function that is similar but accepts some additional arguments.

M-x load-library differs from M-x load-file in that it searches a sequence of directories and tries three file names in each directory. Suppose your argument is lib; the three names are lib.elc, lib.el, and lastly just lib. If lib.elc exists, it is by convention the result of compiling lib.el; it is better to load the compiled file, since it will load and run faster.

If load-library finds that lib.el is newer than lib.elc file, it issues a warning, because it's likely that somebody made changes to the .el file and forgot to recompile it. Nonetheless, it loads lib.elc. This is because people often leave unfinished edits the source file, and don't recompile it until they think it is ready to use.

The variable load-path specifies the sequence of directories searched by M-x load-library. Its value should be a list of strings that are directory names; in addition, nil in this list stands for the current default directory. (Generally, it is not a good idea to put nil in the list; if you find yourself wishing that nil were in the list, most likely what you really want is to do M-x load-file this once.)

The default value of load-path is a list of directories where the Lisp code for Emacs itself is stored. If you have libraries of your own, put them in a single directory and add that directory to load-path, by adding a line like this to your init file (see Init File):

     (add-to-list 'load-path "/path/to/lisp/libraries")

Some commands are autoloaded: when you run them, Emacs will automatically load the associated library first. For instance, the compile and compilation-mode commands (see Compilation) are autoloaded; if you call either command, Emacs automatically loads the compile library. In contrast, the command recompile is not autoloaded, so it is unavailable until you load the compile library.

By default, Emacs refuses to load compiled Lisp files which were compiled with XEmacs, a modified versions of Emacs—they can cause Emacs to crash. Set the variable load-dangerous-libraries to t if you want to try loading them.