(Feval): Put check for interrupt_input_block in #if 0.
[bpt/emacs.git] / lispref / loading.texi
CommitLineData
83ac6b45
RS
1@c -*-texinfo-*-
2@c This is part of the GNU Emacs Lisp Reference Manual.
fd897522
GM
3@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4@c Free Software Foundation, Inc.
83ac6b45
RS
5@c See the file elisp.texi for copying conditions.
6@setfilename ../info/loading
f9f59935 7@node Loading, Byte Compilation, Customization, Top
83ac6b45
RS
8@chapter Loading
9@cindex loading
10@cindex library
11@cindex Lisp library
12
13 Loading a file of Lisp code means bringing its contents into the Lisp
14environment in the form of Lisp objects. Emacs finds and opens the
15file, reads the text, evaluates each form, and then closes the file.
16
17 The load functions evaluate all the expressions in a file just
18as the @code{eval-current-buffer} function evaluates all the
19expressions in a buffer. The difference is that the load functions
20read and evaluate the text in the file as found on disk, not the text
21in an Emacs buffer.
22
23@cindex top-level form
24 The loaded file must contain Lisp expressions, either as source code
78c71a98
RS
25or as byte-compiled code. Each form in the file is called a
26@dfn{top-level form}. There is no special format for the forms in a
83ac6b45
RS
27loadable file; any form in a file may equally well be typed directly
28into a buffer and evaluated there. (Indeed, most code is tested this
29way.) Most often, the forms are function definitions and variable
30definitions.
31
32 A file containing Lisp code is often called a @dfn{library}. Thus,
33the ``Rmail library'' is a file containing code for Rmail mode.
34Similarly, a ``Lisp library directory'' is a directory of files
35containing Lisp code.
36
37@menu
38* How Programs Do Loading:: The @code{load} function and others.
a9f0a989 39* Library Search:: Finding a library to load.
8241495d 40* Loading Non-ASCII:: Non-@sc{ascii} characters in Emacs Lisp files.
83ac6b45
RS
41* Autoload:: Setting up a function to autoload.
42* Repeated Loading:: Precautions about loading a file twice.
bfe721d1 43* Named Features:: Loading a library if it isn't already loaded.
83ac6b45
RS
44* Unloading:: How to ``unload'' a library that was loaded.
45* Hooks for Loading:: Providing code to be run when
46 particular libraries are loaded.
47@end menu
48
49@node How Programs Do Loading
50@section How Programs Do Loading
51
52 Emacs Lisp has several interfaces for loading. For example,
f9f59935
RS
53@code{autoload} creates a placeholder object for a function defined in a
54file; trying to call the autoloading function loads the file to get the
83ac6b45 55function's real definition (@pxref{Autoload}). @code{require} loads a
f9f59935
RS
56file if it isn't already loaded (@pxref{Named Features}). Ultimately,
57all these facilities call the @code{load} function to do the work.
83ac6b45 58
a9f0a989 59@defun load filename &optional missing-ok nomessage nosuffix must-suffix
83ac6b45
RS
60This function finds and opens a file of Lisp code, evaluates all the
61forms in it, and closes the file.
62
63To find the file, @code{load} first looks for a file named
64@file{@var{filename}.elc}, that is, for a file whose name is
65@var{filename} with @samp{.elc} appended. If such a file exists, it is
66loaded. If there is no file by that name, then @code{load} looks for a
78c71a98 67file named @file{@var{filename}.el}. If that file exists, it is loaded.
83ac6b45
RS
68Finally, if neither of those names is found, @code{load} looks for a
69file named @var{filename} with nothing appended, and loads it if it
70exists. (The @code{load} function is not clever about looking at
71@var{filename}. In the perverse case of a file named @file{foo.el.el},
72evaluation of @code{(load "foo.el")} will indeed find it.)
73
74If the optional argument @var{nosuffix} is non-@code{nil}, then the
75suffixes @samp{.elc} and @samp{.el} are not tried. In this case, you
f9f59935
RS
76must specify the precise file name you want. By specifying the precise
77file name and using @code{t} for @var{nosuffix}, you can prevent
78perverse file names such as @file{foo.el.el} from being tried.
83ac6b45 79
a9f0a989
RS
80If the optional argument @var{must-suffix} is non-@code{nil}, then
81@code{load} insists that the file name used must end in either
82@samp{.el} or @samp{.elc}, unless it contains an explicit directory
83name. If @var{filename} does not contain an explicit directory name,
84and does not end in a suffix, then @code{load} insists on adding one.
85
83ac6b45
RS
86If @var{filename} is a relative file name, such as @file{foo} or
87@file{baz/foo.bar}, @code{load} searches for the file using the variable
88@code{load-path}. It appends @var{filename} to each of the directories
89listed in @code{load-path}, and loads the first file it finds whose name
90matches. The current default directory is tried only if it is specified
91in @code{load-path}, where @code{nil} stands for the default directory.
92@code{load} tries all three possible suffixes in the first directory in
93@code{load-path}, then all three suffixes in the second directory, and
a9f0a989 94so on. @xref{Library Search}.
83ac6b45
RS
95
96If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
97means you should consider recompiling @file{foo.el}. @xref{Byte
98Compilation}.
99
969fe9b5
RS
100When loading a source file (not compiled), @code{load} performs
101character set translation just as Emacs would do when visiting the file.
102@xref{Coding Systems}.
103
83ac6b45
RS
104Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
105in the echo area during loading unless @var{nomessage} is
106non-@code{nil}.
107
108@cindex load errors
109Any unhandled errors while loading a file terminate loading. If the
78c71a98
RS
110load was done for the sake of @code{autoload}, any function definitions
111made during the loading are undone.
83ac6b45
RS
112
113@kindex file-error
114If @code{load} can't find the file to load, then normally it signals the
115error @code{file-error} (with @samp{Cannot open load file
116@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
117@code{load} just returns @code{nil}.
118
22697dac
KH
119You can use the variable @code{load-read-function} to specify a function
120for @code{load} to use instead of @code{read} for reading expressions.
121See below.
122
83ac6b45
RS
123@code{load} returns @code{t} if the file loads successfully.
124@end defun
125
83ac6b45 126@deffn Command load-file filename
f9f59935
RS
127This command loads the file @var{filename}. If @var{filename} is a
128relative file name, then the current default directory is assumed.
129@code{load-path} is not used, and suffixes are not appended. Use this
a9f0a989 130command if you wish to specify precisely the file name to load.
83ac6b45
RS
131@end deffn
132
133@deffn Command load-library library
f9f59935
RS
134This command loads the library named @var{library}. It is equivalent to
135@code{load}, except in how it reads its argument interactively.
83ac6b45 136@end deffn
83ac6b45 137
a9f0a989
RS
138@defvar load-in-progress
139This variable is non-@code{nil} if Emacs is in the process of loading a
140file, and it is @code{nil} otherwise.
141@end defvar
142
143@defvar load-read-function
144This variable specifies an alternate expression-reading function for
145@code{load} and @code{eval-region} to use instead of @code{read}.
146The function should accept one argument, just as @code{read} does.
147
148Normally, the variable's value is @code{nil}, which means those
149functions should use @code{read}.
55607887
RS
150
151@strong{Note:} Instead of using this variable, it is cleaner to use
152another, newer feature: to pass the function as the @var{read-function}
153argument to @code{eval-region}. @xref{Eval}.
a9f0a989
RS
154@end defvar
155
1911e6e5
RS
156 For information about how @code{load} is used in building Emacs, see
157@ref{Building Emacs}.
a9f0a989
RS
158
159@node Library Search
160@section Library Search
161
162 When Emacs loads a Lisp library, it searches for the library
163in a list of directories specified by the variable @code{load-path}.
164
83ac6b45
RS
165@defopt load-path
166@cindex @code{EMACSLOADPATH} environment variable
167The value of this variable is a list of directories to search when
168loading files with @code{load}. Each element is a string (which must be
169a directory name) or @code{nil} (which stands for the current working
a9f0a989
RS
170directory).
171@end defopt
172
173 The value of @code{load-path} is initialized from the environment
174variable @code{EMACSLOADPATH}, if that exists; otherwise its default
175value is specified in @file{emacs/src/paths.h} when Emacs is built.
176Then the list is expanded by adding subdirectories of the directories
177in the list.
83ac6b45 178
a9f0a989 179 The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
bfe721d1
KH
180@samp{:} (or @samp{;}, according to the operating system) separates
181directory names, and @samp{.} is used for the current default directory.
182Here is an example of how to set your @code{EMACSLOADPATH} variable from
183a @code{csh} @file{.login} file:
83ac6b45 184
83ac6b45 185@smallexample
f1e2c45e 186setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
83ac6b45
RS
187@end smallexample
188
a9f0a989 189 Here is how to set it using @code{sh}:
83ac6b45
RS
190
191@smallexample
192export EMACSLOADPATH
f1e2c45e 193EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
83ac6b45
RS
194@end smallexample
195
a40d4712
PR
196 Here is an example of code you can place in your init file (@pxref{Init
197File}) to add several directories to the front of your default
198@code{load-path}:
83ac6b45
RS
199
200@smallexample
bda144f4 201@group
83ac6b45
RS
202(setq load-path
203 (append (list nil "/user/bil/emacs"
204 "/usr/local/lisplib"
5e41cf03 205 "~/emacs")
83ac6b45 206 load-path))
bda144f4 207@end group
83ac6b45
RS
208@end smallexample
209
210@c Wordy to rid us of an overfull hbox. --rjc 15mar92
211@noindent
212In this example, the path searches the current working directory first,
5e41cf03
RS
213followed then by the @file{/user/bil/emacs} directory, the
214@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
83ac6b45
RS
215which are then followed by the standard directories for Lisp code.
216
a9f0a989 217 Dumping Emacs uses a special value of @code{load-path}. If the value of
c642171c
RS
218@code{load-path} at the end of dumping is unchanged (that is, still the
219same special value), the dumped Emacs switches to the ordinary
cc8c51f1 220@code{load-path} value when it starts up, as described above. But if
c642171c
RS
221@code{load-path} has any other value at the end of dumping, that value
222is used for execution of the dumped Emacs also.
223
a9f0a989 224 Therefore, if you want to change @code{load-path} temporarily for
c642171c
RS
225loading a few libraries in @file{site-init.el} or @file{site-load.el},
226you should bind @code{load-path} locally with @code{let} around the
227calls to @code{load}.
83ac6b45 228
089e089d 229 The default value of @code{load-path}, when running an Emacs which has
a9f0a989
RS
230been installed on the system, includes two special directories (and
231their subdirectories as well):
089e089d
RS
232
233@smallexample
a9f0a989 234"/usr/local/share/emacs/@var{version}/site-lisp"
089e089d
RS
235@end smallexample
236
a9f0a989
RS
237@noindent
238and
239
240@smallexample
241"/usr/local/share/emacs/site-lisp"
242@end smallexample
243
244@noindent
245The first one is for locally installed packages for a particular Emacs
246version; the second is for locally installed packages meant for use with
247all installed Emacs versions.
089e089d
RS
248
249 There are several reasons why a Lisp package that works well in one
250Emacs version can cause trouble in another. Sometimes packages need
251updating for incompatible changes in Emacs; sometimes they depend on
252undocumented internal Emacs data that can change without notice;
253sometimes a newer Emacs version incorporates a version of the package,
254and should be used only with that version.
255
a9f0a989
RS
256 Emacs finds these directories' subdirectories and adds them to
257@code{load-path} when it starts up. Both immediate subdirectories and
258subdirectories multiple levels down are added to @code{load-path}.
259
260 Not all subdirectories are included, though. Subdirectories whose
261names do not start with a letter or digit are excluded. Subdirectories
8241495d
RS
262named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which
263contains a file named @file{.nosearch} is excluded. You can use these
264methods to prevent certain subdirectories of the @file{site-lisp}
265directories from being searched.
a9f0a989 266
089e089d
RS
267 If you run Emacs from the directory where it was built---that is, an
268executable that has not been formally installed---then @code{load-path}
269normally contains two additional directories. These are the @code{lisp}
270and @code{site-lisp} subdirectories of the main build directory. (Both
271are represented as absolute file names.)
272
f9f59935
RS
273@deffn Command locate-library library &optional nosuffix path interactive-call
274This command finds the precise file name for library @var{library}. It
275searches for the library in the same way @code{load} does, and the
276argument @var{nosuffix} has the same meaning as in @code{load}: don't
277add suffixes @samp{.elc} or @samp{.el} to the specified name
278@var{library}.
279
280If the @var{path} is non-@code{nil}, that list of directories is used
281instead of @code{load-path}.
282
283When @code{locate-library} is called from a program, it returns the file
284name as a string. When the user runs @code{locate-library}
285interactively, the argument @var{interactive-call} is @code{t}, and this
286tells @code{locate-library} to display the file name in the echo area.
287@end deffn
288
a9f0a989 289@node Loading Non-ASCII
75708135 290@section Loading Non-@sc{ascii} Characters
a9f0a989 291
8241495d 292 When Emacs Lisp programs contain string constants with non-@sc{ascii}
a9f0a989
RS
293characters, these can be represented within Emacs either as unibyte
294strings or as multibyte strings (@pxref{Text Representations}). Which
295representation is used depends on how the file is read into Emacs. If
296it is read with decoding into multibyte representation, the text of the
297Lisp program will be multibyte text, and its string constants will be
298multibyte strings. If a file containing Latin-1 characters (for
299example) is read without decoding, the text of the program will be
300unibyte text, and its string constants will be unibyte strings.
301@xref{Coding Systems}.
302
303 To make the results more predictable, Emacs always performs decoding
304into the multibyte representation when loading Lisp files, even if it
305was started with the @samp{--unibyte} option. This means that string
8241495d 306constants with non-@sc{ascii} characters translate into multibyte
a9f0a989
RS
307strings. The only exception is when a particular file specifies no
308decoding.
309
310 The reason Emacs is designed this way is so that Lisp programs give
311predictable results, regardless of how Emacs was started. In addition,
312this enables programs that depend on using multibyte text to work even
313in a unibyte Emacs. Of course, such programs should be designed to
314notice whether the user prefers unibyte or multibyte text, by checking
315@code{default-enable-multibyte-characters}, and convert representations
316appropriately.
317
8241495d 318 In most Emacs Lisp programs, the fact that non-@sc{ascii} strings are
a9f0a989
RS
319multibyte strings should not be noticeable, since inserting them in
320unibyte buffers converts them to unibyte automatically. However, if
321this does make a difference, you can force a particular Lisp file to be
430f8c73 322interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
a9f0a989 323comment on the file's first line. With that designator, the file will
8241495d 324unconditionally be interpreted as unibyte, even in an ordinary
a9f0a989
RS
325multibyte Emacs session.
326
83ac6b45
RS
327@node Autoload
328@section Autoload
329@cindex autoload
330
331 The @dfn{autoload} facility allows you to make a function or macro
bfe721d1
KH
332known in Lisp, but put off loading the file that defines it. The first
333call to the function automatically reads the proper file to install the
334real definition and other associated code, then runs the real definition
83ac6b45
RS
335as if it had been loaded all along.
336
337 There are two ways to set up an autoloaded function: by calling
338@code{autoload}, and by writing a special ``magic'' comment in the
339source before the real definition. @code{autoload} is the low-level
340primitive for autoloading; any Lisp program can call @code{autoload} at
969fe9b5 341any time. Magic comments are the most convenient way to make a function
a9f0a989
RS
342autoload, for packages installed along with Emacs. These comments do
343nothing on their own, but they serve as a guide for the command
969fe9b5
RS
344@code{update-file-autoloads}, which constructs calls to @code{autoload}
345and arranges to execute them when Emacs is built.
83ac6b45 346
78c71a98
RS
347@defun autoload function filename &optional docstring interactive type
348This function defines the function (or macro) named @var{function} so as
83ac6b45
RS
349to load automatically from @var{filename}. The string @var{filename}
350specifies the file to load to get the real definition of @var{function}.
351
f9f59935
RS
352If @var{filename} does not contain either a directory name, or the
353suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
354one of these suffixes, and it will not load from a file whose name is
355just @var{filename} with no added suffix.
356
83ac6b45 357The argument @var{docstring} is the documentation string for the
f9f59935 358function. Normally, this should be identical to the documentation string
83ac6b45
RS
359in the function definition itself. Specifying the documentation string
360in the call to @code{autoload} makes it possible to look at the
361documentation without loading the function's real definition.
362
969fe9b5
RS
363If @var{interactive} is non-@code{nil}, that says @var{function} can be
364called interactively. This lets completion in @kbd{M-x} work without
a9f0a989
RS
365loading @var{function}'s real definition. The complete interactive
366specification is not given here; it's not needed unless the user
367actually calls @var{function}, and when that happens, it's time to load
368the real definition.
83ac6b45
RS
369
370You can autoload macros and keymaps as well as ordinary functions.
371Specify @var{type} as @code{macro} if @var{function} is really a macro.
372Specify @var{type} as @code{keymap} if @var{function} is really a
373keymap. Various parts of Emacs need to know this information without
374loading the real definition.
375
bda144f4
MW
376An autoloaded keymap loads automatically during key lookup when a prefix
377key's binding is the symbol @var{function}. Autoloading does not occur
378for other kinds of access to the keymap. In particular, it does not
379happen when a Lisp program gets the keymap from the value of a variable
380and calls @code{define-key}; not even if the variable name is the same
381symbol @var{function}.
382
83ac6b45 383@cindex function cell in autoload
78c71a98 384If @var{function} already has a non-void function definition that is not
83ac6b45 385an autoload object, @code{autoload} does nothing and returns @code{nil}.
78c71a98 386If the function cell of @var{function} is void, or is already an autoload
83ac6b45
RS
387object, then it is defined as an autoload object like this:
388
389@example
390(autoload @var{filename} @var{docstring} @var{interactive} @var{type})
391@end example
392
393For example,
394
395@example
bda144f4 396@group
83ac6b45
RS
397(symbol-function 'run-prolog)
398 @result{} (autoload "prolog" 169681 t nil)
bda144f4 399@end group
83ac6b45
RS
400@end example
401
402@noindent
403In this case, @code{"prolog"} is the name of the file to load, 169681
f9f59935
RS
404refers to the documentation string in the
405@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
406@code{t} means the function is interactive, and @code{nil} that it is
407not a macro or a keymap.
83ac6b45
RS
408@end defun
409
410@cindex autoload errors
411 The autoloaded file usually contains other definitions and may require
412or provide one or more features. If the file is not completely loaded
413(due to an error in the evaluation of its contents), any function
414definitions or @code{provide} calls that occurred during the load are
415undone. This is to ensure that the next attempt to call any function
416autoloading from this file will try again to load the file. If not for
a9f0a989
RS
417this, then some of the functions in the file might be defined by the
418aborted load, but fail to work properly for the lack of certain
419subroutines not loaded successfully because they come later in the file.
83ac6b45
RS
420
421 If the autoloaded file fails to define the desired Lisp function or
422macro, then an error is signaled with data @code{"Autoloading failed to
423define function @var{function-name}"}.
424
425@findex update-file-autoloads
426@findex update-directory-autoloads
a9f0a989 427 A magic autoload comment consists of @samp{;;;###autoload}, on a line
83ac6b45
RS
428by itself, just before the real definition of the function in its
429autoloadable source file. The command @kbd{M-x update-file-autoloads}
430writes a corresponding @code{autoload} call into @file{loaddefs.el}.
431Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
432@kbd{M-x update-directory-autoloads} is even more powerful; it updates
433autoloads for all files in the current directory.
434
435 The same magic comment can copy any kind of form into
436@file{loaddefs.el}. If the form following the magic comment is not a
8241495d
RS
437function-defining form or a @code{defcustom} form, it is copied
438verbatim. ``Function-defining forms'' include @code{define-skeleton},
439@code{define-derived-mode}, @code{define-generic-mode} and
5858d11f 440@code{define-minor-mode} as well as @code{defun} and
8241495d
RS
441@code{defmacro}. To save space, a @code{defcustom} form is converted to
442a @code{defvar} in @file{loaddefs.el}, with some additional information
443if it uses @code{:require}.
444
445 You can also use a magic comment to execute a form at build time
446@emph{without} executing it when the file itself is loaded. To do this,
447write the form @emph{on the same line} as the magic comment. Since it
448is in a comment, it does nothing when you load the source file; but
449@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
450it is executed while building Emacs.
83ac6b45
RS
451
452 The following example shows how @code{doctor} is prepared for
453autoloading with a magic comment:
454
455@smallexample
456;;;###autoload
457(defun doctor ()
458 "Switch to *doctor* buffer and start giving psychotherapy."
459 (interactive)
460 (switch-to-buffer "*doctor*")
461 (doctor-mode))
462@end smallexample
463
464@noindent
465Here's what that produces in @file{loaddefs.el}:
466
467@smallexample
8241495d 468(autoload 'doctor "doctor" "\
83ac6b45
RS
469Switch to *doctor* buffer and start giving psychotherapy."
470 t)
471@end smallexample
472
473@noindent
474The backslash and newline immediately following the double-quote are a
8241495d 475convention used only in the preloaded uncompiled Lisp files such as
83ac6b45
RS
476@file{loaddefs.el}; they tell @code{make-docfile} to put the
477documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
8241495d 478See also the commentary in @file{lib-src/make-docfile.c}.
83ac6b45
RS
479
480@node Repeated Loading
83ac6b45
RS
481@section Repeated Loading
482@cindex repeated loading
483
a9f0a989 484 You can load a given file more than once in an Emacs session. For
83ac6b45
RS
485example, after you have rewritten and reinstalled a function definition
486by editing it in a buffer, you may wish to return to the original
487version; you can do this by reloading the file it came from.
488
489 When you load or reload files, bear in mind that the @code{load} and
490@code{load-library} functions automatically load a byte-compiled file
491rather than a non-compiled file of similar name. If you rewrite a file
f9f59935
RS
492that you intend to save and reinstall, you need to byte-compile the new
493version; otherwise Emacs will load the older, byte-compiled file instead
494of your newer, non-compiled file! If that happens, the message
a9f0a989 495displayed when loading the file includes, @samp{(compiled; note, source is
969fe9b5 496newer)}, to remind you to recompile it.
83ac6b45
RS
497
498 When writing the forms in a Lisp library file, keep in mind that the
f9f59935
RS
499file might be loaded more than once. For example, think about whether
500each variable should be reinitialized when you reload the library;
501@code{defvar} does not change the value if the variable is already
502initialized. (@xref{Defining Variables}.)
83ac6b45
RS
503
504 The simplest way to add an element to an alist is like this:
505
506@example
507(setq minor-mode-alist
508 (cons '(leif-mode " Leif") minor-mode-alist))
509@end example
510
511@noindent
512But this would add multiple elements if the library is reloaded.
513To avoid the problem, write this:
514
515@example
516(or (assq 'leif-mode minor-mode-alist)
517 (setq minor-mode-alist
518 (cons '(leif-mode " Leif") minor-mode-alist)))
519@end example
520
a9f0a989 521 To add an element to a list just once, you can also use @code{add-to-list}
bfe721d1
KH
522(@pxref{Setting Variables}).
523
83ac6b45
RS
524 Occasionally you will want to test explicitly whether a library has
525already been loaded. Here's one way to test, in a library, whether it
526has been loaded before:
527
528@example
969fe9b5 529(defvar foo-was-loaded nil)
bfe721d1 530
969fe9b5
RS
531(unless foo-was-loaded
532 @var{execute-first-time-only}
533 (setq foo-was-loaded t))
83ac6b45
RS
534@end example
535
536@noindent
537If the library uses @code{provide} to provide a named feature, you can
969fe9b5
RS
538use @code{featurep} earlier in the file to test whether the
539@code{provide} call has been executed before.
37680279 540@ifnottex
bfe721d1 541@xref{Named Features}.
37680279 542@end ifnottex
83ac6b45 543
bfe721d1 544@node Named Features
83ac6b45
RS
545@section Features
546@cindex features
547@cindex requiring features
548@cindex providing features
549
550 @code{provide} and @code{require} are an alternative to
551@code{autoload} for loading files automatically. They work in terms of
552named @dfn{features}. Autoloading is triggered by calling a specific
553function, but a feature is loaded the first time another program asks
554for it by name.
555
556 A feature name is a symbol that stands for a collection of functions,
557variables, etc. The file that defines them should @dfn{provide} the
558feature. Another program that uses them may ensure they are defined by
559@dfn{requiring} the feature. This loads the file of definitions if it
560hasn't been loaded already.
561
562 To require the presence of a feature, call @code{require} with the
563feature name as argument. @code{require} looks in the global variable
564@code{features} to see whether the desired feature has been provided
565already. If not, it loads the feature from the appropriate file. This
78c71a98 566file should call @code{provide} at the top level to add the feature to
83ac6b45
RS
567@code{features}; if it fails to do so, @code{require} signals an error.
568@cindex load error with require
569
83ac6b45
RS
570 For example, in @file{emacs/lisp/prolog.el},
571the definition for @code{run-prolog} includes the following code:
572
573@smallexample
574(defun run-prolog ()
9e2b495b 575 "Run an inferior Prolog process, with I/O via buffer *prolog*."
83ac6b45
RS
576 (interactive)
577 (require 'comint)
578 (switch-to-buffer (make-comint "prolog" prolog-program-name))
579 (inferior-prolog-mode))
580@end smallexample
581
582@noindent
583The expression @code{(require 'comint)} loads the file @file{comint.el}
584if it has not yet been loaded. This ensures that @code{make-comint} is
969fe9b5
RS
585defined. Features are normally named after the files that provide them,
586so that @code{require} need not be given the file name.
83ac6b45
RS
587
588The @file{comint.el} file contains the following top-level expression:
589
590@smallexample
591(provide 'comint)
592@end smallexample
593
594@noindent
595This adds @code{comint} to the global @code{features} list, so that
596@code{(require 'comint)} will henceforth know that nothing needs to be
597done.
598
599@cindex byte-compiling @code{require}
78c71a98 600 When @code{require} is used at top level in a file, it takes effect
83ac6b45
RS
601when you byte-compile that file (@pxref{Byte Compilation}) as well as
602when you load it. This is in case the required package contains macros
8241495d
RS
603that the byte compiler must know about. It also avoids byte-compiler
604warnings for functions and variables defined in the file loaded with
605@code{require}.
83ac6b45
RS
606
607 Although top-level calls to @code{require} are evaluated during
608byte compilation, @code{provide} calls are not. Therefore, you can
609ensure that a file of definitions is loaded before it is byte-compiled
610by including a @code{provide} followed by a @code{require} for the same
611feature, as in the following example.
612
613@smallexample
614@group
615(provide 'my-feature) ; @r{Ignored by byte compiler,}
616 ; @r{evaluated by @code{load}.}
617(require 'my-feature) ; @r{Evaluated by byte compiler.}
618@end group
619@end smallexample
620
78c71a98
RS
621@noindent
622The compiler ignores the @code{provide}, then processes the
623@code{require} by loading the file in question. Loading the file does
624execute the @code{provide} call, so the subsequent @code{require} call
969fe9b5 625does nothing when the file is loaded.
78c71a98 626
83ac6b45
RS
627@defun provide feature
628This function announces that @var{feature} is now loaded, or being
629loaded, into the current Emacs session. This means that the facilities
630associated with @var{feature} are or will be available for other Lisp
631programs.
632
633The direct effect of calling @code{provide} is to add @var{feature} to
634the front of the list @code{features} if it is not already in the list.
635The argument @var{feature} must be a symbol. @code{provide} returns
636@var{feature}.
637
638@smallexample
639features
640 @result{} (bar bish)
641
642(provide 'foo)
643 @result{} foo
644features
645 @result{} (foo bar bish)
646@end smallexample
647
bfe721d1
KH
648When a file is loaded to satisfy an autoload, and it stops due to an
649error in the evaluating its contents, any function definitions or
650@code{provide} calls that occurred during the load are undone.
651@xref{Autoload}.
83ac6b45
RS
652@end defun
653
b6954afd 654@defun require feature &optional filename noerror
83ac6b45 655This function checks whether @var{feature} is present in the current
f9f59935
RS
656Emacs session (using @code{(featurep @var{feature})}; see below). The
657argument @var{feature} must be a symbol.
658
659If the feature is not present, then @code{require} loads @var{filename}
660with @code{load}. If @var{filename} is not supplied, then the name of
661the symbol @var{feature} is used as the base file name to load.
662However, in this case, @code{require} insists on finding @var{feature}
663with an added suffix; a file whose name is just @var{feature} won't be
664used.
83ac6b45
RS
665
666If loading the file fails to provide @var{feature}, @code{require}
667signals an error, @samp{Required feature @var{feature} was not
b6954afd 668provided}, unless @var{noerror} is non-@code{nil}.
83ac6b45
RS
669@end defun
670
671@defun featurep feature
672This function returns @code{t} if @var{feature} has been provided in the
969fe9b5 673current Emacs session (i.e., if @var{feature} is a member of
83ac6b45
RS
674@code{features}.)
675@end defun
676
677@defvar features
678The value of this variable is a list of symbols that are the features
679loaded in the current Emacs session. Each symbol was put in this list
680with a call to @code{provide}. The order of the elements in the
681@code{features} list is not significant.
682@end defvar
683
684@node Unloading
685@section Unloading
686@cindex unloading
687
688@c Emacs 19 feature
689 You can discard the functions and variables loaded by a library to
690reclaim memory for other Lisp objects. To do this, use the function
691@code{unload-feature}:
692
ee6bcc94 693@deffn Command unload-feature feature &optional force
83ac6b45 694This command unloads the library that provided feature @var{feature}.
78c71a98 695It undefines all functions, macros, and variables defined in that
969fe9b5
RS
696library with @code{defun}, @code{defalias}, @code{defsubst},
697@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
698It then restores any autoloads formerly associated with those symbols.
699(Loading saves these in the @code{autoload} property of the symbol.)
ee6bcc94 700
6582d61e
RS
701Before restoring the previous definitions, @code{unload-feature} runs
702@code{remove-hook} to remove functions in the library from certain
703hooks. These hooks include variables whose names end in @samp{hook} or
704@samp{-hooks}, plus those listed in @code{loadhist-special-hooks}. This
705is to prevent Emacs from ceasing to function because important hooks
706refer to functions that are no longer defined.
707
708@vindex @var{feature}-unload-hook
709If these measures are not sufficient to prevent malfunction, a library
710can define an explicit unload hook. If @code{@var{feature}-unload-hook}
711is defined, it is run as a normal hook before restoring the previous
712definitions, @emph{instead of} the usual hook-removing actions. The
713unload hook ought to undo all the global state changes made by the
714library that might cease to work once the library is unloaded.
8241495d
RS
715@code{unload-feature} can cause problems with libraries that fail to do
716this, so it should be used with caution.
6582d61e 717
ee6bcc94
RS
718Ordinarily, @code{unload-feature} refuses to unload a library on which
719other loaded libraries depend. (A library @var{a} depends on library
720@var{b} if @var{a} contains a @code{require} for @var{b}.) If the
721optional argument @var{force} is non-@code{nil}, dependencies are
722ignored and you can unload any library.
83ac6b45
RS
723@end deffn
724
725 The @code{unload-feature} function is written in Lisp; its actions are
726based on the variable @code{load-history}.
727
728@defvar load-history
729This variable's value is an alist connecting library names with the
730names of functions and variables they define, the features they provide,
731and the features they require.
732
733Each element is a list and describes one library. The @sc{car} of the
734list is the name of the library, as a string. The rest of the list is
735composed of these kinds of objects:
736
737@itemize @bullet
738@item
78c71a98 739Symbols that were defined by this library.
83ac6b45
RS
740@item
741Lists of the form @code{(require . @var{feature})} indicating
742features that were required.
743@item
744Lists of the form @code{(provide . @var{feature})} indicating
745features that were provided.
746@end itemize
747
748The value of @code{load-history} may have one element whose @sc{car} is
749@code{nil}. This element describes definitions made with
750@code{eval-buffer} on a buffer that is not visiting a file.
751@end defvar
752
753 The command @code{eval-region} updates @code{load-history}, but does so
754by adding the symbols defined to the element for the file being visited,
55607887 755rather than replacing that element. @xref{Eval}.
83ac6b45 756
8241495d
RS
757 Preloaded libraries don't contribute initially to @code{load-history}.
758Instead, preloading writes information about preloaded libraries into a
05aea714 759file, which can be loaded later on to add information to
8241495d
RS
760@code{load-history} describing the preloaded files. This file is
761installed in @code{exec-directory} and has a name of the form
762@file{fns-@var{emacsversion}.el}.
763
764@findex symbol-file
765 See the source for the function @code{symbol-file}, for an example of
766code that loads this file to find functions in preloaded libraries.
6582d61e 767
6582d61e
RS
768@defvar loadhist-special-hooks
769This variable holds a list of hooks to be scanned before unloading a
770library, to remove functions defined in the library.
771@end defvar
772
83ac6b45
RS
773@node Hooks for Loading
774@section Hooks for Loading
775@cindex loading hooks
776@cindex hooks for loading
777
778You can ask for code to be executed if and when a particular library is
779loaded, by calling @code{eval-after-load}.
780
781@defun eval-after-load library form
782This function arranges to evaluate @var{form} at the end of loading the
d2e9ee06
RS
783library @var{library}, if and when @var{library} is loaded. If
784@var{library} is already loaded, it evaluates @var{form} right away.
83ac6b45
RS
785
786The library name @var{library} must exactly match the argument of
787@code{load}. To get the proper results when an installed library is
788found by searching @code{load-path}, you should not include any
789directory names in @var{library}.
790
791An error in @var{form} does not undo the load, but does prevent
792execution of the rest of @var{form}.
793@end defun
794
d2e9ee06
RS
795In general, well-designed Lisp programs should not use this feature.
796The clean and modular ways to interact with a Lisp library are (1)
797examine and set the library's variables (those which are meant for
cc8c51f1 798outside use), and (2) call the library's functions. If you wish to
d2e9ee06
RS
799do (1), you can do it immediately---there is no need to wait for when
800the library is loaded. To do (2), you must load the library (preferably
801with @code{require}).
802
969fe9b5
RS
803But it is OK to use @code{eval-after-load} in your personal
804customizations if you don't feel they must meet the design standards for
805programs meant for wider use.
d2e9ee06 806
83ac6b45 807@defvar after-load-alist
8241495d
RS
808This variable holds an alist of expressions to evaluate if and when
809particular libraries are loaded. Each element looks like this:
83ac6b45
RS
810
811@example
812(@var{filename} @var{forms}@dots{})
813@end example
814
815The function @code{load} checks @code{after-load-alist} in order to
816implement @code{eval-after-load}.
817@end defvar
818
819@c Emacs 19 feature