2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/loading
6 @node Loading, Byte Compilation, Macros, Top
12 Loading a file of Lisp code means bringing its contents into the Lisp
13 environment in the form of Lisp objects. Emacs finds and opens the
14 file, reads the text, evaluates each form, and then closes the file.
16 The load functions evaluate all the expressions in a file just
17 as the @code{eval-current-buffer} function evaluates all the
18 expressions in a buffer. The difference is that the load functions
19 read and evaluate the text in the file as found on disk, not the text
22 @cindex top-level form
23 The loaded file must contain Lisp expressions, either as source code
24 or as byte-compiled code. Each form in the file is called a
25 @dfn{top-level form}. There is no special format for the forms in a
26 loadable file; any form in a file may equally well be typed directly
27 into a buffer and evaluated there. (Indeed, most code is tested this
28 way.) Most often, the forms are function definitions and variable
31 A file containing Lisp code is often called a @dfn{library}. Thus,
32 the ``Rmail library'' is a file containing code for Rmail mode.
33 Similarly, a ``Lisp library directory'' is a directory of files
37 * How Programs Do Loading:: The @code{load} function and others.
38 * Autoload:: Setting up a function to autoload.
39 * Repeated Loading:: Precautions about loading a file twice.
40 * Features:: Loading a library if it isn't already loaded.
41 * Unloading:: How to ``unload'' a library that was loaded.
42 * Hooks for Loading:: Providing code to be run when
43 particular libraries are loaded.
46 @node How Programs Do Loading
47 @section How Programs Do Loading
49 Emacs Lisp has several interfaces for loading. For example,
50 @code{autoload} creates a placeholder object for a function in a file;
51 trying to call the autoloading function loads the file to get the
52 function's real definition (@pxref{Autoload}). @code{require} loads a
53 file if it isn't already loaded (@pxref{Features}). Ultimately, all
54 these facilities call the @code{load} function to do the work.
56 @defun load filename &optional missing-ok nomessage nosuffix
57 This function finds and opens a file of Lisp code, evaluates all the
58 forms in it, and closes the file.
60 To find the file, @code{load} first looks for a file named
61 @file{@var{filename}.elc}, that is, for a file whose name is
62 @var{filename} with @samp{.elc} appended. If such a file exists, it is
63 loaded. If there is no file by that name, then @code{load} looks for a
64 file named @file{@var{filename}.el}. If that file exists, it is loaded.
65 Finally, if neither of those names is found, @code{load} looks for a
66 file named @var{filename} with nothing appended, and loads it if it
67 exists. (The @code{load} function is not clever about looking at
68 @var{filename}. In the perverse case of a file named @file{foo.el.el},
69 evaluation of @code{(load "foo.el")} will indeed find it.)
71 If the optional argument @var{nosuffix} is non-@code{nil}, then the
72 suffixes @samp{.elc} and @samp{.el} are not tried. In this case, you
73 must specify the precise file name you want.
75 If @var{filename} is a relative file name, such as @file{foo} or
76 @file{baz/foo.bar}, @code{load} searches for the file using the variable
77 @code{load-path}. It appends @var{filename} to each of the directories
78 listed in @code{load-path}, and loads the first file it finds whose name
79 matches. The current default directory is tried only if it is specified
80 in @code{load-path}, where @code{nil} stands for the default directory.
81 @code{load} tries all three possible suffixes in the first directory in
82 @code{load-path}, then all three suffixes in the second directory, and
85 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
86 means you should consider recompiling @file{foo.el}. @xref{Byte
89 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
90 in the echo area during loading unless @var{nomessage} is
94 Any unhandled errors while loading a file terminate loading. If the
95 load was done for the sake of @code{autoload}, any function definitions
96 made during the loading are undone.
99 If @code{load} can't find the file to load, then normally it signals the
100 error @code{file-error} (with @samp{Cannot open load file
101 @var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
102 @code{load} just returns @code{nil}.
104 @code{load} returns @code{t} if the file loads successfully.
108 @deffn Command load-file filename
109 This function loads the file @var{filename}. If @var{filename} is an
110 absolute file name, then it is loaded. If it is relative, then the
111 current default directory is assumed. @code{load-path} is not used, and
112 suffixes are not appended. Use this function if you wish to specify
113 the file to be loaded exactly.
116 @deffn Command load-library library
117 This function loads the library named @var{library}. A library is
118 nothing more than a file that may be loaded as described earlier. This
119 function is identical to @code{load}, save that it reads a file name
120 interactively with completion.
125 @cindex @code{EMACSLOADPATH} environment variable
126 The value of this variable is a list of directories to search when
127 loading files with @code{load}. Each element is a string (which must be
128 a directory name) or @code{nil} (which stands for the current working
129 directory). The value of @code{load-path} is initialized from the
130 environment variable @code{EMACSLOADPATH}, if that exists; otherwise its
131 default value is specified in @file{emacs/src/paths.h} when Emacs is
134 The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
135 @samp{:} separates directory names, and @samp{.} is used for the current
136 default directory. Here is an example of how to set your
137 @code{EMACSLOADPATH} variable from a @code{csh} @file{.login} file:
139 @c This overfull hbox is OK. --rjc 16mar92
141 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
144 Here is how to set it using @code{sh}:
148 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
151 Here is an example of code you can place in a @file{.emacs} file to add
152 several directories to the front of your default @code{load-path}:
156 (append (list nil "/user/bil/emacs"
158 (expand-file-name "~/emacs"))
162 @c Wordy to rid us of an overfull hbox. --rjc 15mar92
164 In this example, the path searches the current working directory first,
165 followed then by the @file{/user/bil/emacs} directory and then by
166 the @file{/usr/local/lisplib} directory,
167 which are then followed by the standard directories for Lisp code.
169 The command line options @samp{-l} or @samp{-load} specify a Lisp
170 library to load as part of Emacs startup. Since this file might be in
171 the current directory, Emacs 18 temporarily adds the current directory
172 to the front of @code{load-path} so the file can be found there. Newer
173 Emacs versions also find such files in the current directory, but
174 without altering @code{load-path}.
177 @defvar load-in-progress
178 This variable is non-@code{nil} if Emacs is in the process of loading a
179 file, and it is @code{nil} otherwise. This is how @code{defun} and
180 @code{provide} determine whether a load is in progress, so that their
181 effect can be undone if the load fails.
184 To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}.
190 The @dfn{autoload} facility allows you to make a function or macro
191 available but put off loading its actual definition. The first call to
192 the function automatically reads the proper file to install the real
193 definition and other associated code, then runs the real definition
194 as if it had been loaded all along.
196 There are two ways to set up an autoloaded function: by calling
197 @code{autoload}, and by writing a special ``magic'' comment in the
198 source before the real definition. @code{autoload} is the low-level
199 primitive for autoloading; any Lisp program can call @code{autoload} at
200 any time. Magic comments do nothing on their own; they serve as a guide
201 for the command @code{update-file-autoloads}, which constructs calls to
202 @code{autoload} and arranges to execute them when Emacs is built. Magic
203 comments are the most convenient way to make a function autoload, but
204 only for packages installed along with Emacs.
206 @defun autoload function filename &optional docstring interactive type
207 This function defines the function (or macro) named @var{function} so as
208 to load automatically from @var{filename}. The string @var{filename}
209 specifies the file to load to get the real definition of @var{function}.
211 The argument @var{docstring} is the documentation string for the
212 function. Normally, this is the identical to the documentation string
213 in the function definition itself. Specifying the documentation string
214 in the call to @code{autoload} makes it possible to look at the
215 documentation without loading the function's real definition.
217 If @var{interactive} is non-@code{nil}, then the function can be called
218 interactively. This lets completion in @kbd{M-x} work without loading
219 the function's real definition. The complete interactive specification
220 need not be given here; it's not needed unless the user actually calls
221 @var{function}, and when that happens, it's time to load the real
224 You can autoload macros and keymaps as well as ordinary functions.
225 Specify @var{type} as @code{macro} if @var{function} is really a macro.
226 Specify @var{type} as @code{keymap} if @var{function} is really a
227 keymap. Various parts of Emacs need to know this information without
228 loading the real definition.
230 @cindex function cell in autoload
231 If @var{function} already has a non-void function definition that is not
232 an autoload object, @code{autoload} does nothing and returns @code{nil}.
233 If the function cell of @var{function} is void, or is already an autoload
234 object, then it is defined as an autoload object like this:
237 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
243 (symbol-function 'run-prolog)
244 @result{} (autoload "prolog" 169681 t nil)
248 In this case, @code{"prolog"} is the name of the file to load, 169681
249 refers to the documentation string in the @file{emacs/etc/DOC} file
250 (@pxref{Documentation Basics}), @code{t} means the function is
251 interactive, and @code{nil} that it is not a macro or a keymap.
254 @cindex autoload errors
255 The autoloaded file usually contains other definitions and may require
256 or provide one or more features. If the file is not completely loaded
257 (due to an error in the evaluation of its contents), any function
258 definitions or @code{provide} calls that occurred during the load are
259 undone. This is to ensure that the next attempt to call any function
260 autoloading from this file will try again to load the file. If not for
261 this, then some of the functions in the file might appear defined, but
262 they might fail to work properly for the lack of certain subroutines
263 defined later in the file and not loaded successfully.
265 If the autoloaded file fails to define the desired Lisp function or
266 macro, then an error is signaled with data @code{"Autoloading failed to
267 define function @var{function-name}"}.
269 @findex update-file-autoloads
270 @findex update-directory-autoloads
271 A magic autoload comment looks like @samp{;;;###autoload}, on a line
272 by itself, just before the real definition of the function in its
273 autoloadable source file. The command @kbd{M-x update-file-autoloads}
274 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
275 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
276 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
277 autoloads for all files in the current directory.
279 The same magic comment can copy any kind of form into
280 @file{loaddefs.el}. If the form following the magic comment is not a
281 function definition, it is copied verbatim. You can also use a magic
282 comment to execute a form at build time @emph{without} executing it when
283 the file itself is loaded. To do this, write the form @dfn{on the same
284 line} as the magic comment. Since it is in a comment, it does nothing
285 when you load the source file; but @code{update-file-autoloads} copies
286 it to @file{loaddefs.el}, where it is executed while building Emacs.
288 The following example shows how @code{doctor} is prepared for
289 autoloading with a magic comment:
294 "Switch to *doctor* buffer and start giving psychotherapy."
296 (switch-to-buffer "*doctor*")
301 Here's what that produces in @file{loaddefs.el}:
304 (autoload 'doctor "doctor"
306 Switch to *doctor* buffer and start giving psychotherapy."
311 The backslash and newline immediately following the double-quote are a
312 convention used only in the preloaded Lisp files such as
313 @file{loaddefs.el}; they tell @code{make-docfile} to put the
314 documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
316 @node Repeated Loading
317 @comment node-name, next, previous, up
318 @section Repeated Loading
319 @cindex repeated loading
321 You may load one file more than once in an Emacs session. For
322 example, after you have rewritten and reinstalled a function definition
323 by editing it in a buffer, you may wish to return to the original
324 version; you can do this by reloading the file it came from.
326 When you load or reload files, bear in mind that the @code{load} and
327 @code{load-library} functions automatically load a byte-compiled file
328 rather than a non-compiled file of similar name. If you rewrite a file
329 that you intend to save and reinstall, remember to byte-compile it if
330 necessary; otherwise you may find yourself inadvertently reloading the
331 older, byte-compiled file instead of your newer, non-compiled file!
333 When writing the forms in a Lisp library file, keep in mind that the
334 file might be loaded more than once. For example, the choice of
335 @code{defvar} vs.@: @code{defconst} for defining a variable depends on
336 whether it is desirable to reinitialize the variable if the library is
337 reloaded: @code{defconst} does so, and @code{defvar} does not.
338 (@xref{Defining Variables}.)
340 The simplest way to add an element to an alist is like this:
343 (setq minor-mode-alist
344 (cons '(leif-mode " Leif") minor-mode-alist))
348 But this would add multiple elements if the library is reloaded.
349 To avoid the problem, write this:
352 (or (assq 'leif-mode minor-mode-alist)
353 (setq minor-mode-alist
354 (cons '(leif-mode " Leif") minor-mode-alist)))
357 Occasionally you will want to test explicitly whether a library has
358 already been loaded. Here's one way to test, in a library, whether it
359 has been loaded before:
362 (if (not (boundp 'foo-was-loaded))
363 @var{execute-first-time-only})
365 (setq foo-was-loaded t)
369 If the library uses @code{provide} to provide a named feature, you can
370 use @code{featurep} to test whether the library has been loaded.
378 @cindex requiring features
379 @cindex providing features
381 @code{provide} and @code{require} are an alternative to
382 @code{autoload} for loading files automatically. They work in terms of
383 named @dfn{features}. Autoloading is triggered by calling a specific
384 function, but a feature is loaded the first time another program asks
387 A feature name is a symbol that stands for a collection of functions,
388 variables, etc. The file that defines them should @dfn{provide} the
389 feature. Another program that uses them may ensure they are defined by
390 @dfn{requiring} the feature. This loads the file of definitions if it
391 hasn't been loaded already.
393 To require the presence of a feature, call @code{require} with the
394 feature name as argument. @code{require} looks in the global variable
395 @code{features} to see whether the desired feature has been provided
396 already. If not, it loads the feature from the appropriate file. This
397 file should call @code{provide} at the top level to add the feature to
398 @code{features}; if it fails to do so, @code{require} signals an error.
399 @cindex load error with require
401 Features are normally named after the files that provide them, so that
402 @code{require} need not be given the file name.
404 For example, in @file{emacs/lisp/prolog.el},
405 the definition for @code{run-prolog} includes the following code:
409 "Run an inferior Prolog process, input and output via buffer *prolog*."
412 (switch-to-buffer (make-comint "prolog" prolog-program-name))
413 (inferior-prolog-mode))
417 The expression @code{(require 'comint)} loads the file @file{comint.el}
418 if it has not yet been loaded. This ensures that @code{make-comint} is
421 The @file{comint.el} file contains the following top-level expression:
428 This adds @code{comint} to the global @code{features} list, so that
429 @code{(require 'comint)} will henceforth know that nothing needs to be
432 @cindex byte-compiling @code{require}
433 When @code{require} is used at top level in a file, it takes effect
434 when you byte-compile that file (@pxref{Byte Compilation}) as well as
435 when you load it. This is in case the required package contains macros
436 that the byte compiler must know about.
438 Although top-level calls to @code{require} are evaluated during
439 byte compilation, @code{provide} calls are not. Therefore, you can
440 ensure that a file of definitions is loaded before it is byte-compiled
441 by including a @code{provide} followed by a @code{require} for the same
442 feature, as in the following example.
446 (provide 'my-feature) ; @r{Ignored by byte compiler,}
447 ; @r{evaluated by @code{load}.}
448 (require 'my-feature) ; @r{Evaluated by byte compiler.}
453 The compiler ignores the @code{provide}, then processes the
454 @code{require} by loading the file in question. Loading the file does
455 execute the @code{provide} call, so the subsequent @code{require} call
456 does nothing while loading.
458 @defun provide feature
459 This function announces that @var{feature} is now loaded, or being
460 loaded, into the current Emacs session. This means that the facilities
461 associated with @var{feature} are or will be available for other Lisp
464 The direct effect of calling @code{provide} is to add @var{feature} to
465 the front of the list @code{features} if it is not already in the list.
466 The argument @var{feature} must be a symbol. @code{provide} returns
476 @result{} (foo bar bish)
479 If the file isn't completely loaded, due to an error in the evaluating
480 its contents, any function definitions or @code{provide} calls that
481 occurred during the load are undone. @xref{Autoload}.
484 @defun require feature &optional filename
485 This function checks whether @var{feature} is present in the current
486 Emacs session (using @code{(featurep @var{feature})}; see below). If it
487 is not, then @code{require} loads @var{filename} with @code{load}. If
488 @var{filename} is not supplied, then the name of the symbol
489 @var{feature} is used as the file name to load.
491 If loading the file fails to provide @var{feature}, @code{require}
492 signals an error, @samp{Required feature @var{feature} was not
496 @defun featurep feature
497 This function returns @code{t} if @var{feature} has been provided in the
498 current Emacs session (i.e., @var{feature} is a member of
503 The value of this variable is a list of symbols that are the features
504 loaded in the current Emacs session. Each symbol was put in this list
505 with a call to @code{provide}. The order of the elements in the
506 @code{features} list is not significant.
514 You can discard the functions and variables loaded by a library to
515 reclaim memory for other Lisp objects. To do this, use the function
516 @code{unload-feature}:
518 @deffn Command unload-feature feature
519 This command unloads the library that provided feature @var{feature}.
520 It undefines all functions, macros, and variables defined in that
521 library with @code{defconst}, @code{defvar}, @code{defun},
522 @code{defmacro}, @code{defsubst} and @code{defalias}. It then restores
523 any autoloads formerly associated with those symbols.
526 The @code{unload-feature} function is written in Lisp; its actions are
527 based on the variable @code{load-history}.
530 This variable's value is an alist connecting library names with the
531 names of functions and variables they define, the features they provide,
532 and the features they require.
534 Each element is a list and describes one library. The @sc{car} of the
535 list is the name of the library, as a string. The rest of the list is
536 composed of these kinds of objects:
540 Symbols that were defined by this library.
542 Lists of the form @code{(require . @var{feature})} indicating
543 features that were required.
545 Lists of the form @code{(provide . @var{feature})} indicating
546 features that were provided.
549 The value of @code{load-history} may have one element whose @sc{car} is
550 @code{nil}. This element describes definitions made with
551 @code{eval-buffer} on a buffer that is not visiting a file.
554 The command @code{eval-region} updates @code{load-history}, but does so
555 by adding the symbols defined to the element for the file being visited,
556 rather than replacing that element.
558 @node Hooks for Loading
559 @section Hooks for Loading
560 @cindex loading hooks
561 @cindex hooks for loading
563 You can ask for code to be executed if and when a particular library is
564 loaded, by calling @code{eval-after-load}.
566 @defun eval-after-load library form
567 This function arranges to evaluate @var{form} at the end of loading the
568 library @var{library}, if and when @var{library} is loaded.
570 The library name @var{library} must exactly match the argument of
571 @code{load}. To get the proper results when an installed library is
572 found by searching @code{load-path}, you should not include any
573 directory names in @var{library}.
575 An error in @var{form} does not undo the load, but does prevent
576 execution of the rest of @var{form}.
579 @defvar after-load-alist
580 An alist of expressions to evaluate if and when particular libraries are
581 loaded. Each element looks like this:
584 (@var{filename} @var{forms}@dots{})
587 The function @code{load} checks @code{after-load-alist} in order to
588 implement @code{eval-after-load}.