gnu.org (original) (raw)

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 namedfilename.elc, that is, for a file whose name isfilename with the extension ‘.elc’ appended. If such a file exists, and Emacs was compiled with native-compilation support (see Compilation of Lisp to Native Code), load attempts to find a corresponding ‘.eln’ file, and if found, loads it instead offilename.elc. Otherwise, it loadsfilename.elc (and starts a background native compilation to produce the missing ‘.eln’ file, followed by loading that file). If there is no filename.elc, then loadlooks for a file named filename.el. If that file exists, it is loaded. If Emacs was compiled with support for dynamic modules (see Emacs Dynamic Modules), load next looks for a file namedfilename.ext, where ext is a system-dependent file-name extension of shared libraries (‘.so’ on GNU and Unix systems). Finally, if neither of those names is found, loadlooks 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 namedfoo.el.el, evaluation of (load "foo.el") will indeed find it.)

If Auto Compression mode is enabled, as it is by default, then ifload can not find a file, it searches for a compressed version of the file before trying other file names. It decompresses and loads it if it exists. It looks for compressed versions by appending each of the suffixes in jka-compr-load-suffixes to the file name. The value of this variable must be a list of strings. Its standard value is (".gz").

If the optional argument nosuffix is non-nil, thenload does not try the suffixes ‘.elc’ and ‘.el’. In this case, you must specify the precise file name you want, except that, if Auto Compression mode is enabled, load will still usejka-compr-load-suffixes to find compressed versions. By specifying the precise file name and using t fornosuffix, you can prevent file names like foo.el.el from being tried.

If the optional argument must-suffix is non-nil, thenload insists that the file name used must end in either ‘.el’ or ‘.elc’ (possibly extended with a compression suffix) or the shared-library extension, unless it contains an explicit directory name.

If the option load-prefer-newer is non-nil, then when searching suffixes, load selects whichever version of a file (‘.elc’, ‘.el’, etc.) has been modified most recently. In this case, load doesn’t load the ‘.eln’ natively-compiled file even if it exists.

If filename is a relative file name, such as foo orbaz/foo.bar, load searches for the file using the variableload-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 inload-path, then all three suffixes in the second directory, and so on. See Library Search.

Whatever the name under which the file is eventually found, and the directory where Emacs found it, Emacs sets the value of the variableload-file-name to that file’s name.

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

When loading a source file (not compiled), load performs character set translation just as Emacs would do when visiting the file. See Coding Systems.

When loading an uncompiled file, Emacs tries to expand any macros that the file contains (see Macros). We refer to this as_eager macro expansion_. Doing this (rather than deferring the expansion until the relevant code runs) can significantly speed up the execution of uncompiled code. Sometimes, this macro expansion cannot be done, owing to a cyclic dependency. In the simplest example of this, the file you are loading refers to a macro defined in another file, and that file in turn requires the file you are loading. Emacs will issue an error about (‘Eager macro-expansion skipped due to cycle…’) giving details of the problem. You have to restructure your code so that this does not happen. Loading a compiled file does not cause macroexpansion, because this should already have happened during compilation. See Macros and Byte Compilation.

Messages like ‘Loading foo...’ and ‘Loading foo...done’ appear in the echo area during loading unless nomessage is non-nil. If a natively-compiled ‘.eln’ file is loaded, the message says so.

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 afile-error (with ‘Cannot open load filefilename’). But if missing-ok is non-nil, thenload 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.