SXEmacs 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 Autoload). require loads a
file if it isn’t already loaded (see Named Features). Ultimately, all
these facilities call the load function to do the work.
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.
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.
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.
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:
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.
This variable is non-nil if SXEmacs is in the process of loading a
file, and it is nil otherwise.
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.
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.
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.
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.)
To learn how load is used to build SXEmacs,
see Building SXEmacs.