2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
5 @c Free Software Foundation, Inc.
6 @c See the file elisp.texi for copying conditions.
7 @setfilename ../../info/loading
8 @node Loading, Byte Compilation, Customization, Top
14 Loading a file of Lisp code means bringing its contents into the Lisp
15 environment in the form of Lisp objects. Emacs finds and opens the
16 file, reads the text, evaluates each form, and then closes the file.
18 The load functions evaluate all the expressions in a file just
19 as the @code{eval-buffer} function evaluates all the
20 expressions in a buffer. The difference is that the load functions
21 read and evaluate the text in the file as found on disk, not the text
24 @cindex top-level form
25 The loaded file must contain Lisp expressions, either as source code
26 or as byte-compiled code. Each form in the file is called a
27 @dfn{top-level form}. There is no special format for the forms in a
28 loadable file; any form in a file may equally well be typed directly
29 into a buffer and evaluated there. (Indeed, most code is tested this
30 way.) Most often, the forms are function definitions and variable
33 A file containing Lisp code is often called a @dfn{library}. Thus,
34 the ``Rmail library'' is a file containing code for Rmail mode.
35 Similarly, a ``Lisp library directory'' is a directory of files
39 * How Programs Do Loading:: The @code{load} function and others.
40 * Load Suffixes:: Details about the suffixes that @code{load} tries.
41 * Library Search:: Finding a library to load.
42 * Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files.
43 * Autoload:: Setting up a function to autoload.
44 * Repeated Loading:: Precautions about loading a file twice.
45 * Named Features:: Loading a library if it isn't already loaded.
46 * Where Defined:: Finding which file defined a certain symbol.
47 * Unloading:: How to "unload" a library that was loaded.
48 * Hooks for Loading:: Providing code to be run when
49 particular libraries are loaded.
52 @node How Programs Do Loading
53 @section How Programs Do Loading
55 Emacs Lisp has several interfaces for loading. For example,
56 @code{autoload} creates a placeholder object for a function defined in a
57 file; trying to call the autoloading function loads the file to get the
58 function's real definition (@pxref{Autoload}). @code{require} loads a
59 file if it isn't already loaded (@pxref{Named Features}). Ultimately,
60 all these facilities call the @code{load} function to do the work.
62 @defun load filename &optional missing-ok nomessage nosuffix must-suffix
63 This function finds and opens a file of Lisp code, evaluates all the
64 forms in it, and closes the file.
66 To find the file, @code{load} first looks for a file named
67 @file{@var{filename}.elc}, that is, for a file whose name is
68 @var{filename} with the extension @samp{.elc} appended. If such a
69 file exists, it is loaded. If there is no file by that name, then
70 @code{load} looks for a file named @file{@var{filename}.el}. If that
71 file exists, it is loaded. Finally, if neither of those names is
72 found, @code{load} looks for a file named @var{filename} with nothing
73 appended, and loads it if it exists. (The @code{load} function is not
74 clever about looking at @var{filename}. In the perverse case of a
75 file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will
78 If Auto Compression mode is enabled, as it is by default, then if
79 @code{load} can not find a file, it searches for a compressed version
80 of the file before trying other file names. It decompresses and loads
81 it if it exists. It looks for compressed versions by appending each
82 of the suffixes in @code{jka-compr-load-suffixes} to the file name.
83 The value of this variable must be a list of strings. Its standard
84 value is @code{(".gz")}.
86 If the optional argument @var{nosuffix} is non-@code{nil}, then
87 @code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In
88 this case, you must specify the precise file name you want, except
89 that, if Auto Compression mode is enabled, @code{load} will still use
90 @code{jka-compr-load-suffixes} to find compressed versions. By
91 specifying the precise file name and using @code{t} for
92 @var{nosuffix}, you can prevent perverse file names such as
93 @file{foo.el.el} from being tried.
95 If the optional argument @var{must-suffix} is non-@code{nil}, then
96 @code{load} insists that the file name used must end in either
97 @samp{.el} or @samp{.elc} (possibly extended with a compression
98 suffix), unless it contains an explicit directory name.
100 If @var{filename} is a relative file name, such as @file{foo} or
101 @file{baz/foo.bar}, @code{load} searches for the file using the variable
102 @code{load-path}. It appends @var{filename} to each of the directories
103 listed in @code{load-path}, and loads the first file it finds whose name
104 matches. The current default directory is tried only if it is specified
105 in @code{load-path}, where @code{nil} stands for the default directory.
106 @code{load} tries all three possible suffixes in the first directory in
107 @code{load-path}, then all three suffixes in the second directory, and
108 so on. @xref{Library Search}.
110 Whatever the name under which the file is eventually found, and the
111 directory where Emacs found it, Emacs sets the value of the variable
112 @code{load-file-name} to that file's name.
114 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
115 means you should consider recompiling @file{foo.el}. @xref{Byte
118 When loading a source file (not compiled), @code{load} performs
119 character set translation just as Emacs would do when visiting the file.
120 @xref{Coding Systems}.
122 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
123 in the echo area during loading unless @var{nomessage} is
127 Any unhandled errors while loading a file terminate loading. If the
128 load was done for the sake of @code{autoload}, any function definitions
129 made during the loading are undone.
132 If @code{load} can't find the file to load, then normally it signals the
133 error @code{file-error} (with @samp{Cannot open load file
134 @var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
135 @code{load} just returns @code{nil}.
137 You can use the variable @code{load-read-function} to specify a function
138 for @code{load} to use instead of @code{read} for reading expressions.
141 @code{load} returns @code{t} if the file loads successfully.
144 @deffn Command load-file filename
145 This command loads the file @var{filename}. If @var{filename} is a
146 relative file name, then the current default directory is assumed.
147 This command does not use @code{load-path}, and does not append
148 suffixes. However, it does look for compressed versions (if Auto
149 Compression Mode is enabled). Use this command if you wish to specify
150 precisely the file name to load.
153 @deffn Command load-library library
154 This command loads the library named @var{library}. It is equivalent to
155 @code{load}, except for the way it reads its argument interactively.
156 @xref{Lisp Libraries,,,emacs, The GNU Emacs Manual}.
159 @defvar load-in-progress
160 This variable is non-@code{nil} if Emacs is in the process of loading a
161 file, and it is @code{nil} otherwise.
164 @defvar load-file-name
165 When Emacs is in the process of loading a file, this variable's value
166 is the name of that file, as Emacs found it during the search
167 described earlier in this section.
170 @defvar load-read-function
171 @anchor{Definition of load-read-function}
172 @c do not allow page break at anchor; work around Texinfo deficiency.
173 This variable specifies an alternate expression-reading function for
174 @code{load} and @code{eval-region} to use instead of @code{read}.
175 The function should accept one argument, just as @code{read} does.
177 Normally, the variable's value is @code{nil}, which means those
178 functions should use @code{read}.
180 Instead of using this variable, it is cleaner to use another, newer
181 feature: to pass the function as the @var{read-function} argument to
182 @code{eval-region}. @xref{Definition of eval-region,, Eval}.
185 For information about how @code{load} is used in building Emacs, see
186 @ref{Building Emacs}.
189 @section Load Suffixes
190 We now describe some technical details about the exact suffixes that
193 @defvar load-suffixes
194 This is a list of suffixes indicating (compiled or source) Emacs Lisp
195 files. It should not include the empty string. @code{load} uses
196 these suffixes in order when it appends Lisp suffixes to the specified
197 file name. The standard value is @code{(".elc" ".el")} which produces
198 the behavior described in the previous section.
201 @defvar load-file-rep-suffixes
202 This is a list of suffixes that indicate representations of the same
203 file. This list should normally start with the empty string.
204 When @code{load} searches for a file it appends the suffixes in this
205 list, in order, to the file name, before searching for another file.
207 Enabling Auto Compression mode appends the suffixes in
208 @code{jka-compr-load-suffixes} to this list and disabling Auto
209 Compression mode removes them again. The standard value of
210 @code{load-file-rep-suffixes} if Auto Compression mode is disabled is
211 @code{("")}. Given that the standard value of
212 @code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value
213 of @code{load-file-rep-suffixes} if Auto Compression mode is enabled
214 is @code{("" ".gz")}.
217 @defun get-load-suffixes
218 This function returns the list of all suffixes that @code{load} should
219 try, in order, when its @var{must-suffix} argument is non-@code{nil}.
220 This takes both @code{load-suffixes} and @code{load-file-rep-suffixes}
221 into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes}
222 and @code{load-file-rep-suffixes} all have their standard values, this
223 function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto
224 Compression mode is enabled and @code{(".elc" ".el")} if Auto
225 Compression mode is disabled.
228 To summarize, @code{load} normally first tries the suffixes in the
229 value of @code{(get-load-suffixes)} and then those in
230 @code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil},
231 it skips the former group, and if @var{must-suffix} is non-@code{nil},
232 it skips the latter group.
235 @section Library Search
236 @cindex library search
239 When Emacs loads a Lisp library, it searches for the library
240 in a list of directories specified by the variable @code{load-path}.
243 @cindex @code{EMACSLOADPATH} environment variable
244 The value of this variable is a list of directories to search when
245 loading files with @code{load}. Each element is a string (which must be
246 a directory name) or @code{nil} (which stands for the current working
250 The value of @code{load-path} is initialized from the environment
251 variable @code{EMACSLOADPATH}, if that exists; otherwise its default
252 value is specified in @file{emacs/src/epaths.h} when Emacs is built.
253 Then the list is expanded by adding subdirectories of the directories
256 The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
257 @samp{:} (or @samp{;}, according to the operating system) separates
258 directory names, and @samp{.} is used for the current default directory.
259 Here is an example of how to set your @code{EMACSLOADPATH} variable from
260 a @code{csh} @file{.login} file:
263 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
266 Here is how to set it using @code{sh}:
270 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
273 Here is an example of code you can place in your init file (@pxref{Init
274 File}) to add several directories to the front of your default
280 (append (list nil "/user/bil/emacs"
287 @c Wordy to rid us of an overfull hbox. --rjc 15mar92
289 In this example, the path searches the current working directory first,
290 followed then by the @file{/user/bil/emacs} directory, the
291 @file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
292 which are then followed by the standard directories for Lisp code.
294 Dumping Emacs uses a special value of @code{load-path}. If the value of
295 @code{load-path} at the end of dumping is unchanged (that is, still the
296 same special value), the dumped Emacs switches to the ordinary
297 @code{load-path} value when it starts up, as described above. But if
298 @code{load-path} has any other value at the end of dumping, that value
299 is used for execution of the dumped Emacs also.
301 Therefore, if you want to change @code{load-path} temporarily for
302 loading a few libraries in @file{site-init.el} or @file{site-load.el},
303 you should bind @code{load-path} locally with @code{let} around the
304 calls to @code{load}.
306 The default value of @code{load-path}, when running an Emacs which has
307 been installed on the system, includes two special directories (and
308 their subdirectories as well):
311 "/usr/local/share/emacs/@var{version}/site-lisp"
318 "/usr/local/share/emacs/site-lisp"
322 The first one is for locally installed packages for a particular Emacs
323 version; the second is for locally installed packages meant for use with
324 all installed Emacs versions.
326 There are several reasons why a Lisp package that works well in one
327 Emacs version can cause trouble in another. Sometimes packages need
328 updating for incompatible changes in Emacs; sometimes they depend on
329 undocumented internal Emacs data that can change without notice;
330 sometimes a newer Emacs version incorporates a version of the package,
331 and should be used only with that version.
333 Emacs finds these directories' subdirectories and adds them to
334 @code{load-path} when it starts up. Both immediate subdirectories and
335 subdirectories multiple levels down are added to @code{load-path}.
337 Not all subdirectories are included, though. Subdirectories whose
338 names do not start with a letter or digit are excluded. Subdirectories
339 named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which
340 contains a file named @file{.nosearch} is excluded. You can use these
341 methods to prevent certain subdirectories of the @file{site-lisp}
342 directories from being searched.
344 If you run Emacs from the directory where it was built---that is, an
345 executable that has not been formally installed---then @code{load-path}
346 normally contains two additional directories. These are the @code{lisp}
347 and @code{site-lisp} subdirectories of the main build directory. (Both
348 are represented as absolute file names.)
350 @deffn Command locate-library library &optional nosuffix path interactive-call
351 This command finds the precise file name for library @var{library}. It
352 searches for the library in the same way @code{load} does, and the
353 argument @var{nosuffix} has the same meaning as in @code{load}: don't
354 add suffixes @samp{.elc} or @samp{.el} to the specified name
357 If the @var{path} is non-@code{nil}, that list of directories is used
358 instead of @code{load-path}.
360 When @code{locate-library} is called from a program, it returns the file
361 name as a string. When the user runs @code{locate-library}
362 interactively, the argument @var{interactive-call} is @code{t}, and this
363 tells @code{locate-library} to display the file name in the echo area.
366 @cindex shadowed Lisp files
367 @deffn Command list-load-path-shadows &optional stringp
368 This command shows a list of @dfn{shadowed} Emacs Lisp files. A
369 shadowed file is one that will not normally be loaded, despite being
370 in a directory on @code{load-path}, due to the existence of another
371 similarly-named file in a directory earlier on @code{load-path}.
373 For instance, suppose @code{load-path} is set to
376 ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
380 and that both these directories contain a file named @file{foo.el}.
381 Then @code{(require 'foo)} never loads the file in the second
382 directory. Such a situation might indicate a problem in the way Emacs
385 When called from Lisp, this function prints a message listing the
386 shadowed files, instead of displaying them in a buffer. If the
387 optional argument @code{stringp} is non-@code{nil}, it instead returns
388 the shadowed files as a string.
391 @node Loading Non-ASCII
392 @section Loading Non-@acronym{ASCII} Characters
394 When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
395 characters, these can be represented within Emacs either as unibyte
396 strings or as multibyte strings (@pxref{Text Representations}). Which
397 representation is used depends on how the file is read into Emacs. If
398 it is read with decoding into multibyte representation, the text of the
399 Lisp program will be multibyte text, and its string constants will be
400 multibyte strings. If a file containing Latin-1 characters (for
401 example) is read without decoding, the text of the program will be
402 unibyte text, and its string constants will be unibyte strings.
403 @xref{Coding Systems}.
405 The reason Emacs is designed this way is so that Lisp programs give
406 predictable results, regardless of how Emacs was started. In addition,
407 this enables programs that depend on using multibyte text to work even
410 In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are
411 multibyte strings should not be noticeable, since inserting them in
412 unibyte buffers converts them to unibyte automatically. However, if
413 this does make a difference, you can force a particular Lisp file to be
414 interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
415 comment on the file's first line. With that designator, the file will
416 unconditionally be interpreted as unibyte, even in an ordinary
417 multibyte Emacs session. This can matter when making keybindings to
418 non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
424 The @dfn{autoload} facility allows you to make a function or macro
425 known in Lisp, but put off loading the file that defines it. The first
426 call to the function automatically reads the proper file to install the
427 real definition and other associated code, then runs the real definition
428 as if it had been loaded all along.
430 There are two ways to set up an autoloaded function: by calling
431 @code{autoload}, and by writing a special ``magic'' comment in the
432 source before the real definition. @code{autoload} is the low-level
433 primitive for autoloading; any Lisp program can call @code{autoload} at
434 any time. Magic comments are the most convenient way to make a function
435 autoload, for packages installed along with Emacs. These comments do
436 nothing on their own, but they serve as a guide for the command
437 @code{update-file-autoloads}, which constructs calls to @code{autoload}
438 and arranges to execute them when Emacs is built.
440 @defun autoload function filename &optional docstring interactive type
441 This function defines the function (or macro) named @var{function} so as
442 to load automatically from @var{filename}. The string @var{filename}
443 specifies the file to load to get the real definition of @var{function}.
445 If @var{filename} does not contain either a directory name, or the
446 suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
447 one of these suffixes, and it will not load from a file whose name is
448 just @var{filename} with no added suffix. (The variable
449 @code{load-suffixes} specifies the exact required suffixes.)
451 The argument @var{docstring} is the documentation string for the
452 function. Specifying the documentation string in the call to
453 @code{autoload} makes it possible to look at the documentation without
454 loading the function's real definition. Normally, this should be
455 identical to the documentation string in the function definition
456 itself. If it isn't, the function definition's documentation string
457 takes effect when it is loaded.
459 If @var{interactive} is non-@code{nil}, that says @var{function} can be
460 called interactively. This lets completion in @kbd{M-x} work without
461 loading @var{function}'s real definition. The complete interactive
462 specification is not given here; it's not needed unless the user
463 actually calls @var{function}, and when that happens, it's time to load
466 You can autoload macros and keymaps as well as ordinary functions.
467 Specify @var{type} as @code{macro} if @var{function} is really a macro.
468 Specify @var{type} as @code{keymap} if @var{function} is really a
469 keymap. Various parts of Emacs need to know this information without
470 loading the real definition.
472 An autoloaded keymap loads automatically during key lookup when a prefix
473 key's binding is the symbol @var{function}. Autoloading does not occur
474 for other kinds of access to the keymap. In particular, it does not
475 happen when a Lisp program gets the keymap from the value of a variable
476 and calls @code{define-key}; not even if the variable name is the same
477 symbol @var{function}.
479 @cindex function cell in autoload
480 If @var{function} already has a non-void function definition that is not
481 an autoload object, @code{autoload} does nothing and returns @code{nil}.
482 If the function cell of @var{function} is void, or is already an autoload
483 object, then it is defined as an autoload object like this:
486 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
493 (symbol-function 'run-prolog)
494 @result{} (autoload "prolog" 169681 t nil)
499 In this case, @code{"prolog"} is the name of the file to load, 169681
500 refers to the documentation string in the
501 @file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
502 @code{t} means the function is interactive, and @code{nil} that it is
503 not a macro or a keymap.
506 @cindex autoload errors
507 The autoloaded file usually contains other definitions and may require
508 or provide one or more features. If the file is not completely loaded
509 (due to an error in the evaluation of its contents), any function
510 definitions or @code{provide} calls that occurred during the load are
511 undone. This is to ensure that the next attempt to call any function
512 autoloading from this file will try again to load the file. If not for
513 this, then some of the functions in the file might be defined by the
514 aborted load, but fail to work properly for the lack of certain
515 subroutines not loaded successfully because they come later in the file.
517 If the autoloaded file fails to define the desired Lisp function or
518 macro, then an error is signaled with data @code{"Autoloading failed to
519 define function @var{function-name}"}.
521 @findex update-file-autoloads
522 @findex update-directory-autoloads
523 @cindex magic autoload comment
524 @cindex autoload cookie
525 @anchor{autoload cookie}
526 A magic autoload comment (often called an @dfn{autoload cookie})
527 consists of @samp{;;;###autoload}, on a line by itself,
528 just before the real definition of the function in its
529 autoloadable source file. The command @kbd{M-x update-file-autoloads}
530 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
531 (The string that serves as the autoload cookie and the name of the
532 file generated by @code{update-file-autoloads} can be changed from the
533 above defaults, see below.)
534 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
535 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
536 autoloads for all files in the current directory.
538 The same magic comment can copy any kind of form into
539 @file{loaddefs.el}. If the form following the magic comment is not a
540 function-defining form or a @code{defcustom} form, it is copied
541 verbatim. ``Function-defining forms'' include @code{define-skeleton},
542 @code{define-derived-mode}, @code{define-generic-mode} and
543 @code{define-minor-mode} as well as @code{defun} and
544 @code{defmacro}. To save space, a @code{defcustom} form is converted to
545 a @code{defvar} in @file{loaddefs.el}, with some additional information
546 if it uses @code{:require}.
548 You can also use a magic comment to execute a form at build time
549 @emph{without} executing it when the file itself is loaded. To do this,
550 write the form @emph{on the same line} as the magic comment. Since it
551 is in a comment, it does nothing when you load the source file; but
552 @kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
553 it is executed while building Emacs.
555 The following example shows how @code{doctor} is prepared for
556 autoloading with a magic comment:
561 "Switch to *doctor* buffer and start giving psychotherapy."
563 (switch-to-buffer "*doctor*")
568 Here's what that produces in @file{loaddefs.el}:
571 (autoload (quote doctor) "doctor" "\
572 Switch to *doctor* buffer and start giving psychotherapy.
578 @cindex @code{fn} in function's documentation string
579 The backslash and newline immediately following the double-quote are a
580 convention used only in the preloaded uncompiled Lisp files such as
581 @file{loaddefs.el}; they tell @code{make-docfile} to put the
582 documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
583 See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)}
584 in the usage part of the documentation string is replaced with the
585 function's name when the various help functions (@pxref{Help
586 Functions}) display it.
588 If you write a function definition with an unusual macro that is not
589 one of the known and recognized function definition methods, use of an
590 ordinary magic autoload comment would copy the whole definition into
591 @code{loaddefs.el}. That is not desirable. You can put the desired
592 @code{autoload} call into @code{loaddefs.el} instead by writing this:
595 ;;;###autoload (autoload 'foo "myfile")
600 You can use a non-default string as the autoload cookie and have the
601 corresponding autoload calls written into a file whose name is
602 different from the default @file{loaddefs.el}. Emacs provides two
603 variables to control this:
605 @defvar generate-autoload-cookie
606 The value of this variable should be a string whose syntax is a Lisp
607 comment. @kbd{M-x update-file-autoloads} copies the Lisp form that
608 follows the cookie into the autoload file it generates. The default
609 value of this variable is @code{";;;###autoload"}.
612 @defvar generated-autoload-file
613 The value of this variable names an Emacs Lisp file where the autoload
614 calls should go. The default value is @file{loaddefs.el}, but you can
615 override that, e.g., in the ``Local Variables'' section of a
616 @file{.el} file (@pxref{File Local Variables}). The autoload file is
617 assumed to contain a trailer starting with a formfeed character.
620 @node Repeated Loading
621 @section Repeated Loading
622 @cindex repeated loading
624 You can load a given file more than once in an Emacs session. For
625 example, after you have rewritten and reinstalled a function definition
626 by editing it in a buffer, you may wish to return to the original
627 version; you can do this by reloading the file it came from.
629 When you load or reload files, bear in mind that the @code{load} and
630 @code{load-library} functions automatically load a byte-compiled file
631 rather than a non-compiled file of similar name. If you rewrite a file
632 that you intend to save and reinstall, you need to byte-compile the new
633 version; otherwise Emacs will load the older, byte-compiled file instead
634 of your newer, non-compiled file! If that happens, the message
635 displayed when loading the file includes, @samp{(compiled; note, source is
636 newer)}, to remind you to recompile it.
638 When writing the forms in a Lisp library file, keep in mind that the
639 file might be loaded more than once. For example, think about whether
640 each variable should be reinitialized when you reload the library;
641 @code{defvar} does not change the value if the variable is already
642 initialized. (@xref{Defining Variables}.)
644 The simplest way to add an element to an alist is like this:
647 (push '(leif-mode " Leif") minor-mode-alist)
651 But this would add multiple elements if the library is reloaded. To
652 avoid the problem, use @code{add-to-list} (@pxref{List Variables}):
655 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
658 Occasionally you will want to test explicitly whether a library has
659 already been loaded. If the library uses @code{provide} to provide a
660 named feature, you can use @code{featurep} earlier in the file to test
661 whether the @code{provide} call has been executed before (@pxref{Named
662 Features}). Alternatively, you could use something like this:
665 (defvar foo-was-loaded nil)
667 (unless foo-was-loaded
668 @var{execute-first-time-only}
669 (setq foo-was-loaded t))
677 @cindex requiring features
678 @cindex providing features
680 @code{provide} and @code{require} are an alternative to
681 @code{autoload} for loading files automatically. They work in terms of
682 named @dfn{features}. Autoloading is triggered by calling a specific
683 function, but a feature is loaded the first time another program asks
686 A feature name is a symbol that stands for a collection of functions,
687 variables, etc. The file that defines them should @dfn{provide} the
688 feature. Another program that uses them may ensure they are defined by
689 @dfn{requiring} the feature. This loads the file of definitions if it
690 hasn't been loaded already.
692 @cindex load error with require
693 To require the presence of a feature, call @code{require} with the
694 feature name as argument. @code{require} looks in the global variable
695 @code{features} to see whether the desired feature has been provided
696 already. If not, it loads the feature from the appropriate file. This
697 file should call @code{provide} at the top level to add the feature to
698 @code{features}; if it fails to do so, @code{require} signals an error.
700 For example, in @file{emacs/lisp/prolog.el},
701 the definition for @code{run-prolog} includes the following code:
705 "Run an inferior Prolog process, with I/O via buffer *prolog*."
708 (switch-to-buffer (make-comint "prolog" prolog-program-name))
709 (inferior-prolog-mode))
713 The expression @code{(require 'comint)} loads the file @file{comint.el}
714 if it has not yet been loaded. This ensures that @code{make-comint} is
715 defined. Features are normally named after the files that provide them,
716 so that @code{require} need not be given the file name.
718 The @file{comint.el} file contains the following top-level expression:
725 This adds @code{comint} to the global @code{features} list, so that
726 @code{(require 'comint)} will henceforth know that nothing needs to be
729 @cindex byte-compiling @code{require}
730 When @code{require} is used at top level in a file, it takes effect
731 when you byte-compile that file (@pxref{Byte Compilation}) as well as
732 when you load it. This is in case the required package contains macros
733 that the byte compiler must know about. It also avoids byte compiler
734 warnings for functions and variables defined in the file loaded with
737 Although top-level calls to @code{require} are evaluated during
738 byte compilation, @code{provide} calls are not. Therefore, you can
739 ensure that a file of definitions is loaded before it is byte-compiled
740 by including a @code{provide} followed by a @code{require} for the same
741 feature, as in the following example.
745 (provide 'my-feature) ; @r{Ignored by byte compiler,}
746 ; @r{evaluated by @code{load}.}
747 (require 'my-feature) ; @r{Evaluated by byte compiler.}
752 The compiler ignores the @code{provide}, then processes the
753 @code{require} by loading the file in question. Loading the file does
754 execute the @code{provide} call, so the subsequent @code{require} call
755 does nothing when the file is loaded.
757 @defun provide feature &optional subfeatures
758 This function announces that @var{feature} is now loaded, or being
759 loaded, into the current Emacs session. This means that the facilities
760 associated with @var{feature} are or will be available for other Lisp
763 The direct effect of calling @code{provide} is if not already in
764 @var{features} then to add @var{feature} to the front of that list and
765 call any @code{eval-after-load} code waiting for it (@pxref{Hooks for
766 Loading}). The argument @var{feature} must be a symbol.
767 @code{provide} returns @var{feature}.
769 If provided, @var{subfeatures} should be a list of symbols indicating
770 a set of specific subfeatures provided by this version of
771 @var{feature}. You can test the presence of a subfeature using
772 @code{featurep}. The idea of subfeatures is that you use them when a
773 package (which is one @var{feature}) is complex enough to make it
774 useful to give names to various parts or functionalities of the
775 package, which might or might not be loaded, or might or might not be
776 present in a given version. @xref{Network Feature Testing}, for
786 @result{} (foo bar bish)
789 When a file is loaded to satisfy an autoload, and it stops due to an
790 error in the evaluation of its contents, any function definitions or
791 @code{provide} calls that occurred during the load are undone.
795 @defun require feature &optional filename noerror
796 This function checks whether @var{feature} is present in the current
797 Emacs session (using @code{(featurep @var{feature})}; see below). The
798 argument @var{feature} must be a symbol.
800 If the feature is not present, then @code{require} loads @var{filename}
801 with @code{load}. If @var{filename} is not supplied, then the name of
802 the symbol @var{feature} is used as the base file name to load.
803 However, in this case, @code{require} insists on finding @var{feature}
804 with an added @samp{.el} or @samp{.elc} suffix (possibly extended with
805 a compression suffix); a file whose name is just @var{feature} won't
806 be used. (The variable @code{load-suffixes} specifies the exact
807 required Lisp suffixes.)
809 If @var{noerror} is non-@code{nil}, that suppresses errors from actual
810 loading of the file. In that case, @code{require} returns @code{nil}
811 if loading the file fails. Normally, @code{require} returns
814 If loading the file succeeds but does not provide @var{feature},
815 @code{require} signals an error, @samp{Required feature @var{feature}
819 @defun featurep feature &optional subfeature
820 This function returns @code{t} if @var{feature} has been provided in
821 the current Emacs session (i.e.@:, if @var{feature} is a member of
822 @code{features}.) If @var{subfeature} is non-@code{nil}, then the
823 function returns @code{t} only if that subfeature is provided as well
824 (i.e.@: if @var{subfeature} is a member of the @code{subfeature}
825 property of the @var{feature} symbol.)
829 The value of this variable is a list of symbols that are the features
830 loaded in the current Emacs session. Each symbol was put in this list
831 with a call to @code{provide}. The order of the elements in the
832 @code{features} list is not significant.
836 @section Which File Defined a Certain Symbol
838 @defun symbol-file symbol &optional type
839 This function returns the name of the file that defined @var{symbol}.
840 If @var{type} is @code{nil}, then any kind of definition is acceptable.
841 If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that
842 specifies function definition, variable definition, or face definition
845 The value is normally an absolute file name. It can also be @code{nil},
846 if the definition is not associated with any file. If @var{symbol}
847 specifies an autoloaded function, the value can be a relative file name
851 The basis for @code{symbol-file} is the data in the variable
855 The value of this variable is an alist that associates the names of
856 loaded library files with the names of the functions and variables
857 they defined, as well as the features they provided or required.
859 Each element in this alist describes one loaded library (including
860 libraries that are preloaded at startup). It is a list whose @sc{car}
861 is the absolute file name of the library (a string). The rest of the
862 list elements have these forms:
866 The symbol @var{var} was defined as a variable.
867 @item (defun . @var{fun})
868 The function @var{fun} was defined.
869 @item (t . @var{fun})
870 The function @var{fun} was previously an autoload before this library
871 redefined it as a function. The following element is always
872 @code{(defun . @var{fun})}, which represents defining @var{fun} as a
874 @item (autoload . @var{fun})
875 The function @var{fun} was defined as an autoload.
876 @item (defface . @var{face})
877 The face @var{face} was defined.
878 @item (require . @var{feature})
879 The feature @var{feature} was required.
880 @item (provide . @var{feature})
881 The feature @var{feature} was provided.
884 The value of @code{load-history} may have one element whose @sc{car} is
885 @code{nil}. This element describes definitions made with
886 @code{eval-buffer} on a buffer that is not visiting a file.
889 The command @code{eval-region} updates @code{load-history}, but does so
890 by adding the symbols defined to the element for the file being visited,
891 rather than replacing that element. @xref{Eval}.
895 @cindex unloading packages
898 You can discard the functions and variables loaded by a library to
899 reclaim memory for other Lisp objects. To do this, use the function
900 @code{unload-feature}:
902 @deffn Command unload-feature feature &optional force
903 This command unloads the library that provided feature @var{feature}.
904 It undefines all functions, macros, and variables defined in that
905 library with @code{defun}, @code{defalias}, @code{defsubst},
906 @code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
907 It then restores any autoloads formerly associated with those symbols.
908 (Loading saves these in the @code{autoload} property of the symbol.)
910 Before restoring the previous definitions, @code{unload-feature} runs
911 @code{remove-hook} to remove functions in the library from certain
912 hooks. These hooks include variables whose names end in @samp{hook}
913 or @samp{-hooks}, plus those listed in
914 @code{unload-feature-special-hooks}, as well as
915 @code{auto-mode-alist}. This is to prevent Emacs from ceasing to
916 function because important hooks refer to functions that are no longer
919 Standard unloading activities also undoes ELP profiling of functions
920 in that library, unprovides any features provided by the library, and
921 cancels timers held in variables defined by the library.
923 @vindex @var{feature}-unload-function
924 If these measures are not sufficient to prevent malfunction, a library
925 can define an explicit unloader named @code{@var{feature}-unload-function}.
926 If that symbol is defined as a function, @code{unload-feature} calls
927 it with no arguments before doing anything else. It can do whatever
928 is appropriate to unload the library. If it returns @code{nil},
929 @code{unload-feature} proceeds to take the normal unload actions.
930 Otherwise it considers the job to be done.
932 Ordinarily, @code{unload-feature} refuses to unload a library on which
933 other loaded libraries depend. (A library @var{a} depends on library
934 @var{b} if @var{a} contains a @code{require} for @var{b}.) If the
935 optional argument @var{force} is non-@code{nil}, dependencies are
936 ignored and you can unload any library.
939 The @code{unload-feature} function is written in Lisp; its actions are
940 based on the variable @code{load-history}.
942 @defvar unload-feature-special-hooks
943 This variable holds a list of hooks to be scanned before unloading a
944 library, to remove functions defined in the library.
947 @node Hooks for Loading
948 @section Hooks for Loading
949 @cindex loading hooks
950 @cindex hooks for loading
952 You can ask for code to be executed each time Emacs loads a library,
953 by using the variable @code{after-load-functions}:
955 @defvar after-load-functions
956 This abnormal hook is run after loading a file. Each function in the
957 hook is called with a single argument, the absolute filename of the
958 file that was just loaded.
961 If you want code to be executed when a @emph{particular} library is
962 loaded, use the function @code{eval-after-load}:
964 @defun eval-after-load library form
965 This function arranges to evaluate @var{form} at the end of loading
966 the file @var{library}, each time @var{library} is loaded. If
967 @var{library} is already loaded, it evaluates @var{form} right away.
968 Don't forget to quote @var{form}!
970 You don't need to give a directory or extension in the file name
971 @var{library}. Normally, you just give a bare file name, like this:
974 (eval-after-load "edebug" '(def-edebug-spec c-point t))
977 To restrict which files can trigger the evaluation, include a
978 directory or an extension or both in @var{library}. Only a file whose
979 absolute true name (i.e., the name with all symbolic links chased out)
980 matches all the given name components will match. In the following
981 example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory
982 @code{..../foo/bar} will trigger the evaluation, but not
986 (eval-after-load "foo/bar/my_inst.elc" @dots{})
989 @var{library} can also be a feature (i.e.@: a symbol), in which case
990 @var{form} is evaluated at the end of any file where
991 @code{(provide @var{library})} is called.
993 An error in @var{form} does not undo the load, but does prevent
994 execution of the rest of @var{form}.
997 Normally, well-designed Lisp programs should not use
998 @code{eval-after-load}. If you need to examine and set the variables
999 defined in another library (those meant for outside use), you can do
1000 it immediately---there is no need to wait until the library is loaded.
1001 If you need to call functions defined by that library, you should load
1002 the library, preferably with @code{require} (@pxref{Named Features}).
1004 But it is OK to use @code{eval-after-load} in your personal
1005 customizations if you don't feel that they must meet the design
1006 standards for programs meant for wider use.
1008 @defvar after-load-alist
1009 This variable stores an alist built by @code{eval-after-load},
1010 containing the expressions to evaluate when certain libraries are
1011 loaded. Each element looks like this:
1014 (@var{regexp-or-feature} @var{forms}@dots{})
1017 The key @var{regexp-or-feature} is either a regular expression or a
1018 symbol, and the value is a list of forms. The forms are evaluated
1019 when the key matches the absolute true name or feature name of the
1020 library being loaded.