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.