Loading a file of Lisp code means bringing its contents into the Lisp environment in the form of Lisp objects. Emacs finds and opens the file, reads the text, evaluates each form, and then closes the file.
The load functions evaluate all the expressions in a file just
as the eval-current-buffer function evaluates all the
expressions in a buffer. The difference is that the load functions
read and evaluate the text in the file as found on disk, not the text
in an Emacs buffer.
The loaded file must contain Lisp expressions, either as source code or as byte-compiled code. Each form in the file is called a top-level form. There is no special format for the forms in a loadable file; any form in a file may equally well be typed directly into a buffer and evaluated there. (Indeed, most code is tested this way.) Most often, the forms are function definitions and variable definitions.
A file containing Lisp code is often called a library. Thus, the "Rmail library" is a file containing code for Rmail mode. Similarly, a "Lisp library directory" is a directory of files containing Lisp code.
Emacs Lisp has several interfaces for loading. For example,
autoload creates a placeholder object for a function defined 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.
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. By specifying the precise
file name and using t for nosuffix, you can prevent
perverse file names such as `foo.el.el' from being tried.
If the optional argument must-suffix is non-nil, then
load insists that the file name used must end in either
`.el' or `.elc', unless it contains an explicit directory
name. If filename does not contain an explicit directory name,
and does not end in a suffix, then load insists on adding one.
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. See section Library Search.
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.
When loading a source file (not compiled), load performs
character set translation just as Emacs would do when visiting the file.
See section Coding Systems.
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.
load-path is not used, and suffixes are not appended. Use this
command if you wish to specify precisely the file name to load.
load, except in how it reads its argument interactively.
nil if Emacs is in the process of loading a
file, and it is nil otherwise.
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.
Note: Instead of using this variable, it is cleaner to use
another, newer feature: to pass the function as the read-function
argument to eval-region. See section Eval.
For information about how load is used in building Emacs, see
section Building Emacs.
When Emacs loads a Lisp library, it searches for the library
in a list of directories specified by the variable load-path.
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.
Then the list is expanded by adding subdirectories of the directories
in the list.
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/local/share/emacs/20.3/lisp
Here is how to set it using sh:
export EMACSLOADPATH EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/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.
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, includes two special directories (and
their subdirectories as well):
"/usr/local/share/emacs/version/site-lisp"
and
"/usr/local/share/emacs/site-lisp"
The first one is for locally installed packages for a particular Emacs version; the second is for locally installed packages meant for use with all installed Emacs versions.
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.
Emacs finds these directories' subdirectories and adds them to
load-path when it starts up. Both immediate subdirectories and
subdirectories multiple levels down are added to load-path.
Not all subdirectories are included, though. Subdirectories whose names do not start with a letter or digit are excluded. Subdirectories named `RCS' are excluded. Also, a subdirectory which contains a file named `.nosearch' is excluded. You can use these methods to prevent certain subdirectories of the `site-lisp' directories from being searched.
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.)
load does, and the
argument nosuffix has the same meaning as in load: don't
add suffixes `.elc' or `.el' to the specified name
library.
If the path is non-nil, that list of directories is used
instead of load-path.
When locate-library is called from a program, it returns the file
name as a string. When the user runs locate-library
interactively, the argument interactive-call is t, and this
tells locate-library to display the file name in the echo area.
When Emacs Lisp programs contain string constants with non-ASCII characters, these can be represented within Emacs either as unibyte strings or as multibyte strings (see section Text Representations). Which representation is used depends on how the file is read into Emacs. If it is read with decoding into multibyte representation, the text of the Lisp program will be multibyte text, and its string constants will be multibyte strings. If a file containing Latin-1 characters (for example) is read without decoding, the text of the program will be unibyte text, and its string constants will be unibyte strings. See section Coding Systems.
To make the results more predictable, Emacs always performs decoding into the multibyte representation when loading Lisp files, even if it was started with the `--unibyte' option. This means that string constants with non-ASCII characters translate into multibyte strings. The only exception is when a particular file specifies no decoding.
The reason Emacs is designed this way is so that Lisp programs give
predictable results, regardless of how Emacs was started. In addition,
this enables programs that depend on using multibyte text to work even
in a unibyte Emacs. Of course, such programs should be designed to
notice whether the user prefers unibyte or multibyte text, by checking
default-enable-multibyte-characters, and convert representations
appropriately.
In most Emacs Lisp programs, the fact that non-ASCII strings are multibyte strings should not be noticeable, since inserting them in unibyte buffers converts them to unibyte automatically. However, if this does make a difference, you can force a particular Lisp file to be interpreted as unibyte by writing `-*-unibyte: t;-*-' in a comment on the file's first line. With that designator, the file will be unconditionally be interpreted as unibyte, even in an ordinary multibyte Emacs session.
The autoload facility allows you to make a function or macro known in Lisp, but put off loading the file that defines it. The first call to the function automatically reads the proper file to install the real definition and other associated code, then runs the real definition as if it had been loaded all along.
There are two ways to set up an autoloaded function: by calling
autoload, and by writing a special "magic" comment in the
source before the real definition. autoload is the low-level
primitive for autoloading; any Lisp program can call autoload at
any time. Magic comments are the most convenient way to make a function
autoload, for packages installed along with Emacs. These comments do
nothing on their own, but they serve as a guide for the command
update-file-autoloads, which constructs calls to autoload
and arranges to execute them when Emacs is built.
If filename does not contain either a directory name, or the
suffix .el or .elc, then autoload insists on adding
one of these suffixes, and it will not load from a file whose name is
just filename with no added suffix.
The argument docstring is the documentation string for the
function. Normally, this should be identical to the documentation string
in the function definition itself. Specifying the documentation string
in the call to autoload makes it possible to look at the
documentation without loading the function's real definition.
If interactive is non-nil, that says function can be
called interactively. This lets completion in M-x work without
loading function's real definition. The complete interactive
specification is not given here; it's not needed unless the user
actually calls function, and when that happens, it's time to load
the real definition.
You can autoload macros and keymaps as well as ordinary functions.
Specify type as macro if function is really a macro.
Specify type as keymap if function is really a
keymap. Various parts of Emacs need to know this information without
loading the real definition.
An autoloaded keymap loads automatically during key lookup when a prefix
key's binding is the symbol function. Autoloading does not occur
for other kinds of access to the keymap. In particular, it does not
happen when a Lisp program gets the keymap from the value of a variable
and calls define-key; not even if the variable name is the same
symbol function.
If function already has a non-void function definition that is not
an autoload object, autoload does nothing and returns nil.
If the function cell of function is void, or is already an autoload
object, then it is defined as an autoload object like this:
(autoload filename docstring interactive type)
For example,
(symbol-function 'run-prolog)
=> (autoload "prolog" 169681 t nil)
In this case, "prolog" is the name of the file to load, 169681
refers to the documentation string in the
`emacs/etc/DOC-version' file (see section Documentation Basics),
t means the function is interactive, and nil that it is
not a macro or a keymap.
The autoloaded file usually contains other definitions and may require
or provide one or more features. If the file is not completely loaded
(due to an error in the evaluation of its contents), any function
definitions or provide calls that occurred during the load are
undone. This is to ensure that the next attempt to call any function
autoloading from this file will try again to load the file. If not for
this, then some of the functions in the file might be defined by the
aborted load, but fail to work properly for the lack of certain
subroutines not loaded successfully because they come later in the file.
If the autoloaded file fails to define the desired Lisp function or
macro, then an error is signaled with data "Autoloading failed to
define function function-name".
A magic autoload comment consists of `;;;###autoload', on a line
by itself, just before the real definition of the function in its
autoloadable source file. The command M-x update-file-autoloads
writes a corresponding autoload call into `loaddefs.el'.
Building Emacs loads `loaddefs.el' and thus calls autoload.
M-x update-directory-autoloads is even more powerful; it updates
autoloads for all files in the current directory.
The same magic comment can copy any kind of form into `loaddefs.el'. If the form following the magic comment is not a function definition, it is copied verbatim. You can also use a magic comment to execute a form at build time without executing it when the file itself is loaded. To do this, write the form on the same line as the magic comment. Since it is in a comment, it does nothing when you load the source file; but M-x update-file-autoloads copies it to `loaddefs.el', where it is executed while building Emacs.
The following example shows how doctor is prepared for
autoloading with a magic comment:
;;;###autoload (defun doctor () "Switch to *doctor* buffer and start giving psychotherapy." (interactive) (switch-to-buffer "*doctor*") (doctor-mode))
Here's what that produces in `loaddefs.el':
(autoload 'doctor "doctor" "\ Switch to *doctor* buffer and start giving psychotherapy." t)
The backslash and newline immediately following the double-quote are a
convention used only in the preloaded Lisp files such as
`loaddefs.el'; they tell make-docfile to put the
documentation string in the `etc/DOC' file. See section Building Emacs.
You can load a given file more than once in an Emacs session. For example, after you have rewritten and reinstalled a function definition by editing it in a buffer, you may wish to return to the original version; you can do this by reloading the file it came from.
When you load or reload files, bear in mind that the load and
load-library functions automatically load a byte-compiled file
rather than a non-compiled file of similar name. If you rewrite a file
that you intend to save and reinstall, you need to byte-compile the new
version; otherwise Emacs will load the older, byte-compiled file instead
of your newer, non-compiled file! If that happens, the message
displayed when loading the file includes, `(compiled; note, source is
newer)', to remind you to recompile it.
When writing the forms in a Lisp library file, keep in mind that the
file might be loaded more than once. For example, think about whether
each variable should be reinitialized when you reload the library;
defvar does not change the value if the variable is already
initialized. (See section Defining Global Variables.)
The simplest way to add an element to an alist is like this:
(setq minor-mode-alist
(cons '(leif-mode " Leif") minor-mode-alist))
But this would add multiple elements if the library is reloaded. To avoid the problem, write this:
(or (assq 'leif-mode minor-mode-alist)
(setq minor-mode-alist
(cons '(leif-mode " Leif") minor-mode-alist)))
To add an element to a list just once, you can also use add-to-list
(see section How to Alter a Variable Value).
Occasionally you will want to test explicitly whether a library has already been loaded. Here's one way to test, in a library, whether it has been loaded before:
(defvar foo-was-loaded nil) (unless foo-was-loaded execute-first-time-only (setq foo-was-loaded t))
If the library uses provide to provide a named feature, you can
use featurep earlier in the file to test whether the
provide call has been executed before.
provide and require are an alternative to
autoload for loading files automatically. They work in terms of
named features. Autoloading is triggered by calling a specific
function, but a feature is loaded the first time another program asks
for it by name.
A feature name is a symbol that stands for a collection of functions, variables, etc. The file that defines them should provide the feature. Another program that uses them may ensure they are defined by requiring the feature. This loads the file of definitions if it hasn't been loaded already.
To require the presence of a feature, call require with the
feature name as argument. require looks in the global variable
features to see whether the desired feature has been provided
already. If not, it loads the feature from the appropriate file. This
file should call provide at the top level to add the feature to
features; if it fails to do so, require signals an error.
For example, in `emacs/lisp/prolog.el',
the definition for run-prolog includes the following code:
(defun run-prolog () "Run an inferior Prolog process, with I/O via buffer *prolog*." (interactive) (require 'comint) (switch-to-buffer (make-comint "prolog" prolog-program-name)) (inferior-prolog-mode))
The expression (require 'comint) loads the file `comint.el'
if it has not yet been loaded. This ensures that make-comint is
defined. Features are normally named after the files that provide them,
so that require need not be given the file name.
The `comint.el' file contains the following top-level expression:
(provide 'comint)
This adds comint to the global features list, so that
(require 'comint) will henceforth know that nothing needs to be
done.
When require is used at top level in a file, it takes effect
when you byte-compile that file (see section Byte Compilation) as well as
when you load it. This is in case the required package contains macros
that the byte compiler must know about.
Although top-level calls to require are evaluated during
byte compilation, provide calls are not. Therefore, you can
ensure that a file of definitions is loaded before it is byte-compiled
by including a provide followed by a require for the same
feature, as in the following example.
(provide 'my-feature) ; Ignored by byte compiler,
; evaluated by load.
(require 'my-feature) ; Evaluated by byte compiler.
The compiler ignores the provide, then processes the
require by loading the file in question. Loading the file does
execute the provide call, so the subsequent require call
does nothing when the file is loaded.
The direct effect of calling provide is to add feature to
the front of the list features if it is not already in the list.
The argument feature must be a symbol. provide returns
feature.
features
=> (bar bish)
(provide 'foo)
=> foo
features
=> (foo bar bish)
When a file is loaded to satisfy an autoload, and it stops due to an
error in the evaluating its contents, any function definitions or
provide calls that occurred during the load are undone.
See section Autoload.
(featurep feature); see below). The
argument feature must be a symbol.
If the feature is not present, then require loads filename
with load. If filename is not supplied, then the name of
the symbol feature is used as the base file name to load.
However, in this case, require insists on finding feature
with an added suffix; a file whose name is just feature won't be
used.
If loading the file fails to provide feature, require
signals an error, `Required feature feature was not
provided'.
t if feature has been provided in the
current Emacs session (i.e., if feature is a member of
features.)
provide. The order of the elements in the
features list is not significant.
You can discard the functions and variables loaded by a library to
reclaim memory for other Lisp objects. To do this, use the function
unload-feature:
defun, defalias, defsubst,
defmacro, defconst, defvar, and defcustom.
It then restores any autoloads formerly associated with those symbols.
(Loading saves these in the autoload property of the symbol.)
Before restoring the previous definitions, unload-feature runs
remove-hook to remove functions in the library from certain
hooks. These hooks include variables whose names end in `hook' or
`-hooks', plus those listed in loadhist-special-hooks. This
is to prevent Emacs from ceasing to function because important hooks
refer to functions that are no longer defined.
If these measures are not sufficient to prevent malfunction, a library
can define an explicit unload hook. If feature-unload-hook
is defined, it is run as a normal hook before restoring the previous
definitions, instead of the usual hook-removing actions. The
unload hook ought to undo all the global state changes made by the
library that might cease to work once the library is unloaded.
Ordinarily, unload-feature refuses to unload a library on which
other loaded libraries depend. (A library a depends on library
b if a contains a require for b.) If the
optional argument force is non-nil, dependencies are
ignored and you can unload any library.
The unload-feature function is written in Lisp; its actions are
based on the variable load-history.
Each element is a list and describes one library. The CAR of the list is the name of the library, as a string. The rest of the list is composed of these kinds of objects:
(require . feature) indicating
features that were required.
(provide . feature) indicating
features that were provided.
The value of load-history may have one element whose CAR is
nil. This element describes definitions made with
eval-buffer on a buffer that is not visiting a file.
The command eval-region updates load-history, but does so
by adding the symbols defined to the element for the file being visited,
rather than replacing that element. See section Eval.
Preloaded libraries don't contribute to load-history.
You can ask for code to be executed if and when a particular library is
loaded, by calling eval-after-load.
The library name library must exactly match the argument of
load. To get the proper results when an installed library is
found by searching load-path, you should not include any
directory names in library.
An error in form does not undo the load, but does prevent execution of the rest of form.
In general, well-designed Lisp programs should not use this feature.
The clean and modular ways to interact with a Lisp library are (1)
examine and set the library's variables (those which are meant for
outside use), and (2) call the library's functions. If you wish to
do (1), you can do it immediately--there is no need to wait for when
the library is loaded. To do (2), you must load the library (preferably
with require).
But it is OK to use eval-after-load in your personal
customizations if you don't feel they must meet the design standards for
programs meant for wider use.
(filename forms...)
The function load checks after-load-alist in order to
implement eval-after-load.
Go to the first, previous, next, last section, table of contents.