mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-15 09:47:20 +00:00
821 lines
34 KiB
Plaintext
821 lines
34 KiB
Plaintext
@c -*-texinfo-*-
|
|
@c This is part of the GNU Emacs Lisp Reference Manual.
|
|
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
|
|
@c Free Software Foundation, Inc.
|
|
@c See the file elisp.texi for copying conditions.
|
|
@setfilename ../info/loading
|
|
@node Loading, Byte Compilation, Customization, Top
|
|
@chapter Loading
|
|
@cindex loading
|
|
@cindex library
|
|
@cindex Lisp library
|
|
|
|
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 @code{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.
|
|
|
|
@cindex top-level form
|
|
The loaded file must contain Lisp expressions, either as source code
|
|
or as byte-compiled code. Each form in the file is called a
|
|
@dfn{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 @dfn{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.
|
|
|
|
@menu
|
|
* How Programs Do Loading:: The @code{load} function and others.
|
|
* Library Search:: Finding a library to load.
|
|
* Loading Non-ASCII:: Non-@sc{ascii} characters in Emacs Lisp files.
|
|
* Autoload:: Setting up a function to autoload.
|
|
* Repeated Loading:: Precautions about loading a file twice.
|
|
* Named Features:: Loading a library if it isn't already loaded.
|
|
* Unloading:: How to ``unload'' a library that was loaded.
|
|
* Hooks for Loading:: Providing code to be run when
|
|
particular libraries are loaded.
|
|
@end menu
|
|
|
|
@node How Programs Do Loading
|
|
@section How Programs Do Loading
|
|
|
|
Emacs Lisp has several interfaces for loading. For example,
|
|
@code{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 (@pxref{Autoload}). @code{require} loads a
|
|
file if it isn't already loaded (@pxref{Named Features}). Ultimately,
|
|
all these facilities call the @code{load} function to do the work.
|
|
|
|
@defun load filename &optional missing-ok nomessage nosuffix must-suffix
|
|
This function finds and opens a file of Lisp code, evaluates all the
|
|
forms in it, and closes the file.
|
|
|
|
To find the file, @code{load} first looks for a file named
|
|
@file{@var{filename}.elc}, that is, for a file whose name is
|
|
@var{filename} with @samp{.elc} appended. If such a file exists, it is
|
|
loaded. If there is no file by that name, then @code{load} looks for a
|
|
file named @file{@var{filename}.el}. If that file exists, it is loaded.
|
|
Finally, if neither of those names is found, @code{load} looks for a
|
|
file named @var{filename} with nothing appended, and loads it if it
|
|
exists. (The @code{load} function is not clever about looking at
|
|
@var{filename}. In the perverse case of a file named @file{foo.el.el},
|
|
evaluation of @code{(load "foo.el")} will indeed find it.)
|
|
|
|
If the optional argument @var{nosuffix} is non-@code{nil}, then the
|
|
suffixes @samp{.elc} and @samp{.el} are not tried. In this case, you
|
|
must specify the precise file name you want. By specifying the precise
|
|
file name and using @code{t} for @var{nosuffix}, you can prevent
|
|
perverse file names such as @file{foo.el.el} from being tried.
|
|
|
|
If the optional argument @var{must-suffix} is non-@code{nil}, then
|
|
@code{load} insists that the file name used must end in either
|
|
@samp{.el} or @samp{.elc}, unless it contains an explicit directory
|
|
name. If @var{filename} does not contain an explicit directory name,
|
|
and does not end in a suffix, then @code{load} insists on adding one.
|
|
|
|
If @var{filename} is a relative file name, such as @file{foo} or
|
|
@file{baz/foo.bar}, @code{load} searches for the file using the variable
|
|
@code{load-path}. It appends @var{filename} to each of the directories
|
|
listed in @code{load-path}, and loads the first file it finds whose name
|
|
matches. The current default directory is tried only if it is specified
|
|
in @code{load-path}, where @code{nil} stands for the default directory.
|
|
@code{load} tries all three possible suffixes in the first directory in
|
|
@code{load-path}, then all three suffixes in the second directory, and
|
|
so on. @xref{Library Search}.
|
|
|
|
If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
|
|
means you should consider recompiling @file{foo.el}. @xref{Byte
|
|
Compilation}.
|
|
|
|
When loading a source file (not compiled), @code{load} performs
|
|
character set translation just as Emacs would do when visiting the file.
|
|
@xref{Coding Systems}.
|
|
|
|
Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
|
|
in the echo area during loading unless @var{nomessage} is
|
|
non-@code{nil}.
|
|
|
|
@cindex load errors
|
|
Any unhandled errors while loading a file terminate loading. If the
|
|
load was done for the sake of @code{autoload}, any function definitions
|
|
made during the loading are undone.
|
|
|
|
@kindex file-error
|
|
If @code{load} can't find the file to load, then normally it signals the
|
|
error @code{file-error} (with @samp{Cannot open load file
|
|
@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
|
|
@code{load} just returns @code{nil}.
|
|
|
|
You can use the variable @code{load-read-function} to specify a function
|
|
for @code{load} to use instead of @code{read} for reading expressions.
|
|
See below.
|
|
|
|
@code{load} returns @code{t} if the file loads successfully.
|
|
@end defun
|
|
|
|
@deffn Command load-file filename
|
|
This command loads the file @var{filename}. If @var{filename} is a
|
|
relative file name, then the current default directory is assumed.
|
|
@code{load-path} is not used, and suffixes are not appended. Use this
|
|
command if you wish to specify precisely the file name to load.
|
|
@end deffn
|
|
|
|
@deffn Command load-library library
|
|
This command loads the library named @var{library}. It is equivalent to
|
|
@code{load}, except in how it reads its argument interactively.
|
|
@end deffn
|
|
|
|
@defvar load-in-progress
|
|
This variable is non-@code{nil} if Emacs is in the process of loading a
|
|
file, and it is @code{nil} otherwise.
|
|
@end defvar
|
|
|
|
@defvar load-read-function
|
|
This variable specifies an alternate expression-reading function for
|
|
@code{load} and @code{eval-region} to use instead of @code{read}.
|
|
The function should accept one argument, just as @code{read} does.
|
|
|
|
Normally, the variable's value is @code{nil}, which means those
|
|
functions should use @code{read}.
|
|
|
|
@strong{Note:} Instead of using this variable, it is cleaner to use
|
|
another, newer feature: to pass the function as the @var{read-function}
|
|
argument to @code{eval-region}. @xref{Eval}.
|
|
@end defvar
|
|
|
|
For information about how @code{load} is used in building Emacs, see
|
|
@ref{Building Emacs}.
|
|
|
|
@node Library Search
|
|
@section Library Search
|
|
|
|
When Emacs loads a Lisp library, it searches for the library
|
|
in a list of directories specified by the variable @code{load-path}.
|
|
|
|
@defopt load-path
|
|
@cindex @code{EMACSLOADPATH} environment variable
|
|
The value of this variable is a list of directories to search when
|
|
loading files with @code{load}. Each element is a string (which must be
|
|
a directory name) or @code{nil} (which stands for the current working
|
|
directory).
|
|
@end defopt
|
|
|
|
The value of @code{load-path} is initialized from the environment
|
|
variable @code{EMACSLOADPATH}, if that exists; otherwise its default
|
|
value is specified in @file{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 @code{EMACSLOADPATH} is the same as used for @code{PATH};
|
|
@samp{:} (or @samp{;}, according to the operating system) separates
|
|
directory names, and @samp{.} is used for the current default directory.
|
|
Here is an example of how to set your @code{EMACSLOADPATH} variable from
|
|
a @code{csh} @file{.login} file:
|
|
|
|
@smallexample
|
|
setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
|
|
@end smallexample
|
|
|
|
Here is how to set it using @code{sh}:
|
|
|
|
@smallexample
|
|
export EMACSLOADPATH
|
|
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
|
|
@end smallexample
|
|
|
|
Here is an example of code you can place in your init file (@pxref{Init
|
|
File}) to add several directories to the front of your default
|
|
@code{load-path}:
|
|
|
|
@smallexample
|
|
@group
|
|
(setq load-path
|
|
(append (list nil "/user/bil/emacs"
|
|
"/usr/local/lisplib"
|
|
"~/emacs")
|
|
load-path))
|
|
@end group
|
|
@end smallexample
|
|
|
|
@c Wordy to rid us of an overfull hbox. --rjc 15mar92
|
|
@noindent
|
|
In this example, the path searches the current working directory first,
|
|
followed then by the @file{/user/bil/emacs} directory, the
|
|
@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
|
|
which are then followed by the standard directories for Lisp code.
|
|
|
|
Dumping Emacs uses a special value of @code{load-path}. If the value of
|
|
@code{load-path} at the end of dumping is unchanged (that is, still the
|
|
same special value), the dumped Emacs switches to the ordinary
|
|
@code{load-path} value when it starts up, as described above. But if
|
|
@code{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 @code{load-path} temporarily for
|
|
loading a few libraries in @file{site-init.el} or @file{site-load.el},
|
|
you should bind @code{load-path} locally with @code{let} around the
|
|
calls to @code{load}.
|
|
|
|
The default value of @code{load-path}, when running an Emacs which has
|
|
been installed on the system, includes two special directories (and
|
|
their subdirectories as well):
|
|
|
|
@smallexample
|
|
"/usr/local/share/emacs/@var{version}/site-lisp"
|
|
@end smallexample
|
|
|
|
@noindent
|
|
and
|
|
|
|
@smallexample
|
|
"/usr/local/share/emacs/site-lisp"
|
|
@end smallexample
|
|
|
|
@noindent
|
|
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
|
|
@code{load-path} when it starts up. Both immediate subdirectories and
|
|
subdirectories multiple levels down are added to @code{load-path}.
|
|
|
|
Not all subdirectories are included, though. Subdirectories whose
|
|
names do not start with a letter or digit are excluded. Subdirectories
|
|
named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which
|
|
contains a file named @file{.nosearch} is excluded. You can use these
|
|
methods to prevent certain subdirectories of the @file{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 @code{load-path}
|
|
normally contains two additional directories. These are the @code{lisp}
|
|
and @code{site-lisp} subdirectories of the main build directory. (Both
|
|
are represented as absolute file names.)
|
|
|
|
@deffn Command locate-library library &optional nosuffix path interactive-call
|
|
This command finds the precise file name for library @var{library}. It
|
|
searches for the library in the same way @code{load} does, and the
|
|
argument @var{nosuffix} has the same meaning as in @code{load}: don't
|
|
add suffixes @samp{.elc} or @samp{.el} to the specified name
|
|
@var{library}.
|
|
|
|
If the @var{path} is non-@code{nil}, that list of directories is used
|
|
instead of @code{load-path}.
|
|
|
|
When @code{locate-library} is called from a program, it returns the file
|
|
name as a string. When the user runs @code{locate-library}
|
|
interactively, the argument @var{interactive-call} is @code{t}, and this
|
|
tells @code{locate-library} to display the file name in the echo area.
|
|
@end deffn
|
|
|
|
@node Loading Non-ASCII
|
|
@section Loading Non-@sc{ascii} Characters
|
|
|
|
When Emacs Lisp programs contain string constants with non-@sc{ascii}
|
|
characters, these can be represented within Emacs either as unibyte
|
|
strings or as multibyte strings (@pxref{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.
|
|
@xref{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 @samp{--unibyte} option. This means that string
|
|
constants with non-@sc{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
|
|
@code{default-enable-multibyte-characters}, and convert representations
|
|
appropriately.
|
|
|
|
In most Emacs Lisp programs, the fact that non-@sc{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 @samp{-*-unibyte: t;-*-} in a
|
|
comment on the file's first line. With that designator, the file will
|
|
unconditionally be interpreted as unibyte, even in an ordinary
|
|
multibyte Emacs session. This can matter when making keybindings to
|
|
non-@sc{ascii} characters written as @code{?v@var{literal}}.
|
|
|
|
@node Autoload
|
|
@section Autoload
|
|
@cindex autoload
|
|
|
|
The @dfn{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
|
|
@code{autoload}, and by writing a special ``magic'' comment in the
|
|
source before the real definition. @code{autoload} is the low-level
|
|
primitive for autoloading; any Lisp program can call @code{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
|
|
@code{update-file-autoloads}, which constructs calls to @code{autoload}
|
|
and arranges to execute them when Emacs is built.
|
|
|
|
@defun autoload function filename &optional docstring interactive type
|
|
This function defines the function (or macro) named @var{function} so as
|
|
to load automatically from @var{filename}. The string @var{filename}
|
|
specifies the file to load to get the real definition of @var{function}.
|
|
|
|
If @var{filename} does not contain either a directory name, or the
|
|
suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
|
|
one of these suffixes, and it will not load from a file whose name is
|
|
just @var{filename} with no added suffix.
|
|
|
|
The argument @var{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 @code{autoload} makes it possible to look at the
|
|
documentation without loading the function's real definition.
|
|
|
|
If @var{interactive} is non-@code{nil}, that says @var{function} can be
|
|
called interactively. This lets completion in @kbd{M-x} work without
|
|
loading @var{function}'s real definition. The complete interactive
|
|
specification is not given here; it's not needed unless the user
|
|
actually calls @var{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 @var{type} as @code{macro} if @var{function} is really a macro.
|
|
Specify @var{type} as @code{keymap} if @var{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 @var{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 @code{define-key}; not even if the variable name is the same
|
|
symbol @var{function}.
|
|
|
|
@cindex function cell in autoload
|
|
If @var{function} already has a non-void function definition that is not
|
|
an autoload object, @code{autoload} does nothing and returns @code{nil}.
|
|
If the function cell of @var{function} is void, or is already an autoload
|
|
object, then it is defined as an autoload object like this:
|
|
|
|
@example
|
|
(autoload @var{filename} @var{docstring} @var{interactive} @var{type})
|
|
@end example
|
|
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
(symbol-function 'run-prolog)
|
|
@result{} (autoload "prolog" 169681 t nil)
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
In this case, @code{"prolog"} is the name of the file to load, 169681
|
|
refers to the documentation string in the
|
|
@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
|
|
@code{t} means the function is interactive, and @code{nil} that it is
|
|
not a macro or a keymap.
|
|
@end defun
|
|
|
|
@cindex autoload errors
|
|
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 @code{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 @code{"Autoloading failed to
|
|
define function @var{function-name}"}.
|
|
|
|
@findex update-file-autoloads
|
|
@findex update-directory-autoloads
|
|
A magic autoload comment consists of @samp{;;;###autoload}, on a line
|
|
by itself, just before the real definition of the function in its
|
|
autoloadable source file. The command @kbd{M-x update-file-autoloads}
|
|
writes a corresponding @code{autoload} call into @file{loaddefs.el}.
|
|
Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
|
|
@kbd{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
|
|
@file{loaddefs.el}. If the form following the magic comment is not a
|
|
function-defining form or a @code{defcustom} form, it is copied
|
|
verbatim. ``Function-defining forms'' include @code{define-skeleton},
|
|
@code{define-derived-mode}, @code{define-generic-mode} and
|
|
@code{define-minor-mode} as well as @code{defun} and
|
|
@code{defmacro}. To save space, a @code{defcustom} form is converted to
|
|
a @code{defvar} in @file{loaddefs.el}, with some additional information
|
|
if it uses @code{:require}.
|
|
|
|
You can also use a magic comment to execute a form at build time
|
|
@emph{without} executing it when the file itself is loaded. To do this,
|
|
write the form @emph{on the same line} as the magic comment. Since it
|
|
is in a comment, it does nothing when you load the source file; but
|
|
@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
|
|
it is executed while building Emacs.
|
|
|
|
The following example shows how @code{doctor} is prepared for
|
|
autoloading with a magic comment:
|
|
|
|
@smallexample
|
|
;;;###autoload
|
|
(defun doctor ()
|
|
"Switch to *doctor* buffer and start giving psychotherapy."
|
|
(interactive)
|
|
(switch-to-buffer "*doctor*")
|
|
(doctor-mode))
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Here's what that produces in @file{loaddefs.el}:
|
|
|
|
@smallexample
|
|
(autoload 'doctor "doctor" "\
|
|
Switch to *doctor* buffer and start giving psychotherapy."
|
|
t)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The backslash and newline immediately following the double-quote are a
|
|
convention used only in the preloaded uncompiled Lisp files such as
|
|
@file{loaddefs.el}; they tell @code{make-docfile} to put the
|
|
documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
|
|
See also the commentary in @file{lib-src/make-docfile.c}.
|
|
|
|
@node Repeated Loading
|
|
@section Repeated Loading
|
|
@cindex repeated loading
|
|
|
|
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 @code{load} and
|
|
@code{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, @samp{(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;
|
|
@code{defvar} does not change the value if the variable is already
|
|
initialized. (@xref{Defining Variables}.)
|
|
|
|
The simplest way to add an element to an alist is like this:
|
|
|
|
@example
|
|
(setq minor-mode-alist
|
|
(cons '(leif-mode " Leif") minor-mode-alist))
|
|
@end example
|
|
|
|
@noindent
|
|
But this would add multiple elements if the library is reloaded.
|
|
To avoid the problem, write this:
|
|
|
|
@example
|
|
(or (assq 'leif-mode minor-mode-alist)
|
|
(setq minor-mode-alist
|
|
(cons '(leif-mode " Leif") minor-mode-alist)))
|
|
@end example
|
|
|
|
To add an element to a list just once, you can also use @code{add-to-list}
|
|
(@pxref{Setting Variables}).
|
|
|
|
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:
|
|
|
|
@example
|
|
(defvar foo-was-loaded nil)
|
|
|
|
(unless foo-was-loaded
|
|
@var{execute-first-time-only}
|
|
(setq foo-was-loaded t))
|
|
@end example
|
|
|
|
@noindent
|
|
If the library uses @code{provide} to provide a named feature, you can
|
|
use @code{featurep} earlier in the file to test whether the
|
|
@code{provide} call has been executed before.
|
|
@ifnottex
|
|
@xref{Named Features}.
|
|
@end ifnottex
|
|
|
|
@node Named Features
|
|
@section Features
|
|
@cindex features
|
|
@cindex requiring features
|
|
@cindex providing features
|
|
|
|
@code{provide} and @code{require} are an alternative to
|
|
@code{autoload} for loading files automatically. They work in terms of
|
|
named @dfn{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 @dfn{provide} the
|
|
feature. Another program that uses them may ensure they are defined by
|
|
@dfn{requiring} the feature. This loads the file of definitions if it
|
|
hasn't been loaded already.
|
|
|
|
To require the presence of a feature, call @code{require} with the
|
|
feature name as argument. @code{require} looks in the global variable
|
|
@code{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 @code{provide} at the top level to add the feature to
|
|
@code{features}; if it fails to do so, @code{require} signals an error.
|
|
@cindex load error with require
|
|
|
|
For example, in @file{emacs/lisp/prolog.el},
|
|
the definition for @code{run-prolog} includes the following code:
|
|
|
|
@smallexample
|
|
(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))
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The expression @code{(require 'comint)} loads the file @file{comint.el}
|
|
if it has not yet been loaded. This ensures that @code{make-comint} is
|
|
defined. Features are normally named after the files that provide them,
|
|
so that @code{require} need not be given the file name.
|
|
|
|
The @file{comint.el} file contains the following top-level expression:
|
|
|
|
@smallexample
|
|
(provide 'comint)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This adds @code{comint} to the global @code{features} list, so that
|
|
@code{(require 'comint)} will henceforth know that nothing needs to be
|
|
done.
|
|
|
|
@cindex byte-compiling @code{require}
|
|
When @code{require} is used at top level in a file, it takes effect
|
|
when you byte-compile that file (@pxref{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. It also avoids byte-compiler
|
|
warnings for functions and variables defined in the file loaded with
|
|
@code{require}.
|
|
|
|
Although top-level calls to @code{require} are evaluated during
|
|
byte compilation, @code{provide} calls are not. Therefore, you can
|
|
ensure that a file of definitions is loaded before it is byte-compiled
|
|
by including a @code{provide} followed by a @code{require} for the same
|
|
feature, as in the following example.
|
|
|
|
@smallexample
|
|
@group
|
|
(provide 'my-feature) ; @r{Ignored by byte compiler,}
|
|
; @r{evaluated by @code{load}.}
|
|
(require 'my-feature) ; @r{Evaluated by byte compiler.}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The compiler ignores the @code{provide}, then processes the
|
|
@code{require} by loading the file in question. Loading the file does
|
|
execute the @code{provide} call, so the subsequent @code{require} call
|
|
does nothing when the file is loaded.
|
|
|
|
@defun provide feature
|
|
This function announces that @var{feature} is now loaded, or being
|
|
loaded, into the current Emacs session. This means that the facilities
|
|
associated with @var{feature} are or will be available for other Lisp
|
|
programs.
|
|
|
|
The direct effect of calling @code{provide} is to add @var{feature} to
|
|
the front of the list @code{features} if it is not already in the list.
|
|
The argument @var{feature} must be a symbol. @code{provide} returns
|
|
@var{feature}.
|
|
|
|
@smallexample
|
|
features
|
|
@result{} (bar bish)
|
|
|
|
(provide 'foo)
|
|
@result{} foo
|
|
features
|
|
@result{} (foo bar bish)
|
|
@end smallexample
|
|
|
|
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
|
|
@code{provide} calls that occurred during the load are undone.
|
|
@xref{Autoload}.
|
|
@end defun
|
|
|
|
@defun require feature &optional filename noerror
|
|
This function checks whether @var{feature} is present in the current
|
|
Emacs session (using @code{(featurep @var{feature})}; see below). The
|
|
argument @var{feature} must be a symbol.
|
|
|
|
If the feature is not present, then @code{require} loads @var{filename}
|
|
with @code{load}. If @var{filename} is not supplied, then the name of
|
|
the symbol @var{feature} is used as the base file name to load.
|
|
However, in this case, @code{require} insists on finding @var{feature}
|
|
with an added suffix; a file whose name is just @var{feature} won't be
|
|
used.
|
|
|
|
If loading the file fails to provide @var{feature}, @code{require}
|
|
signals an error, @samp{Required feature @var{feature} was not
|
|
provided}, unless @var{noerror} is non-@code{nil}.
|
|
@end defun
|
|
|
|
@defun featurep feature
|
|
This function returns @code{t} if @var{feature} has been provided in the
|
|
current Emacs session (i.e., if @var{feature} is a member of
|
|
@code{features}.)
|
|
@end defun
|
|
|
|
@defvar 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 @code{provide}. The order of the elements in the
|
|
@code{features} list is not significant.
|
|
@end defvar
|
|
|
|
@node Unloading
|
|
@section Unloading
|
|
@cindex unloading
|
|
|
|
@c Emacs 19 feature
|
|
You can discard the functions and variables loaded by a library to
|
|
reclaim memory for other Lisp objects. To do this, use the function
|
|
@code{unload-feature}:
|
|
|
|
@deffn Command unload-feature feature &optional force
|
|
This command unloads the library that provided feature @var{feature}.
|
|
It undefines all functions, macros, and variables defined in that
|
|
library with @code{defun}, @code{defalias}, @code{defsubst},
|
|
@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
|
|
It then restores any autoloads formerly associated with those symbols.
|
|
(Loading saves these in the @code{autoload} property of the symbol.)
|
|
|
|
Before restoring the previous definitions, @code{unload-feature} runs
|
|
@code{remove-hook} to remove functions in the library from certain
|
|
hooks. These hooks include variables whose names end in @samp{hook} or
|
|
@samp{-hooks}, plus those listed in @code{loadhist-special-hooks}. This
|
|
is to prevent Emacs from ceasing to function because important hooks
|
|
refer to functions that are no longer defined.
|
|
|
|
@vindex @var{feature}-unload-hook
|
|
If these measures are not sufficient to prevent malfunction, a library
|
|
can define an explicit unload hook. If @code{@var{feature}-unload-hook}
|
|
is defined, it is run as a normal hook before restoring the previous
|
|
definitions, @emph{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.
|
|
@code{unload-feature} can cause problems with libraries that fail to do
|
|
this, so it should be used with caution.
|
|
|
|
Ordinarily, @code{unload-feature} refuses to unload a library on which
|
|
other loaded libraries depend. (A library @var{a} depends on library
|
|
@var{b} if @var{a} contains a @code{require} for @var{b}.) If the
|
|
optional argument @var{force} is non-@code{nil}, dependencies are
|
|
ignored and you can unload any library.
|
|
@end deffn
|
|
|
|
The @code{unload-feature} function is written in Lisp; its actions are
|
|
based on the variable @code{load-history}.
|
|
|
|
@defvar 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 @sc{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:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Symbols that were defined by this library.
|
|
@item
|
|
Cons cells of the form @code{(require . @var{feature})} indicating
|
|
features that were required.
|
|
@item
|
|
Cons cells of the form @code{(provide . @var{feature})} indicating
|
|
features that were provided.
|
|
@end itemize
|
|
|
|
The value of @code{load-history} may have one element whose @sc{car} is
|
|
@code{nil}. This element describes definitions made with
|
|
@code{eval-buffer} on a buffer that is not visiting a file.
|
|
@end defvar
|
|
|
|
The command @code{eval-region} updates @code{load-history}, but does so
|
|
by adding the symbols defined to the element for the file being visited,
|
|
rather than replacing that element. @xref{Eval}.
|
|
|
|
Preloaded libraries don't contribute initially to @code{load-history}.
|
|
Instead, preloading writes information about preloaded libraries into a
|
|
file, which can be loaded later on to add information to
|
|
@code{load-history} describing the preloaded files. This file is
|
|
installed in @code{exec-directory} and has a name of the form
|
|
@file{fns-@var{emacsversion}.el}.
|
|
|
|
@findex symbol-file
|
|
See the source for the function @code{symbol-file}, for an example of
|
|
code that loads this file to find functions in preloaded libraries.
|
|
|
|
@defvar loadhist-special-hooks
|
|
This variable holds a list of hooks to be scanned before unloading a
|
|
library, to remove functions defined in the library.
|
|
@end defvar
|
|
|
|
@node Hooks for Loading
|
|
@section Hooks for Loading
|
|
@cindex loading hooks
|
|
@cindex hooks for loading
|
|
|
|
You can ask for code to be executed if and when a particular library is
|
|
loaded, by calling @code{eval-after-load}.
|
|
|
|
@defun eval-after-load library form
|
|
This function arranges to evaluate @var{form} at the end of loading the
|
|
library @var{library}, if and when @var{library} is loaded. If
|
|
@var{library} is already loaded, it evaluates @var{form} right away.
|
|
|
|
The library name @var{library} must exactly match the argument of
|
|
@code{load}. To get the proper results when an installed library is
|
|
found by searching @code{load-path}, you should not include any
|
|
directory names in @var{library}.
|
|
|
|
An error in @var{form} does not undo the load, but does prevent
|
|
execution of the rest of @var{form}.
|
|
@end defun
|
|
|
|
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 @code{require}).
|
|
|
|
But it is OK to use @code{eval-after-load} in your personal
|
|
customizations if you don't feel they must meet the design standards for
|
|
programs meant for wider use.
|
|
|
|
@defvar after-load-alist
|
|
This variable holds an alist of expressions to evaluate if and when
|
|
particular libraries are loaded. Each element looks like this:
|
|
|
|
@example
|
|
(@var{filename} @var{forms}@dots{})
|
|
@end example
|
|
|
|
The function @code{load} checks @code{after-load-alist} in order to
|
|
implement @code{eval-after-load}.
|
|
@end defvar
|
|
|
|
@c Emacs 19 feature
|