2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
12 Loading a file of Lisp code means bringing its contents into the
13 Lisp environment in the form of Lisp objects. Emacs finds and opens
14 the file, reads the text, evaluates each form, and then closes the
15 file. Such a file is also called a @dfn{Lisp library}.
17 The load functions evaluate all the expressions in a file just
18 as the @code{eval-buffer} function evaluates all the
19 expressions in a buffer. The difference is that the load functions
20 read and evaluate the text in the file as found on disk, not the text
23 @cindex top-level form
24 The loaded file must contain Lisp expressions, either as source code
25 or 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
27 loadable file; any form in a file may equally well be typed directly
28 into a buffer and evaluated there. (Indeed, most code is tested this
29 way.) Most often, the forms are function definitions and variable
33 * How Programs Do Loading:: The @code{load} function and others.
34 * Load Suffixes:: Details about the suffixes that @code{load} tries.
35 * Library Search:: Finding a library to load.
36 * Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files.
37 * Autoload:: Setting up a function to autoload.
38 * Repeated Loading:: Precautions about loading a file twice.
39 * Named Features:: Loading a library if it isn't already loaded.
40 * Where Defined:: Finding which file defined a certain symbol.
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 defined in a
51 file; 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{Named Features}). Ultimately,
54 all these facilities call the @code{load} function to do the work.
56 @defun load filename &optional missing-ok nomessage nosuffix must-suffix
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 the extension @samp{.elc} appended. If such a
63 file exists, it is loaded. If there is no file by that name, then
64 @code{load} looks for a file named @file{@var{filename}.el}. If that
65 file exists, it is loaded. Finally, if neither of those names is
66 found, @code{load} looks for a file named @var{filename} with nothing
67 appended, and loads it if it exists. (The @code{load} function is not
68 clever about looking at @var{filename}. In the perverse case of a
69 file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will
72 If Auto Compression mode is enabled, as it is by default, then if
73 @code{load} can not find a file, it searches for a compressed version
74 of the file before trying other file names. It decompresses and loads
75 it if it exists. It looks for compressed versions by appending each
76 of the suffixes in @code{jka-compr-load-suffixes} to the file name.
77 The value of this variable must be a list of strings. Its standard
78 value is @code{(".gz")}.
80 If the optional argument @var{nosuffix} is non-@code{nil}, then
81 @code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In
82 this case, you must specify the precise file name you want, except
83 that, if Auto Compression mode is enabled, @code{load} will still use
84 @code{jka-compr-load-suffixes} to find compressed versions. By
85 specifying the precise file name and using @code{t} for
86 @var{nosuffix}, you can prevent file names like @file{foo.el.el} from
89 If the optional argument @var{must-suffix} is non-@code{nil}, then
90 @code{load} insists that the file name used must end in either
91 @samp{.el} or @samp{.elc} (possibly extended with a compression
92 suffix), unless it contains an explicit directory name.
94 If @var{filename} is a relative file name, such as @file{foo} or
95 @file{baz/foo.bar}, @code{load} searches for the file using the variable
96 @code{load-path}. It appends @var{filename} to each of the directories
97 listed in @code{load-path}, and loads the first file it finds whose name
98 matches. The current default directory is tried only if it is specified
99 in @code{load-path}, where @code{nil} stands for the default directory.
100 @code{load} tries all three possible suffixes in the first directory in
101 @code{load-path}, then all three suffixes in the second directory, and
102 so on. @xref{Library Search}.
104 Whatever the name under which the file is eventually found, and the
105 directory where Emacs found it, Emacs sets the value of the variable
106 @code{load-file-name} to that file's name.
108 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
109 means you should consider recompiling @file{foo.el}. @xref{Byte
112 When loading a source file (not compiled), @code{load} performs
113 character set translation just as Emacs would do when visiting the file.
114 @xref{Coding Systems}.
116 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
117 in the echo area during loading unless @var{nomessage} is
121 Any unhandled errors while loading a file terminate loading. If the
122 load was done for the sake of @code{autoload}, any function definitions
123 made during the loading are undone.
126 If @code{load} can't find the file to load, then normally it signals the
127 error @code{file-error} (with @samp{Cannot open load file
128 @var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
129 @code{load} just returns @code{nil}.
131 You can use the variable @code{load-read-function} to specify a function
132 for @code{load} to use instead of @code{read} for reading expressions.
135 @code{load} returns @code{t} if the file loads successfully.
138 @deffn Command load-file filename
139 This command loads the file @var{filename}. If @var{filename} is a
140 relative file name, then the current default directory is assumed.
141 This command does not use @code{load-path}, and does not append
142 suffixes. However, it does look for compressed versions (if Auto
143 Compression Mode is enabled). Use this command if you wish to specify
144 precisely the file name to load.
147 @deffn Command load-library library
148 This command loads the library named @var{library}. It is equivalent to
149 @code{load}, except for the way it reads its argument interactively.
150 @xref{Lisp Libraries,,,emacs, The GNU Emacs Manual}.
153 @defvar load-in-progress
154 This variable is non-@code{nil} if Emacs is in the process of loading a
155 file, and it is @code{nil} otherwise.
158 @defvar load-file-name
159 When Emacs is in the process of loading a file, this variable's value
160 is the name of that file, as Emacs found it during the search
161 described earlier in this section.
164 @defvar load-read-function
165 @anchor{Definition of load-read-function}
166 @c do not allow page break at anchor; work around Texinfo deficiency.
167 This variable specifies an alternate expression-reading function for
168 @code{load} and @code{eval-region} to use instead of @code{read}.
169 The function should accept one argument, just as @code{read} does.
171 Normally, the variable's value is @code{nil}, which means those
172 functions should use @code{read}.
174 Instead of using this variable, it is cleaner to use another, newer
175 feature: to pass the function as the @var{read-function} argument to
176 @code{eval-region}. @xref{Definition of eval-region,, Eval}.
179 For information about how @code{load} is used in building Emacs, see
180 @ref{Building Emacs}.
183 @section Load Suffixes
184 We now describe some technical details about the exact suffixes that
187 @defvar load-suffixes
188 This is a list of suffixes indicating (compiled or source) Emacs Lisp
189 files. It should not include the empty string. @code{load} uses
190 these suffixes in order when it appends Lisp suffixes to the specified
191 file name. The standard value is @code{(".elc" ".el")} which produces
192 the behavior described in the previous section.
195 @defvar load-file-rep-suffixes
196 This is a list of suffixes that indicate representations of the same
197 file. This list should normally start with the empty string.
198 When @code{load} searches for a file it appends the suffixes in this
199 list, in order, to the file name, before searching for another file.
201 Enabling Auto Compression mode appends the suffixes in
202 @code{jka-compr-load-suffixes} to this list and disabling Auto
203 Compression mode removes them again. The standard value of
204 @code{load-file-rep-suffixes} if Auto Compression mode is disabled is
205 @code{("")}. Given that the standard value of
206 @code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value
207 of @code{load-file-rep-suffixes} if Auto Compression mode is enabled
208 is @code{("" ".gz")}.
211 @defun get-load-suffixes
212 This function returns the list of all suffixes that @code{load} should
213 try, in order, when its @var{must-suffix} argument is non-@code{nil}.
214 This takes both @code{load-suffixes} and @code{load-file-rep-suffixes}
215 into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes}
216 and @code{load-file-rep-suffixes} all have their standard values, this
217 function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto
218 Compression mode is enabled and @code{(".elc" ".el")} if Auto
219 Compression mode is disabled.
222 To summarize, @code{load} normally first tries the suffixes in the
223 value of @code{(get-load-suffixes)} and then those in
224 @code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil},
225 it skips the former group, and if @var{must-suffix} is non-@code{nil},
226 it skips the latter group.
229 @section Library Search
230 @cindex library search
233 When Emacs loads a Lisp library, it searches for the library
234 in a list of directories specified by the variable @code{load-path}.
237 @cindex @env{EMACSLOADPATH} environment variable
238 The value of this variable is a list of directories to search when
239 loading files with @code{load}. Each element is a string (which must be
240 a directory name) or @code{nil} (which stands for the current working
244 Each time Emacs starts up, it sets up the value of @code{load-path}
245 in several steps. First, it initializes @code{load-path} to the
246 directories specified by the environment variable @env{EMACSLOADPATH},
247 if that exists. The syntax of @env{EMACSLOADPATH} is the same as used
248 for @code{PATH}; directory names are separated by @samp{:} (or
249 @samp{;}, on some operating systems), and @samp{.} stands for the
250 current default directory. Here is an example of how to set
251 @env{EMACSLOADPATH} variable from @command{sh}:
255 EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
259 Here is how to set it from @code{csh}:
262 setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
265 @cindex site-lisp directories
266 If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs
267 initializes @code{load-path} with the following two directories:
270 "/usr/local/share/emacs/@var{version}/site-lisp"
277 "/usr/local/share/emacs/site-lisp"
281 The first one is for locally installed packages for a particular Emacs
282 version; the second is for locally installed packages meant for use
283 with all installed Emacs versions.
285 If you run Emacs from the directory where it was built---that is, an
286 executable that has not been formally installed---Emacs puts two more
287 directories in @code{load-path}. These are the @code{lisp} and
288 @code{site-lisp} subdirectories of the main build directory. (Both
289 are represented as absolute file names.)
291 Next, Emacs ``expands'' the initial list of directories in
292 @code{load-path} by adding the subdirectories of those directories.
293 Both immediate subdirectories and subdirectories multiple levels down
294 are added. But it excludes subdirectories whose names do not start
295 with a letter or digit, and subdirectories named @file{RCS} or
296 @file{CVS}, and subdirectories containing a file named
299 Next, Emacs adds any extra load directory that you specify using the
300 @samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The
301 GNU Emacs Manual}). It also adds the directories where optional
302 packages are installed, if any (@pxref{Packaging Basics}).
304 It is common to add code to one's init file (@pxref{Init File}) to
305 add one or more directories to @code{load-path}. For example:
308 (push "~/.emacs.d/lisp" load-path)
311 Dumping Emacs uses a special value of @code{load-path}. If the
312 value of @code{load-path} at the end of dumping is unchanged (that is,
313 still the same special value), the dumped Emacs switches to the
314 ordinary @code{load-path} value when it starts up, as described above.
315 But if @code{load-path} has any other value at the end of dumping,
316 that value is used for execution of the dumped Emacs also.
318 @deffn Command locate-library library &optional nosuffix path interactive-call
319 This command finds the precise file name for library @var{library}. It
320 searches for the library in the same way @code{load} does, and the
321 argument @var{nosuffix} has the same meaning as in @code{load}: don't
322 add suffixes @samp{.elc} or @samp{.el} to the specified name
325 If the @var{path} is non-@code{nil}, that list of directories is used
326 instead of @code{load-path}.
328 When @code{locate-library} is called from a program, it returns the file
329 name as a string. When the user runs @code{locate-library}
330 interactively, the argument @var{interactive-call} is @code{t}, and this
331 tells @code{locate-library} to display the file name in the echo area.
334 @cindex shadowed Lisp files
335 @deffn Command list-load-path-shadows &optional stringp
336 This command shows a list of @dfn{shadowed} Emacs Lisp files. A
337 shadowed file is one that will not normally be loaded, despite being
338 in a directory on @code{load-path}, due to the existence of another
339 similarly-named file in a directory earlier on @code{load-path}.
341 For instance, suppose @code{load-path} is set to
344 ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
348 and that both these directories contain a file named @file{foo.el}.
349 Then @code{(require 'foo)} never loads the file in the second
350 directory. Such a situation might indicate a problem in the way Emacs
353 When called from Lisp, this function prints a message listing the
354 shadowed files, instead of displaying them in a buffer. If the
355 optional argument @code{stringp} is non-@code{nil}, it instead returns
356 the shadowed files as a string.
359 @node Loading Non-ASCII
360 @section Loading Non-@acronym{ASCII} Characters
362 When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
363 characters, these can be represented within Emacs either as unibyte
364 strings or as multibyte strings (@pxref{Text Representations}). Which
365 representation is used depends on how the file is read into Emacs. If
366 it is read with decoding into multibyte representation, the text of the
367 Lisp program will be multibyte text, and its string constants will be
368 multibyte strings. If a file containing Latin-1 characters (for
369 example) is read without decoding, the text of the program will be
370 unibyte text, and its string constants will be unibyte strings.
371 @xref{Coding Systems}.
373 In most Emacs Lisp programs, the fact that non-@acronym{ASCII}
374 strings are multibyte strings should not be noticeable, since
375 inserting them in unibyte buffers converts them to unibyte
376 automatically. However, if this does make a difference, you can force
377 a particular Lisp file to be interpreted as unibyte by writing
378 @samp{coding: raw-text} in a local variables section. With
379 that designator, the file will unconditionally be interpreted as
380 unibyte. This can matter when making keybindings to
381 non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
387 The @dfn{autoload} facility allows you to register the existence of
388 a function or macro, but put off loading the file that defines it.
389 The first call to the function automatically reads the proper file, in
390 order to install the real definition and other associated code, then
391 runs the real definition as if it had been loaded all along.
393 There are two ways to set up an autoloaded function: by calling
394 @code{autoload}, and by writing a special ``magic'' comment in the
395 source before the real definition. @code{autoload} is the low-level
396 primitive for autoloading; any Lisp program can call @code{autoload} at
397 any time. Magic comments are the most convenient way to make a function
398 autoload, for packages installed along with Emacs. These comments do
399 nothing on their own, but they serve as a guide for the command
400 @code{update-file-autoloads}, which constructs calls to @code{autoload}
401 and arranges to execute them when Emacs is built.
403 @defun autoload function filename &optional docstring interactive type
404 This function defines the function (or macro) named @var{function} so as
405 to load automatically from @var{filename}. The string @var{filename}
406 specifies the file to load to get the real definition of @var{function}.
408 If @var{filename} does not contain either a directory name, or the
409 suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
410 one of these suffixes, and it will not load from a file whose name is
411 just @var{filename} with no added suffix. (The variable
412 @code{load-suffixes} specifies the exact required suffixes.)
414 The argument @var{docstring} is the documentation string for the
415 function. Specifying the documentation string in the call to
416 @code{autoload} makes it possible to look at the documentation without
417 loading the function's real definition. Normally, this should be
418 identical to the documentation string in the function definition
419 itself. If it isn't, the function definition's documentation string
420 takes effect when it is loaded.
422 If @var{interactive} is non-@code{nil}, that says @var{function} can be
423 called interactively. This lets completion in @kbd{M-x} work without
424 loading @var{function}'s real definition. The complete interactive
425 specification is not given here; it's not needed unless the user
426 actually calls @var{function}, and when that happens, it's time to load
429 You can autoload macros and keymaps as well as ordinary functions.
430 Specify @var{type} as @code{macro} if @var{function} is really a macro.
431 Specify @var{type} as @code{keymap} if @var{function} is really a
432 keymap. Various parts of Emacs need to know this information without
433 loading the real definition.
435 An autoloaded keymap loads automatically during key lookup when a prefix
436 key's binding is the symbol @var{function}. Autoloading does not occur
437 for other kinds of access to the keymap. In particular, it does not
438 happen when a Lisp program gets the keymap from the value of a variable
439 and calls @code{define-key}; not even if the variable name is the same
440 symbol @var{function}.
442 @cindex function cell in autoload
443 If @var{function} already has a non-void function definition that is not
444 an autoload object, @code{autoload} does nothing and returns @code{nil}.
445 If the function cell of @var{function} is void, or is already an autoload
446 object, then it is defined as an autoload object like this:
449 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
456 (symbol-function 'run-prolog)
457 @result{} (autoload "prolog" 169681 t nil)
462 In this case, @code{"prolog"} is the name of the file to load, 169681
463 refers to the documentation string in the
464 @file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
465 @code{t} means the function is interactive, and @code{nil} that it is
466 not a macro or a keymap.
469 @cindex autoload errors
470 The autoloaded file usually contains other definitions and may require
471 or provide one or more features. If the file is not completely loaded
472 (due to an error in the evaluation of its contents), any function
473 definitions or @code{provide} calls that occurred during the load are
474 undone. This is to ensure that the next attempt to call any function
475 autoloading from this file will try again to load the file. If not for
476 this, then some of the functions in the file might be defined by the
477 aborted load, but fail to work properly for the lack of certain
478 subroutines not loaded successfully because they come later in the file.
480 If the autoloaded file fails to define the desired Lisp function or
481 macro, then an error is signaled with data @code{"Autoloading failed to
482 define function @var{function-name}"}.
484 @findex update-file-autoloads
485 @findex update-directory-autoloads
486 @cindex magic autoload comment
487 @cindex autoload cookie
488 @anchor{autoload cookie}
489 A magic autoload comment (often called an @dfn{autoload cookie})
490 consists of @samp{;;;###autoload}, on a line by itself,
491 just before the real definition of the function in its
492 autoloadable source file. The command @kbd{M-x update-file-autoloads}
493 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
494 (The string that serves as the autoload cookie and the name of the
495 file generated by @code{update-file-autoloads} can be changed from the
496 above defaults, see below.)
497 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
498 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
499 autoloads for all files in the current directory.
501 The same magic comment can copy any kind of form into
502 @file{loaddefs.el}. The form following the magic comment is copied
503 verbatim, @emph{except} if it is one of the forms which the autoload
504 facility handles specially (e.g.@: by conversion into an
505 @code{autoload} call). The forms which are not copied verbatim are
509 @item Definitions for function or function-like objects:
510 @code{defun} and @code{defmacro}; also @code{defun*} and
511 @code{defmacro*} (@pxref{Argument Lists,,,cl,CL Manual}), and
512 @code{define-overloadable-function} (see the commentary in
513 @file{mode-local.el}).
515 @item Definitions for major or minor modes:
516 @code{define-minor-mode}, @code{define-globalized-minor-mode},
517 @code{define-generic-mode}, @code{define-derived-mode},
518 @code{easy-mmode-define-minor-mode},
519 @code{easy-mmode-define-global-mode}, @code{define-compilation-mode},
520 and @code{define-global-minor-mode}.
522 @item Other definition types:
523 @code{defcustom}, @code{defgroup}, @code{defclass}
524 (@pxref{Top,EIEIO,,eieio,EIEIO}), and @code{define-skeleton} (see the
525 commentary in @file{skeleton.el}).
528 You can also use a magic comment to execute a form at build time
529 @emph{without} executing it when the file itself is loaded. To do this,
530 write the form @emph{on the same line} as the magic comment. Since it
531 is in a comment, it does nothing when you load the source file; but
532 @kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
533 it is executed while building Emacs.
535 The following example shows how @code{doctor} is prepared for
536 autoloading with a magic comment:
541 "Switch to *doctor* buffer and start giving psychotherapy."
543 (switch-to-buffer "*doctor*")
548 Here's what that produces in @file{loaddefs.el}:
551 (autoload (quote doctor) "doctor" "\
552 Switch to *doctor* buffer and start giving psychotherapy.
558 @cindex @code{fn} in function's documentation string
559 The backslash and newline immediately following the double-quote are a
560 convention used only in the preloaded uncompiled Lisp files such as
561 @file{loaddefs.el}; they tell @code{make-docfile} to put the
562 documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
563 See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)}
564 in the usage part of the documentation string is replaced with the
565 function's name when the various help functions (@pxref{Help
566 Functions}) display it.
568 If you write a function definition with an unusual macro that is not
569 one of the known and recognized function definition methods, use of an
570 ordinary magic autoload comment would copy the whole definition into
571 @code{loaddefs.el}. That is not desirable. You can put the desired
572 @code{autoload} call into @code{loaddefs.el} instead by writing this:
575 ;;;###autoload (autoload 'foo "myfile")
580 You can use a non-default string as the autoload cookie and have the
581 corresponding autoload calls written into a file whose name is
582 different from the default @file{loaddefs.el}. Emacs provides two
583 variables to control this:
585 @defvar generate-autoload-cookie
586 The value of this variable should be a string whose syntax is a Lisp
587 comment. @kbd{M-x update-file-autoloads} copies the Lisp form that
588 follows the cookie into the autoload file it generates. The default
589 value of this variable is @code{";;;###autoload"}.
592 @defvar generated-autoload-file
593 The value of this variable names an Emacs Lisp file where the autoload
594 calls should go. The default value is @file{loaddefs.el}, but you can
595 override that, e.g., in the ``Local Variables'' section of a
596 @file{.el} file (@pxref{File Local Variables}). The autoload file is
597 assumed to contain a trailer starting with a formfeed character.
600 @node Repeated Loading
601 @section Repeated Loading
602 @cindex repeated loading
604 You can load a given file more than once in an Emacs session. For
605 example, after you have rewritten and reinstalled a function definition
606 by editing it in a buffer, you may wish to return to the original
607 version; you can do this by reloading the file it came from.
609 When you load or reload files, bear in mind that the @code{load} and
610 @code{load-library} functions automatically load a byte-compiled file
611 rather than a non-compiled file of similar name. If you rewrite a file
612 that you intend to save and reinstall, you need to byte-compile the new
613 version; otherwise Emacs will load the older, byte-compiled file instead
614 of your newer, non-compiled file! If that happens, the message
615 displayed when loading the file includes, @samp{(compiled; note, source is
616 newer)}, to remind you to recompile it.
618 When writing the forms in a Lisp library file, keep in mind that the
619 file might be loaded more than once. For example, think about whether
620 each variable should be reinitialized when you reload the library;
621 @code{defvar} does not change the value if the variable is already
622 initialized. (@xref{Defining Variables}.)
624 The simplest way to add an element to an alist is like this:
627 (push '(leif-mode " Leif") minor-mode-alist)
631 But this would add multiple elements if the library is reloaded. To
632 avoid the problem, use @code{add-to-list} (@pxref{List Variables}):
635 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
638 Occasionally you will want to test explicitly whether a library has
639 already been loaded. If the library uses @code{provide} to provide a
640 named feature, you can use @code{featurep} earlier in the file to test
641 whether the @code{provide} call has been executed before (@pxref{Named
642 Features}). Alternatively, you could use something like this:
645 (defvar foo-was-loaded nil)
647 (unless foo-was-loaded
648 @var{execute-first-time-only}
649 (setq foo-was-loaded t))
657 @cindex requiring features
658 @cindex providing features
660 @code{provide} and @code{require} are an alternative to
661 @code{autoload} for loading files automatically. They work in terms of
662 named @dfn{features}. Autoloading is triggered by calling a specific
663 function, but a feature is loaded the first time another program asks
666 A feature name is a symbol that stands for a collection of functions,
667 variables, etc. The file that defines them should @dfn{provide} the
668 feature. Another program that uses them may ensure they are defined by
669 @dfn{requiring} the feature. This loads the file of definitions if it
670 hasn't been loaded already.
672 @cindex load error with require
673 To require the presence of a feature, call @code{require} with the
674 feature name as argument. @code{require} looks in the global variable
675 @code{features} to see whether the desired feature has been provided
676 already. If not, it loads the feature from the appropriate file. This
677 file should call @code{provide} at the top level to add the feature to
678 @code{features}; if it fails to do so, @code{require} signals an error.
680 For example, in @file{idlwave.el}, the definition for
681 @code{idlwave-complete-filename} includes the following code:
684 (defun idlwave-complete-filename ()
685 "Use the comint stuff to complete a file name."
687 (let* ((comint-file-name-chars "~/A-Za-z0-9+@:_.$#%=@{@}\\-")
688 (comint-completion-addsuffix nil)
690 (comint-dynamic-complete-filename)))
694 The expression @code{(require 'comint)} loads the file @file{comint.el}
695 if it has not yet been loaded, ensuring that
696 @code{comint-dynamic-complete-filename} is defined. Features are
697 normally named after the files that provide them, so that
698 @code{require} need not be given the file name. (Note that it is
699 important that the @code{require} statement be outside the body of the
700 @code{let}. Loading a library while its variables are let-bound can
701 have unintended consequences, namely the variables becoming unbound
702 after the let exits.)
704 The @file{comint.el} file contains the following top-level expression:
711 This adds @code{comint} to the global @code{features} list, so that
712 @code{(require 'comint)} will henceforth know that nothing needs to be
715 @cindex byte-compiling @code{require}
716 When @code{require} is used at top level in a file, it takes effect
717 when you byte-compile that file (@pxref{Byte Compilation}) as well as
718 when you load it. This is in case the required package contains macros
719 that the byte compiler must know about. It also avoids byte compiler
720 warnings for functions and variables defined in the file loaded with
723 Although top-level calls to @code{require} are evaluated during
724 byte compilation, @code{provide} calls are not. Therefore, you can
725 ensure that a file of definitions is loaded before it is byte-compiled
726 by including a @code{provide} followed by a @code{require} for the same
727 feature, as in the following example.
731 (provide 'my-feature) ; @r{Ignored by byte compiler,}
732 ; @r{evaluated by @code{load}.}
733 (require 'my-feature) ; @r{Evaluated by byte compiler.}
738 The compiler ignores the @code{provide}, then processes the
739 @code{require} by loading the file in question. Loading the file does
740 execute the @code{provide} call, so the subsequent @code{require} call
741 does nothing when the file is loaded.
743 @defun provide feature &optional subfeatures
744 This function announces that @var{feature} is now loaded, or being
745 loaded, into the current Emacs session. This means that the facilities
746 associated with @var{feature} are or will be available for other Lisp
749 The direct effect of calling @code{provide} is if not already in
750 @var{features} then to add @var{feature} to the front of that list and
751 call any @code{eval-after-load} code waiting for it (@pxref{Hooks for
752 Loading}). The argument @var{feature} must be a symbol.
753 @code{provide} returns @var{feature}.
755 If provided, @var{subfeatures} should be a list of symbols indicating
756 a set of specific subfeatures provided by this version of
757 @var{feature}. You can test the presence of a subfeature using
758 @code{featurep}. The idea of subfeatures is that you use them when a
759 package (which is one @var{feature}) is complex enough to make it
760 useful to give names to various parts or functionalities of the
761 package, which might or might not be loaded, or might or might not be
762 present in a given version. @xref{Network Feature Testing}, for
772 @result{} (foo bar bish)
775 When a file is loaded to satisfy an autoload, and it stops due to an
776 error in the evaluation of its contents, any function definitions or
777 @code{provide} calls that occurred during the load are undone.
781 @defun require feature &optional filename noerror
782 This function checks whether @var{feature} is present in the current
783 Emacs session (using @code{(featurep @var{feature})}; see below). The
784 argument @var{feature} must be a symbol.
786 If the feature is not present, then @code{require} loads @var{filename}
787 with @code{load}. If @var{filename} is not supplied, then the name of
788 the symbol @var{feature} is used as the base file name to load.
789 However, in this case, @code{require} insists on finding @var{feature}
790 with an added @samp{.el} or @samp{.elc} suffix (possibly extended with
791 a compression suffix); a file whose name is just @var{feature} won't
792 be used. (The variable @code{load-suffixes} specifies the exact
793 required Lisp suffixes.)
795 If @var{noerror} is non-@code{nil}, that suppresses errors from actual
796 loading of the file. In that case, @code{require} returns @code{nil}
797 if loading the file fails. Normally, @code{require} returns
800 If loading the file succeeds but does not provide @var{feature},
801 @code{require} signals an error, @samp{Required feature @var{feature}
805 @defun featurep feature &optional subfeature
806 This function returns @code{t} if @var{feature} has been provided in
807 the current Emacs session (i.e.@:, if @var{feature} is a member of
808 @code{features}.) If @var{subfeature} is non-@code{nil}, then the
809 function returns @code{t} only if that subfeature is provided as well
810 (i.e.@: if @var{subfeature} is a member of the @code{subfeature}
811 property of the @var{feature} symbol.)
815 The value of this variable is a list of symbols that are the features
816 loaded in the current Emacs session. Each symbol was put in this list
817 with a call to @code{provide}. The order of the elements in the
818 @code{features} list is not significant.
822 @section Which File Defined a Certain Symbol
824 @defun symbol-file symbol &optional type
825 This function returns the name of the file that defined @var{symbol}.
826 If @var{type} is @code{nil}, then any kind of definition is acceptable.
827 If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that
828 specifies function definition, variable definition, or face definition
831 The value is normally an absolute file name. It can also be @code{nil},
832 if the definition is not associated with any file. If @var{symbol}
833 specifies an autoloaded function, the value can be a relative file name
837 The basis for @code{symbol-file} is the data in the variable
841 The value of this variable is an alist that associates the names of
842 loaded library files with the names of the functions and variables
843 they defined, as well as the features they provided or required.
845 Each element in this alist describes one loaded library (including
846 libraries that are preloaded at startup). It is a list whose @sc{car}
847 is the absolute file name of the library (a string). The rest of the
848 list elements have these forms:
852 The symbol @var{var} was defined as a variable.
853 @item (defun . @var{fun})
854 The function @var{fun} was defined.
855 @item (t . @var{fun})
856 The function @var{fun} was previously an autoload before this library
857 redefined it as a function. The following element is always
858 @code{(defun . @var{fun})}, which represents defining @var{fun} as a
860 @item (autoload . @var{fun})
861 The function @var{fun} was defined as an autoload.
862 @item (defface . @var{face})
863 The face @var{face} was defined.
864 @item (require . @var{feature})
865 The feature @var{feature} was required.
866 @item (provide . @var{feature})
867 The feature @var{feature} was provided.
870 The value of @code{load-history} may have one element whose @sc{car} is
871 @code{nil}. This element describes definitions made with
872 @code{eval-buffer} on a buffer that is not visiting a file.
875 The command @code{eval-region} updates @code{load-history}, but does so
876 by adding the symbols defined to the element for the file being visited,
877 rather than replacing that element. @xref{Eval}.
881 @cindex unloading packages
884 You can discard the functions and variables loaded by a library to
885 reclaim memory for other Lisp objects. To do this, use the function
886 @code{unload-feature}:
888 @deffn Command unload-feature feature &optional force
889 This command unloads the library that provided feature @var{feature}.
890 It undefines all functions, macros, and variables defined in that
891 library with @code{defun}, @code{defalias}, @code{defsubst},
892 @code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
893 It then restores any autoloads formerly associated with those symbols.
894 (Loading saves these in the @code{autoload} property of the symbol.)
896 Before restoring the previous definitions, @code{unload-feature} runs
897 @code{remove-hook} to remove functions in the library from certain
898 hooks. These hooks include variables whose names end in @samp{hook}
899 or @samp{-hooks}, plus those listed in
900 @code{unload-feature-special-hooks}, as well as
901 @code{auto-mode-alist}. This is to prevent Emacs from ceasing to
902 function because important hooks refer to functions that are no longer
905 Standard unloading activities also undoes ELP profiling of functions
906 in that library, unprovides any features provided by the library, and
907 cancels timers held in variables defined by the library.
909 @vindex @var{feature}-unload-function
910 If these measures are not sufficient to prevent malfunction, a library
911 can define an explicit unloader named @code{@var{feature}-unload-function}.
912 If that symbol is defined as a function, @code{unload-feature} calls
913 it with no arguments before doing anything else. It can do whatever
914 is appropriate to unload the library. If it returns @code{nil},
915 @code{unload-feature} proceeds to take the normal unload actions.
916 Otherwise it considers the job to be done.
918 Ordinarily, @code{unload-feature} refuses to unload a library on which
919 other loaded libraries depend. (A library @var{a} depends on library
920 @var{b} if @var{a} contains a @code{require} for @var{b}.) If the
921 optional argument @var{force} is non-@code{nil}, dependencies are
922 ignored and you can unload any library.
925 The @code{unload-feature} function is written in Lisp; its actions are
926 based on the variable @code{load-history}.
928 @defvar unload-feature-special-hooks
929 This variable holds a list of hooks to be scanned before unloading a
930 library, to remove functions defined in the library.
933 @node Hooks for Loading
934 @section Hooks for Loading
935 @cindex loading hooks
936 @cindex hooks for loading
938 You can ask for code to be executed each time Emacs loads a library,
939 by using the variable @code{after-load-functions}:
941 @defvar after-load-functions
942 This abnormal hook is run after loading a file. Each function in the
943 hook is called with a single argument, the absolute filename of the
944 file that was just loaded.
947 If you want code to be executed when a @emph{particular} library is
948 loaded, use the function @code{eval-after-load}:
950 @defun eval-after-load library form
951 This function arranges to evaluate @var{form} at the end of loading
952 the file @var{library}, each time @var{library} is loaded. If
953 @var{library} is already loaded, it evaluates @var{form} right away.
954 Don't forget to quote @var{form}!
956 You don't need to give a directory or extension in the file name
957 @var{library}. Normally, you just give a bare file name, like this:
960 (eval-after-load "edebug" '(def-edebug-spec c-point t))
963 To restrict which files can trigger the evaluation, include a
964 directory or an extension or both in @var{library}. Only a file whose
965 absolute true name (i.e., the name with all symbolic links chased out)
966 matches all the given name components will match. In the following
967 example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory
968 @code{..../foo/bar} will trigger the evaluation, but not
972 (eval-after-load "foo/bar/my_inst.elc" @dots{})
975 @var{library} can also be a feature (i.e.@: a symbol), in which case
976 @var{form} is evaluated at the end of any file where
977 @code{(provide @var{library})} is called.
979 An error in @var{form} does not undo the load, but does prevent
980 execution of the rest of @var{form}.
983 Normally, well-designed Lisp programs should not use
984 @code{eval-after-load}. If you need to examine and set the variables
985 defined in another library (those meant for outside use), you can do
986 it immediately---there is no need to wait until the library is loaded.
987 If you need to call functions defined by that library, you should load
988 the library, preferably with @code{require} (@pxref{Named Features}).
990 @defvar after-load-alist
991 This variable stores an alist built by @code{eval-after-load},
992 containing the expressions to evaluate when certain libraries are
993 loaded. Each element looks like this:
996 (@var{regexp-or-feature} @var{forms}@dots{})
999 The key @var{regexp-or-feature} is either a regular expression or a
1000 symbol, and the value is a list of forms. The forms are evaluated
1001 when the key matches the absolute true name or feature name of the
1002 library being loaded.