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}.
176 Dumping Emacs uses a special value of @code{load-path}. If the value of
177 @code{load-path} at the end of dumping is unchanged (that is, still the
178 same special value), the dumped Emacs switches to the ordinary
179 @code{load-path} value when it starts up, as decribed above. But if
180 @code{load-path} has any other value at the end of dumping, that value
181 is used for execution of the dumped Emacs also.
183 Therefore, if you want to change @code{load-path} temporarily for
184 loading a few libraries in @file{site-init.el} or @file{site-load.el},
185 you should bind @code{load-path} locally with @code{let} around the
186 calls to @code{load}.
189 @defvar load-in-progress
190 This variable is non-@code{nil} if Emacs is in the process of loading a
191 file, and it is @code{nil} otherwise. This is how @code{defun} and
192 @code{provide} determine whether a load is in progress, so that their
193 effect can be undone if the load fails.
196 To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}.
202 The @dfn{autoload} facility allows you to make a function or macro
203 available but put off loading its actual definition. The first call to
204 the function automatically reads the proper file to install the real
205 definition and other associated code, then runs the real definition
206 as if it had been loaded all along.
208 There are two ways to set up an autoloaded function: by calling
209 @code{autoload}, and by writing a special ``magic'' comment in the
210 source before the real definition. @code{autoload} is the low-level
211 primitive for autoloading; any Lisp program can call @code{autoload} at
212 any time. Magic comments do nothing on their own; they serve as a guide
213 for the command @code{update-file-autoloads}, which constructs calls to
214 @code{autoload} and arranges to execute them when Emacs is built. Magic
215 comments are the most convenient way to make a function autoload, but
216 only for packages installed along with Emacs.
218 @defun autoload function filename &optional docstring interactive type
219 This function defines the function (or macro) named @var{function} so as
220 to load automatically from @var{filename}. The string @var{filename}
221 specifies the file to load to get the real definition of @var{function}.
223 The argument @var{docstring} is the documentation string for the
224 function. Normally, this is the identical to the documentation string
225 in the function definition itself. Specifying the documentation string
226 in the call to @code{autoload} makes it possible to look at the
227 documentation without loading the function's real definition.
229 If @var{interactive} is non-@code{nil}, then the function can be called
230 interactively. This lets completion in @kbd{M-x} work without loading
231 the function's real definition. The complete interactive specification
232 need not be given here; it's not needed unless the user actually calls
233 @var{function}, and when that happens, it's time to load the real
236 You can autoload macros and keymaps as well as ordinary functions.
237 Specify @var{type} as @code{macro} if @var{function} is really a macro.
238 Specify @var{type} as @code{keymap} if @var{function} is really a
239 keymap. Various parts of Emacs need to know this information without
240 loading the real definition.
242 @cindex function cell in autoload
243 If @var{function} already has a non-void function definition that is not
244 an autoload object, @code{autoload} does nothing and returns @code{nil}.
245 If the function cell of @var{function} is void, or is already an autoload
246 object, then it is defined as an autoload object like this:
249 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
255 (symbol-function 'run-prolog)
256 @result{} (autoload "prolog" 169681 t nil)
260 In this case, @code{"prolog"} is the name of the file to load, 169681
261 refers to the documentation string in the @file{emacs/etc/DOC} file
262 (@pxref{Documentation Basics}), @code{t} means the function is
263 interactive, and @code{nil} that it is not a macro or a keymap.
266 @cindex autoload errors
267 The autoloaded file usually contains other definitions and may require
268 or provide one or more features. If the file is not completely loaded
269 (due to an error in the evaluation of its contents), any function
270 definitions or @code{provide} calls that occurred during the load are
271 undone. This is to ensure that the next attempt to call any function
272 autoloading from this file will try again to load the file. If not for
273 this, then some of the functions in the file might appear defined, but
274 they might fail to work properly for the lack of certain subroutines
275 defined later in the file and not loaded successfully.
277 If the autoloaded file fails to define the desired Lisp function or
278 macro, then an error is signaled with data @code{"Autoloading failed to
279 define function @var{function-name}"}.
281 @findex update-file-autoloads
282 @findex update-directory-autoloads
283 A magic autoload comment looks like @samp{;;;###autoload}, on a line
284 by itself, just before the real definition of the function in its
285 autoloadable source file. The command @kbd{M-x update-file-autoloads}
286 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
287 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
288 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
289 autoloads for all files in the current directory.
291 The same magic comment can copy any kind of form into
292 @file{loaddefs.el}. If the form following the magic comment is not a
293 function definition, it is copied verbatim. You can also use a magic
294 comment to execute a form at build time @emph{without} executing it when
295 the file itself is loaded. To do this, write the form @dfn{on the same
296 line} as the magic comment. Since it is in a comment, it does nothing
297 when you load the source file; but @code{update-file-autoloads} copies
298 it to @file{loaddefs.el}, where it is executed while building Emacs.
300 The following example shows how @code{doctor} is prepared for
301 autoloading with a magic comment:
306 "Switch to *doctor* buffer and start giving psychotherapy."
308 (switch-to-buffer "*doctor*")
313 Here's what that produces in @file{loaddefs.el}:
316 (autoload 'doctor "doctor"
318 Switch to *doctor* buffer and start giving psychotherapy."
323 The backslash and newline immediately following the double-quote are a
324 convention used only in the preloaded Lisp files such as
325 @file{loaddefs.el}; they tell @code{make-docfile} to put the
326 documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
328 @node Repeated Loading
329 @comment node-name, next, previous, up
330 @section Repeated Loading
331 @cindex repeated loading
333 You may load one file more than once in an Emacs session. For
334 example, after you have rewritten and reinstalled a function definition
335 by editing it in a buffer, you may wish to return to the original
336 version; you can do this by reloading the file it came from.
338 When you load or reload files, bear in mind that the @code{load} and
339 @code{load-library} functions automatically load a byte-compiled file
340 rather than a non-compiled file of similar name. If you rewrite a file
341 that you intend to save and reinstall, remember to byte-compile it if
342 necessary; otherwise you may find yourself inadvertently reloading the
343 older, byte-compiled file instead of your newer, non-compiled file!
345 When writing the forms in a Lisp library file, keep in mind that the
346 file might be loaded more than once. For example, the choice of
347 @code{defvar} vs.@: @code{defconst} for defining a variable depends on
348 whether it is desirable to reinitialize the variable if the library is
349 reloaded: @code{defconst} does so, and @code{defvar} does not.
350 (@xref{Defining Variables}.)
352 The simplest way to add an element to an alist is like this:
355 (setq minor-mode-alist
356 (cons '(leif-mode " Leif") minor-mode-alist))
360 But this would add multiple elements if the library is reloaded.
361 To avoid the problem, write this:
364 (or (assq 'leif-mode minor-mode-alist)
365 (setq minor-mode-alist
366 (cons '(leif-mode " Leif") minor-mode-alist)))
369 Occasionally you will want to test explicitly whether a library has
370 already been loaded. Here's one way to test, in a library, whether it
371 has been loaded before:
374 (if (not (boundp 'foo-was-loaded))
375 @var{execute-first-time-only})
377 (setq foo-was-loaded t)
381 If the library uses @code{provide} to provide a named feature, you can
382 use @code{featurep} to test whether the library has been loaded.
390 @cindex requiring features
391 @cindex providing features
393 @code{provide} and @code{require} are an alternative to
394 @code{autoload} for loading files automatically. They work in terms of
395 named @dfn{features}. Autoloading is triggered by calling a specific
396 function, but a feature is loaded the first time another program asks
399 A feature name is a symbol that stands for a collection of functions,
400 variables, etc. The file that defines them should @dfn{provide} the
401 feature. Another program that uses them may ensure they are defined by
402 @dfn{requiring} the feature. This loads the file of definitions if it
403 hasn't been loaded already.
405 To require the presence of a feature, call @code{require} with the
406 feature name as argument. @code{require} looks in the global variable
407 @code{features} to see whether the desired feature has been provided
408 already. If not, it loads the feature from the appropriate file. This
409 file should call @code{provide} at the top level to add the feature to
410 @code{features}; if it fails to do so, @code{require} signals an error.
411 @cindex load error with require
413 Features are normally named after the files that provide them, so that
414 @code{require} need not be given the file name.
416 For example, in @file{emacs/lisp/prolog.el},
417 the definition for @code{run-prolog} includes the following code:
421 "Run an inferior Prolog process, input and output via buffer *prolog*."
424 (switch-to-buffer (make-comint "prolog" prolog-program-name))
425 (inferior-prolog-mode))
429 The expression @code{(require 'comint)} loads the file @file{comint.el}
430 if it has not yet been loaded. This ensures that @code{make-comint} is
433 The @file{comint.el} file contains the following top-level expression:
440 This adds @code{comint} to the global @code{features} list, so that
441 @code{(require 'comint)} will henceforth know that nothing needs to be
444 @cindex byte-compiling @code{require}
445 When @code{require} is used at top level in a file, it takes effect
446 when you byte-compile that file (@pxref{Byte Compilation}) as well as
447 when you load it. This is in case the required package contains macros
448 that the byte compiler must know about.
450 Although top-level calls to @code{require} are evaluated during
451 byte compilation, @code{provide} calls are not. Therefore, you can
452 ensure that a file of definitions is loaded before it is byte-compiled
453 by including a @code{provide} followed by a @code{require} for the same
454 feature, as in the following example.
458 (provide 'my-feature) ; @r{Ignored by byte compiler,}
459 ; @r{evaluated by @code{load}.}
460 (require 'my-feature) ; @r{Evaluated by byte compiler.}
465 The compiler ignores the @code{provide}, then processes the
466 @code{require} by loading the file in question. Loading the file does
467 execute the @code{provide} call, so the subsequent @code{require} call
468 does nothing while loading.
470 @defun provide feature
471 This function announces that @var{feature} is now loaded, or being
472 loaded, into the current Emacs session. This means that the facilities
473 associated with @var{feature} are or will be available for other Lisp
476 The direct effect of calling @code{provide} is to add @var{feature} to
477 the front of the list @code{features} if it is not already in the list.
478 The argument @var{feature} must be a symbol. @code{provide} returns
488 @result{} (foo bar bish)
491 If the file isn't completely loaded, due to an error in the evaluating
492 its contents, any function definitions or @code{provide} calls that
493 occurred during the load are undone. @xref{Autoload}.
496 @defun require feature &optional filename
497 This function checks whether @var{feature} is present in the current
498 Emacs session (using @code{(featurep @var{feature})}; see below). If it
499 is not, then @code{require} loads @var{filename} with @code{load}. If
500 @var{filename} is not supplied, then the name of the symbol
501 @var{feature} is used as the file name to load.
503 If loading the file fails to provide @var{feature}, @code{require}
504 signals an error, @samp{Required feature @var{feature} was not
508 @defun featurep feature
509 This function returns @code{t} if @var{feature} has been provided in the
510 current Emacs session (i.e., @var{feature} is a member of
515 The value of this variable is a list of symbols that are the features
516 loaded in the current Emacs session. Each symbol was put in this list
517 with a call to @code{provide}. The order of the elements in the
518 @code{features} list is not significant.
526 You can discard the functions and variables loaded by a library to
527 reclaim memory for other Lisp objects. To do this, use the function
528 @code{unload-feature}:
530 @deffn Command unload-feature feature &optional force
531 This command unloads the library that provided feature @var{feature}.
532 It undefines all functions, macros, and variables defined in that
533 library with @code{defconst}, @code{defvar}, @code{defun},
534 @code{defmacro}, @code{defsubst} and @code{defalias}. It then restores
535 any autoloads formerly associated with those symbols.
537 Ordinarily, @code{unload-feature} refuses to unload a library on which
538 other loaded libraries depend. (A library @var{a} depends on library
539 @var{b} if @var{a} contains a @code{require} for @var{b}.) If the
540 optional argument @var{force} is non-@code{nil}, dependencies are
541 ignored and you can unload any library.
544 The @code{unload-feature} function is written in Lisp; its actions are
545 based on the variable @code{load-history}.
548 This variable's value is an alist connecting library names with the
549 names of functions and variables they define, the features they provide,
550 and the features they require.
552 Each element is a list and describes one library. The @sc{car} of the
553 list is the name of the library, as a string. The rest of the list is
554 composed of these kinds of objects:
558 Symbols that were defined by this library.
560 Lists of the form @code{(require . @var{feature})} indicating
561 features that were required.
563 Lists of the form @code{(provide . @var{feature})} indicating
564 features that were provided.
567 The value of @code{load-history} may have one element whose @sc{car} is
568 @code{nil}. This element describes definitions made with
569 @code{eval-buffer} on a buffer that is not visiting a file.
572 The command @code{eval-region} updates @code{load-history}, but does so
573 by adding the symbols defined to the element for the file being visited,
574 rather than replacing that element.
576 @node Hooks for Loading
577 @section Hooks for Loading
578 @cindex loading hooks
579 @cindex hooks for loading
581 You can ask for code to be executed if and when a particular library is
582 loaded, by calling @code{eval-after-load}.
584 @defun eval-after-load library form
585 This function arranges to evaluate @var{form} at the end of loading the
586 library @var{library}, if and when @var{library} is loaded.
588 The library name @var{library} must exactly match the argument of
589 @code{load}. To get the proper results when an installed library is
590 found by searching @code{load-path}, you should not include any
591 directory names in @var{library}.
593 An error in @var{form} does not undo the load, but does prevent
594 execution of the rest of @var{form}.
597 @defvar after-load-alist
598 An alist of expressions to evaluate if and when particular libraries are
599 loaded. Each element looks like this:
602 (@var{filename} @var{forms}@dots{})
605 The function @code{load} checks @code{after-load-alist} in order to
606 implement @code{eval-after-load}.