22.3.1 Loading Libraries

M-x load-file file

Load the file file of Lisp code.

M-x load-library library

Load the library named library.

M-x locate-library library &optional nosuffix

Show the full path name of Emacs library library.

To execute a file of Emacs Lisp, use M-x load-file. This command reads the file name you provide in the minibuffer, then executes the contents of that file as Lisp code. It is not necessary to visit the file first; in fact, this command reads the file as found on disk, not the 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-library, or with 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. The three names are: first, the specified name with .elc appended; second, the name with .el appended; third, the specified name alone. A .elc file would be the result of compiling the Lisp file into byte code; if possible, it is loaded in preference to the Lisp file itself because the compiled file loads and runs faster.

Because the argument to load-library is usually not in itself a valid file name, file name completion is not available. In fact, when using this command, you usually do not know exactly what file name will be used.

The sequence of directories searched by M-x load-library is specified by the variable load-path, a list of strings that are directory names. The elements of this list may not begin with "‘~’", so you must call expand-file-name on them before adding them to the list. The default value of the list contains the directory 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. nil in this list stands for the current default directory, but it is probably not a good idea to put nil in the list. If you start wishing that nil were in the list, you should probably use M-x load-file for this case.

The variable is initialized by the EMACSLOADPATH environment variable. If no value is specified, the variable takes the default value specified in the file paths.h when Emacs was built. If a path isn’t specified in paths.h, a default value is obtained from the file system, near the directory in which the Emacs executable resides.

Like M-x load-library, M-x locate-library searches the directories in load-path to find the file that M-x load-library would load. If the optional second argument nosuffix is non-nil, the suffixes .elc or .el are not added to the specified name library (like calling load instead of load-library).

You often do not have to give any command to load a library, because the commands defined in the library are set up to autoload that library. Running any of those commands causes load to be called to load the library; this replaces the autoload definitions with the real ones from the library.

If autoloading a file does not finish, either because of an error or because of a C-g quit, all function definitions made by the file are undone automatically. So are any calls to provide. As a consequence, the entire file is loaded a second time if you use one of the autoloadable commands again. This prevents problems when the command is no longer autoloading but is working incorrectly because the file was only partially loaded. Function definitions are undone only for autoloading; explicit calls to load do not undo anything if loading is not completed.

The variable after-load-alist takes an alist of expressions to be evaluated when particular files are loaded. Each element has the form (filename forms...). When load is run and the filename argument is filename, the forms in the corresponding element are executed at the end of loading.

filename must match exactly. Normally filename is the name of a library, with no directory specified, since that is how load is normally called. An error in forms does not undo the load, but it does prevent execution of the rest of the forms.