— 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 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 SXEmacs 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 init.el 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 SXEmacs startup.

Dumping SXEmacs 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 SXEmacs 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 SXEmacs 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.

— Function: locate-file filename path-list &optional suffixes mode

This function searches for a file in the same way that load does, and returns the file found (if any). (In fact, load uses this function to search through load-path.) It searches for filename through path-list, expanded by one of the optional suffixes (string of suffixes separated by ‘:’s), checking for access mode (0|1|2|4 = exists|executable|writable|readable), default readable.

locate-file keeps hash tables of the directories it searches through, in order to speed things up. It tries valiantly to not get confused in the face of a changing and unpredictable environment, but can occasionally get tripped up. In this case, you will have to call locate-file-clear-hashing to get it back on track. See that function for details.

— Function: locate-file-clear-hashing path

This function clears the hash records for the specified list of directories. locate-file uses a hashing scheme to speed lookup, and will correctly track the following environmental changes:

• changes of any sort to the list of directories to be searched.
• addition and deletion of non-shadowing files (see below) from the directories in the list.
• byte-compilation of a .el file into a .elc file.

locate-file will primarily get confused if you add a file that shadows (i.e. has the same name as) another file further down in the directory list. In this case, you must call locate-file-clear-hashing.

— Variable: load-in-progress

This variable is non-nil if SXEmacs 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.

— User Option: load-warn-when-source-newer

This variable specifies whether load should check whether the source is newer than the binary. If this variable is true, then when a ‘.elc’ file is being loaded and the corresponding ‘.el’ is newer, a warning message will be printed. The default is nil, but it is bound to t during the initial loadup.

— User Option: load-warn-when-source-only

This variable specifies whether load should warn when loading a ‘.el’ file instead of an ‘.elc’. If this variable is true, then when load is called with a filename without an extension, and the ‘.elc’ version doesn't exist but the ‘.el’ version does, then a message will be printed. If an explicit extension is passed to load, no warning will be printed. The default is nil, but it is bound to t during the initial loadup.

— User Option: load-ignore-elc-files

This variable specifies whether load should ignore ‘.elc’ files when a suffix is not given. This is normally used only to bootstrap the ‘.elc’ files when building SXEmacs, when you use the command ‘make all-elc’. (This forces the ‘.el’ versions to be loaded in the process of compiling those same files, so that existing out-of-date ‘.elc’ files do not make it mess things up.)