How Programs Do Loading

Emacs Lisp has several interfaces for loading. For example, autoload creates a placeholder object for a function in a file; trying to call the autoloading function loads the file to get the function's real definition (see section Autoload). require loads a file if it isn't already loaded (see section Features). Ultimately, all these facilities call the load function to do the work.

Function: load filename &optional missing-ok nomessage nosuffix

This function finds and opens a file of Lisp code, evaluates all the forms in it, and closes the file.

To find the file, load first looks for a file named `filename.elc', that is, for a file whose name is filename with `.elc' appended. If such a file exists, it is loaded. If there is no file by that name, then load looks for a file named `filename.el'. If that file exists, it is loaded. Finally, if neither of those names is found, load looks for a file named filename with nothing appended, and loads it if it exists. (The load function is not clever about looking at filename. In the perverse case of a file named `foo.el.el', evaluation of (load "foo.el") will indeed find it.)

If the optional argument nosuffix is non-nil, then the suffixes `.elc' and `.el' are not tried. In this case, you must specify the precise file name you want.

If filename is a relative file name, such as `foo' or `baz/foo.bar', load searches for the file using the variable load-path. It appends filename to each of the directories listed in load-path, and loads the first file it finds whose name matches. The current default directory is tried only if it is specified in load-path, where nil stands for the default directory. load tries all three possible suffixes in the first directory in load-path, then all three suffixes in the second directory, and so on.

If you get a warning that `foo.elc' is older than `foo.el', it means you should consider recompiling `foo.el'. See section Byte Compilation.

Messages like `Loading foo...' and `Loading foo...done' appear in the echo area during loading unless nomessage is non-nil.

Any unhandled errors while loading a file terminate loading. If the load was done for the sake of autoload, any function definitions made during the loading are undone.

If load can't find the file to load, then normally it signals the error file-error (with `Cannot open load file filename'). But if missing-ok is non-nil, then load just returns nil.

You can use the variable load-read-function to specify a function for load to use instead of read for reading expressions. See below.

load returns t if the file loads successfully.

User Option: load-path

The value of this variable is a list of directories to search when loading files with load. Each element is a string (which must be a directory name) or nil (which stands for the current working directory). The value of load-path is initialized from the environment variable EMACSLOADPATH, if that exists; otherwise its default value is specified in `emacs/src/paths.h' when Emacs is built.

The syntax of EMACSLOADPATH is the same as used for PATH; `:' (or `;', according to the operating system) separates directory names, and `.' is used for the current default directory. Here is an example of how to set your EMACSLOADPATH variable from a csh `.login' file:

setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp

Here is how to set it using sh:

export EMACSLOADPATH
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp

Here is an example of code you can place in a `.emacs' file to add several directories to the front of your default load-path:

(setq load-path
      (append (list nil "/user/bil/emacs"
                    "/usr/local/lisplib"
                    "~/emacs")
              load-path))

In this example, the path searches the current working directory first, followed then by the `/user/bil/emacs' directory, the `/usr/local/lisplib' directory, and the `~/emacs' directory, which are then followed by the standard directories for Lisp code.

The command line options `-l' or `-load' specify a Lisp library to load as part of Emacs startup. Since this file might be in the current directory, Emacs 18 temporarily adds the current directory to the front of load-path so the file can be found there. Newer Emacs versions also find such files in the current directory, but without altering load-path.

Dumping Emacs uses a special value of load-path. If the value of load-path at the end of dumping is unchanged (that is, still the same special value), the dumped Emacs switches to the ordinary load-path value when it starts up, as described above. But if load-path has any other value at the end of dumping, that value is used for execution of the dumped Emacs also.

Therefore, if you want to change load-path temporarily for loading a few libraries in `site-init.el' or `site-load.el', you should bind load-path locally with let around the calls to load.

The default value of load-path, when running an Emacs which has been installed on the system, looks like this:

("/usr/local/share/emacs/version/site-lisp"
 "/usr/local/share/emacs/site-lisp"
 "/usr/local/share/emacs/version/lisp")

The last of these three directories is where the Lisp files of Emacs itself are installed; the first two are for additional Lisp packages installed at your site. The first directory is for locally installed packages that belong with a particular Emacs version; the second is for locally installed packages that can be used with any installed Emacs version.

There are several reasons why a Lisp package that works well in one Emacs version can cause trouble in another. Sometimes packages need updating for incompatible changes in Emacs; sometimes they depend on undocumented internal Emacs data that can change without notice; sometimes a newer Emacs version incorporates a version of the package, and should be used only with that version.

If you run Emacs from the directory where it was built--that is, an executable that has not been formally installed--then load-path normally contains two additional directories. These are the lisp and site-lisp subdirectories of the main build directory. (Both are represented as absolute file names.)

Variable: load-in-progress

This variable is non-nil if Emacs is in the process of loading a file, and it is nil otherwise.

Variable: load-read-function

This variable specifies an alternate expression-reading function for load and eval-region to use instead of read. The function should accept one argument, just as read does.

Normally, the variable's value is nil, which means those functions should use read.

To learn how load is used to build Emacs, see section Building Emacs.

Go to the first, previous, next, last section, table of contents.