[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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, optionally, 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.
1.1 How Programs Do Loading | The load function and others.
| |
1.2 Autoload | Setting up a function to autoload. | |
1.3 Repeated Loading | Precautions about loading a file twice. | |
1.4 Features | Loading a library if it isn’t already loaded. | |
1.5 Unloading | How to “unload” a library that was loaded. | |
1.6 Hooks for Loading | Providing code to be run when particular libraries are loaded. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are several interface functions for loading. For example, the
autoload
function creates a Lisp object that loads a file when it
is evaluated (see section Autoload). require
also causes files to be
loaded (see section 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 has
‘.elc’ appended. If such a file exists, it is loaded. But if
there is no file by that name, then load
looks for a file whose
name has ‘.el’ appended. If that file exists, it is loaded.
Finally, if there is no file by either name, 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 it is represented as nil
.
All three possible suffixes are tried in the first directory in
load-path
, then all three in the second directory in
load-path
, etc.
If you get a warning that ‘foo.elc’ is older than ‘foo.el’, it means you should consider recompiling ‘foo.el’. @xref{Byte Compilation}.
Messages like ‘Loading foo...’ and ‘Loading foo...done’ appear
in the echo area during loading unless nomessage is
non-nil
.
Any errors that are encountered while loading a file cause load
to abort. If the load was done for the sake of autoload
, certain
kinds of top-level forms, those which define functions, are undone.
The error file-error
is signaled (with ‘Cannot open load
file filename’) if no file is found. No error is signaled if
missing-ok is non-nil
—then load
just returns
nil
.
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 it exists; otherwise it is
set to the default specified in ‘emacs/src/paths.h’ when Emacs is
built.
The syntax of EMACSLOADPATH
is the same as that of PATH
;
fields are separated by ‘:’, 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/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 ‘.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") load-path))
In this example, the path searches the current working directory first, followed then by the ‘/user/bil/emacs’ directory and then by the ‘/usr/local/lisplib’ directory, which are then followed by the standard directories for Lisp code.
When Emacs version 18 processes command options ‘-l’ or
‘-load’ which specify Lisp libraries to be loaded, it temporarily
adds the current directory to the front of load-path
so that
files in the current directory can be specified easily. Newer Emacs
versions also find such files in the current directory, but without
altering load-path
.
This variable is non-nil
if Emacs is in the process of loading a
file, and it is nil
otherwise. This is how defun
and
provide
determine whether a load is in progress, so that their
effect can be undone if the load fails.
To learn how load
is used to build Emacs, see @ref{Building Emacs}.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The autoload facility allows you to make a function or macro available but put off loading its actual definition. An attempt to call a symbol whose definition is an autoload object automatically reads the file to install the real definition and its other associated code, and then calls the real definition.
To prepare a function or macro for autoloading, you must call
autoload
, specifying the function name and the name of the file
to be loaded. A file such as ‘emacs/lisp/loaddefs.el’ usually does
this when Emacs is first built.
The following example shows how doctor
is prepared for
autoloading 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 cause the documentation string to be put in the ‘etc/DOC’ file. (@xref{Building Emacs}.) In any other source file, you would write just this:
(autoload 'doctor "doctor" "Switch to *doctor* buffer and start giving psychotherapy." t)
Calling autoload
creates an autoload object containing the name
of the file and some other information, and makes this the function
definition of the specified symbol. When you later try to call that
symbol as a function or macro, the file is loaded; the loading should
redefine that symbol with its proper definition. After the file
completes loading, the function or macro is called as if it had been
there originally.
If, at the end of loading the file, the desired Lisp function or macro
has not been defined, then the error error
is signaled (with data
"Autoloading failed to define function function-name"
).
The autoloaded file may, of course, contain 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 the 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 appear defined, but
they may fail to work properly for the lack of certain subroutines
defined later in the file and not loaded successfully.
Emacs as distributed comes with many autoloaded functions.
The calls to autoload
are in the file ‘loaddefs.el’.
There is a convenient way of updating them automatically.
Write ‘;;;###autoload’ on a line by itself before a function
definition before the real definition of the function, in its
autoloadable source file; then the command M-x
update-file-autoloads automatically puts the autoload
call into
‘loaddefs.el’. M-x update-directory-autoloads is more
powerful; it updates autoloads for all files in the current directory.
You can also put other kinds of forms into ‘loaddefs.el’, by writing ‘;;;###autoload’ followed on the same line by the form. M-x update-file-autoloads copies the form from that line.
The commands for updating autoloads work by visiting and editing the file ‘loaddefs.el’. To make the result take effect, you must save that file’s buffer.
This function defines the function (or macro) named symbol so as
to load automatically from filename. The string filename is
a file name which will be passed to load
when the function is
called.
The argument docstring is the documentation string for the function. Normally, this is the same string that is in the function definition itself. This makes it possible to look at the documentation without loading the real definition.
If interactive is non-nil
, then the function can be
called interactively. This lets completion in M-x work without
loading the function’s real definition. The complete interactive
specification need not be given here. If type is macro
,
then the function is really a macro. If type is keymap
,
then the function is really a keymap.
If symbol already has a non-nil
function definition that
is not an autoload object, autoload
does nothing and returns
nil
. If the function cell of symbol is void, or is already
an autoload object, then it is set to an autoload object that looks 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’
file (@pxref{Documentation Basics}), t
means the function is
interactive, and nil
that it is not a macro.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You may load a 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 in which it is located.
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, remember to byte-compile it if
necessary; otherwise you may find yourself inadvertently reloading the
older, byte-compiled file instead of your newer, non-compiled file!
When writing the forms in a library, keep in mind that the library
might be loaded more than once. For example, the choice of
defvar
vs. defconst
for defining a variable depends on
whether it is desirable to reinitialize the variable if the library is
reloaded: defconst
does so, and defvar
does not.
(@xref{Defining 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)))
Occasionally you will want to test explicitly whether a library has already been loaded; you can do so as follows:
(if (not (boundp 'foo-was-loaded)) execute-first-time-only) (setq foo-was-loaded t)
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
The use of named features simplifies the task of determining whether required definitions have been defined. A feature name is a symbol that stands for a collection of functions, variables, etc. A program that needs the collection may ensure that they are defined by requiring the feature. If the file that contains the feature has not yet been loaded, then it will be loaded (or an error will be signaled if it cannot be loaded). The file thus loaded must provide the required feature or an error will be signaled.
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
.
Features are normally named after the files they are provided in
so that require
need not be given the file name.
For example, in ‘emacs/lisp/prolog.el’,
the definition for run-prolog
includes the following code:
(defun run-prolog () "Run an inferior Prolog process,\ input and output via buffer *prolog*." (interactive) (require 'comint) (switch-to-buffer (make-comint "prolog" prolog-program-name)) (inferior-prolog-mode))
The expression (require 'shell)
loads the file ‘shell.el’ if
it has not yet been loaded. This ensures that make-shell
is
defined.
The ‘shell.el’ file contains the following top-level expression:
(provide 'shell)
This adds shell
to the global features
list when the
‘shell’ file is loaded, so that (require 'shell)
will
henceforth know that nothing needs to be done.
When require
is used at top-level in a file, it takes effect if
you byte-compile that file (@pxref{Byte Compilation}). 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.
This function announces that feature is now loaded, or being loaded, into the current Emacs session. This means that the facilities associated with feature are or will be available for other Lisp programs.
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)
During autoloading, if the file is not completely loaded (due to an
error in the evaluation of the contents) any function definitions or
provide
calls that occurred during the load are undone.
See section Autoload.
This function checks whether feature is present in the current
Emacs session (using (featurep feature)
; see below). If it
is not, then require
loads filename with load
. If
filename is not supplied, then the name of the symbol
feature is used as the file name to load.
If feature is not provided after the file has been loaded, Emacs
will signal the error error
(with data ‘Required feature
feature was not provided’).
This function returns t
if feature has been provided in the
current Emacs session (i.e., feature is a member of
features
.)
The value of this variable is a list of symbols that are the features
loaded in the current Emacs session. Each symbol was put in this list
with a call to provide
. The order of the elements in the
features
list is not significant.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
:
This command unloads the library that provided feature feature.
It undefines all functions and variables defined with defvar
,
defmacro
, defconst
, defsubst
and
defalias
by the library which provided feature
feature. It then restores any autoloads associated with those
symbols.
The unload-feature
function is written in Lisp; its actions are
based on the variable load-history
.
This variable’s value is an alist connecting library names with the names of functions and variables they define, the features they provide, and the features they require.
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 the
features that are required.
(provide . feature)
indicating the
features that are 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.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can ask for code to be executed if and when a particular library is
loaded, by calling eval-after-load
.
This function arranges to evaluate form at the end of loading the library library, if and when library is loaded.
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.
An alist of expressions to evaluate if and when particular libraries are loaded. Each element looks like this:
(filename forms…)
The function load
checks after-load-alist
in order to
implement eval-after-load
.
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on January 16, 2023 using texi2html 5.0.
The buttons in the navigation panels have the following meaning:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
[ < ] | Back | Previous section in reading order | 1.2.2 |
[ Up ] | Up | Up section | 1.2 |
[ > ] | Forward | Next section in reading order | 1.2.4 |
[ >> ] | FastForward | Next chapter | 2 |
[Top] | Top | Cover (top) of document | |
[Contents] | Contents | Table of contents | |
[Index] | Index | Index | |
[ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on January 16, 2023 using texi2html 5.0.