2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
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
32 For on-demand loading of external libraries, @pxref{Dynamic Libraries}.
35 * How Programs Do Loading:: The @code{load} function and others.
36 * Load Suffixes:: Details about the suffixes that @code{load} tries.
37 * Library Search:: Finding a library to load.
38 * Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files.
39 * Autoload:: Setting up a function to autoload.
40 * Repeated Loading:: Precautions about loading a file twice.
41 * Named Features:: Loading a library if it isn't already loaded.
42 * Where Defined:: Finding which file defined a certain symbol.
43 * Unloading:: How to "unload" a library that was loaded.
44 * Hooks for Loading:: Providing code to be run when
45 particular libraries are loaded.
48 @node How Programs Do Loading
49 @section How Programs Do Loading
51 Emacs Lisp has several interfaces for loading. For example,
52 @code{autoload} creates a placeholder object for a function defined in a
53 file; trying to call the autoloading function loads the file to get the
54 function's real definition (@pxref{Autoload}). @code{require} loads a
55 file if it isn't already loaded (@pxref{Named Features}). Ultimately,
56 all these facilities call the @code{load} function to do the work.
58 @defun load filename &optional missing-ok nomessage nosuffix must-suffix
59 This function finds and opens a file of Lisp code, evaluates all the
60 forms in it, and closes the file.
62 To find the file, @code{load} first looks for a file named
63 @file{@var{filename}.elc}, that is, for a file whose name is
64 @var{filename} with the extension @samp{.elc} appended. If such a
65 file exists, it is loaded. If there is no file by that name, then
66 @code{load} looks for a file named @file{@var{filename}.el}. If that
67 file exists, it is loaded. Finally, if neither of those names is
68 found, @code{load} looks for a file named @var{filename} with nothing
69 appended, and loads it if it exists. (The @code{load} function is not
70 clever about looking at @var{filename}. In the perverse case of a
71 file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will
74 If Auto Compression mode is enabled, as it is by default, then if
75 @code{load} can not find a file, it searches for a compressed version
76 of the file before trying other file names. It decompresses and loads
77 it if it exists. It looks for compressed versions by appending each
78 of the suffixes in @code{jka-compr-load-suffixes} to the file name.
79 The value of this variable must be a list of strings. Its standard
80 value is @code{(".gz")}.
82 If the optional argument @var{nosuffix} is non-@code{nil}, then
83 @code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In
84 this case, you must specify the precise file name you want, except
85 that, if Auto Compression mode is enabled, @code{load} will still use
86 @code{jka-compr-load-suffixes} to find compressed versions. By
87 specifying the precise file name and using @code{t} for
88 @var{nosuffix}, you can prevent file names like @file{foo.el.el} from
91 If the optional argument @var{must-suffix} is non-@code{nil}, then
92 @code{load} insists that the file name used must end in either
93 @samp{.el} or @samp{.elc} (possibly extended with a compression
94 suffix), unless it contains an explicit directory name.
96 If @var{filename} is a relative file name, such as @file{foo} or
97 @file{baz/foo.bar}, @code{load} searches for the file using the variable
98 @code{load-path}. It appends @var{filename} to each of the directories
99 listed in @code{load-path}, and loads the first file it finds whose name
100 matches. The current default directory is tried only if it is specified
101 in @code{load-path}, where @code{nil} stands for the default directory.
102 @code{load} tries all three possible suffixes in the first directory in
103 @code{load-path}, then all three suffixes in the second directory, and
104 so on. @xref{Library Search}.
106 Whatever the name under which the file is eventually found, and the
107 directory where Emacs found it, Emacs sets the value of the variable
108 @code{load-file-name} to that file's name.
110 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
111 means you should consider recompiling @file{foo.el}. @xref{Byte
114 When loading a source file (not compiled), @code{load} performs
115 character set translation just as Emacs would do when visiting the file.
116 @xref{Coding Systems}.
118 @c This is referred to from the Macros chapter.
119 @c Not sure if it should be the other way round.
120 @cindex eager macro expansion
121 When loading an uncompiled file, Emacs tries to expand any macros
122 that the file contains (@pxref{Macros}). We refer to this as
123 @dfn{eager macro expansion}. Doing this (rather than deferring
124 the expansion until the relevant code runs) can significantly speed
125 up the execution of uncompiled code. Sometimes, this macro expansion
126 cannot be done, owing to a cyclic dependency. In the simplest
127 example of this, the file you are loading refers to a macro defined
128 in another file, and that file in turn requires the file you are
129 loading. This is generally harmless. Emacs prints a warning
130 (@samp{Eager macro-expansion skipped due to cycle@dots{}})
131 giving details of the problem, but it still loads the file, just
132 leaving the macro unexpanded for now. You may wish to restructure
133 your code so that this does not happen. Loading a compiled file does
134 not cause macroexpansion, because this should already have happened
135 during compilation. @xref{Compiling Macros}.
137 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
138 in the echo area during loading unless @var{nomessage} is
142 Any unhandled errors while loading a file terminate loading. If the
143 load was done for the sake of @code{autoload}, any function definitions
144 made during the loading are undone.
147 If @code{load} can't find the file to load, then normally it signals the
148 error @code{file-error} (with @samp{Cannot open load file
149 @var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
150 @code{load} just returns @code{nil}.
152 You can use the variable @code{load-read-function} to specify a function
153 for @code{load} to use instead of @code{read} for reading expressions.
156 @code{load} returns @code{t} if the file loads successfully.
159 @deffn Command load-file filename
160 This command loads the file @var{filename}. If @var{filename} is a
161 relative file name, then the current default directory is assumed.
162 This command does not use @code{load-path}, and does not append
163 suffixes. However, it does look for compressed versions (if Auto
164 Compression Mode is enabled). Use this command if you wish to specify
165 precisely the file name to load.
168 @deffn Command load-library library
169 This command loads the library named @var{library}. It is equivalent to
170 @code{load}, except for the way it reads its argument interactively.
171 @xref{Lisp Libraries,,,emacs, The GNU Emacs Manual}.
174 @defvar load-in-progress
175 This variable is non-@code{nil} if Emacs is in the process of loading a
176 file, and it is @code{nil} otherwise.
179 @defvar load-file-name
180 When Emacs is in the process of loading a file, this variable's value
181 is the name of that file, as Emacs found it during the search
182 described earlier in this section.
185 @defvar load-read-function
186 @anchor{Definition of load-read-function}
187 @c do not allow page break at anchor; work around Texinfo deficiency.
188 This variable specifies an alternate expression-reading function for
189 @code{load} and @code{eval-region} to use instead of @code{read}.
190 The function should accept one argument, just as @code{read} does.
192 Normally, the variable's value is @code{nil}, which means those
193 functions should use @code{read}.
195 Instead of using this variable, it is cleaner to use another, newer
196 feature: to pass the function as the @var{read-function} argument to
197 @code{eval-region}. @xref{Definition of eval-region,, Eval}.
200 For information about how @code{load} is used in building Emacs, see
201 @ref{Building Emacs}.
204 @section Load Suffixes
205 We now describe some technical details about the exact suffixes that
208 @defvar load-suffixes
209 This is a list of suffixes indicating (compiled or source) Emacs Lisp
210 files. It should not include the empty string. @code{load} uses
211 these suffixes in order when it appends Lisp suffixes to the specified
212 file name. The standard value is @code{(".elc" ".el")} which produces
213 the behavior described in the previous section.
216 @defvar load-file-rep-suffixes
217 This is a list of suffixes that indicate representations of the same
218 file. This list should normally start with the empty string.
219 When @code{load} searches for a file it appends the suffixes in this
220 list, in order, to the file name, before searching for another file.
222 Enabling Auto Compression mode appends the suffixes in
223 @code{jka-compr-load-suffixes} to this list and disabling Auto
224 Compression mode removes them again. The standard value of
225 @code{load-file-rep-suffixes} if Auto Compression mode is disabled is
226 @code{("")}. Given that the standard value of
227 @code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value
228 of @code{load-file-rep-suffixes} if Auto Compression mode is enabled
229 is @code{("" ".gz")}.
232 @defun get-load-suffixes
233 This function returns the list of all suffixes that @code{load} should
234 try, in order, when its @var{must-suffix} argument is non-@code{nil}.
235 This takes both @code{load-suffixes} and @code{load-file-rep-suffixes}
236 into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes}
237 and @code{load-file-rep-suffixes} all have their standard values, this
238 function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto
239 Compression mode is enabled and @code{(".elc" ".el")} if Auto
240 Compression mode is disabled.
243 To summarize, @code{load} normally first tries the suffixes in the
244 value of @code{(get-load-suffixes)} and then those in
245 @code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil},
246 it skips the former group, and if @var{must-suffix} is non-@code{nil},
247 it skips the latter group.
250 @section Library Search
251 @cindex library search
254 When Emacs loads a Lisp library, it searches for the library
255 in a list of directories specified by the variable @code{load-path}.
258 The value of this variable is a list of directories to search when
259 loading files with @code{load}. Each element is a string (which must be
260 a directory name) or @code{nil} (which stands for the current working
264 When Emacs starts up, it sets up the value of @code{load-path}
265 in several steps. First, it initializes @code{load-path} using
266 default locations set when Emacs was compiled. Normally, this
267 is a directory something like
270 "/usr/local/share/emacs/@var{version}/lisp"
273 followed by a similarly named @file{leim} directory. These
274 directories contain the standard Lisp files that come with Emacs.
275 If Emacs cannot find them, it will not start correctly.
277 If you run Emacs from the directory where it was built---that is, an
278 executable that has not been formally installed---Emacs instead
279 initializes @code{load-path} using the @file{lisp} and @file{leim}
280 directories in the directory containing the sources from which it
281 was built. If you built Emacs in a separate directory from the
282 sources, it also adds those directories from the build directory.
283 (In all cases, elements are represented as absolute file names.)
285 @cindex site-lisp directories
286 Unless you start Emacs with the @option{--no-site-lisp} option,
287 it then adds two more @file{site-lisp} directories to the front of
288 @code{load-path}. These are intended for locally installed Lisp files,
289 and are normally of the form:
292 "/usr/local/share/emacs/@var{version}/site-lisp"
299 "/usr/local/share/emacs/site-lisp"
303 The first one is for locally installed files for a specific Emacs
304 version; the second is for locally installed files meant for use
305 with all installed Emacs versions. (If Emacs is running uninstalled,
306 it also adds @file{site-lisp} directories from the source and build
307 directories, if they exist. Normally these directories do not contain
308 @file{site-lisp} directories.)
310 @cindex @env{EMACSLOADPATH} environment variable
311 If the environment variable @env{EMACSLOADPATH} is set, it overrides
312 the above initialization procedure. That is, Emacs initializes
313 @code{load-path} based solely on the value of the environment
314 variable. You must therefore include the directory containing the
315 standard Lisp files, else Emacs will not function. In most
316 situations, it is better to use the @option{-L} command-line option
317 (see below) to add elements to @code{load-path}.
319 The syntax of @env{EMACSLOADPATH} is the same as used for @code{PATH};
320 directory names are separated by @samp{:} (or @samp{;}, on some
321 operating systems), and @samp{.} stands for the current default
322 directory. Here is an example of how to set @env{EMACSLOADPATH}
323 variable (from a @command{sh}-style shell):
327 EMACSLOADPATH=/home/foo/.emacs.d/lisp:/usr/local/emacs/24.3/lisp
330 For each directory in @code{load-path}, Emacs then checks to see if
331 it contains a file @file{subdirs.el}, and if so, loads it. The
332 @file{subdirs.el} file is created when Emacs is built/installed,
333 and contains code that causes Emacs to add any subdirectories of those
334 directories to @code{load-path}. Both immediate subdirectories and
335 subdirectories multiple levels down are added. But it excludes
336 subdirectories whose names do not start with a letter or digit, and
337 subdirectories named @file{RCS} or @file{CVS}, and subdirectories
338 containing a file named @file{.nosearch}.
340 Next, Emacs adds any extra load directories that you specify using the
341 @option{-L} command-line option (@pxref{Action Arguments,,,emacs, The
342 GNU Emacs Manual}). It also adds the directories where optional
343 packages are installed, if any (@pxref{Packaging Basics}).
345 It is common to add code to one's init file (@pxref{Init File}) to
346 add one or more directories to @code{load-path}. For example:
349 (push "~/.emacs.d/lisp" load-path)
352 Dumping Emacs uses a special value of @code{load-path}. If the
353 value of @code{load-path} at the end of dumping is unchanged (that is,
354 still the same special value), the dumped Emacs switches to the
355 ordinary @code{load-path} value when it starts up, as described above.
356 But if @code{load-path} has any other value at the end of dumping,
357 that value is used for execution of the dumped Emacs also.
359 @deffn Command locate-library library &optional nosuffix path interactive-call
360 This command finds the precise file name for library @var{library}. It
361 searches for the library in the same way @code{load} does, and the
362 argument @var{nosuffix} has the same meaning as in @code{load}: don't
363 add suffixes @samp{.elc} or @samp{.el} to the specified name
366 If the @var{path} is non-@code{nil}, that list of directories is used
367 instead of @code{load-path}.
369 When @code{locate-library} is called from a program, it returns the file
370 name as a string. When the user runs @code{locate-library}
371 interactively, the argument @var{interactive-call} is @code{t}, and this
372 tells @code{locate-library} to display the file name in the echo area.
375 @cindex shadowed Lisp files
376 @deffn Command list-load-path-shadows &optional stringp
377 This command shows a list of @dfn{shadowed} Emacs Lisp files. A
378 shadowed file is one that will not normally be loaded, despite being
379 in a directory on @code{load-path}, due to the existence of another
380 similarly-named file in a directory earlier on @code{load-path}.
382 For instance, suppose @code{load-path} is set to
385 ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
389 and that both these directories contain a file named @file{foo.el}.
390 Then @code{(require 'foo)} never loads the file in the second
391 directory. Such a situation might indicate a problem in the way Emacs
394 When called from Lisp, this function prints a message listing the
395 shadowed files, instead of displaying them in a buffer. If the
396 optional argument @code{stringp} is non-@code{nil}, it instead returns
397 the shadowed files as a string.
400 @node Loading Non-ASCII
401 @section Loading Non-@acronym{ASCII} Characters
403 When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
404 characters, these can be represented within Emacs either as unibyte
405 strings or as multibyte strings (@pxref{Text Representations}). Which
406 representation is used depends on how the file is read into Emacs. If
407 it is read with decoding into multibyte representation, the text of the
408 Lisp program will be multibyte text, and its string constants will be
409 multibyte strings. If a file containing Latin-1 characters (for
410 example) is read without decoding, the text of the program will be
411 unibyte text, and its string constants will be unibyte strings.
412 @xref{Coding Systems}.
414 In most Emacs Lisp programs, the fact that non-@acronym{ASCII}
415 strings are multibyte strings should not be noticeable, since
416 inserting them in unibyte buffers converts them to unibyte
417 automatically. However, if this does make a difference, you can force
418 a particular Lisp file to be interpreted as unibyte by writing
419 @samp{coding: raw-text} in a local variables section. With
420 that designator, the file will unconditionally be interpreted as
421 unibyte. This can matter when making keybindings to
422 non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
428 The @dfn{autoload} facility lets you register the existence of a
429 function or macro, but put off loading the file that defines it. The
430 first call to the function automatically loads the proper library, in
431 order to install the real definition and other associated code, then
432 runs the real definition as if it had been loaded all along.
433 Autoloading can also be triggered by looking up the documentation of
434 the function or macro (@pxref{Documentation Basics}).
436 There are two ways to set up an autoloaded function: by calling
437 @code{autoload}, and by writing a special ``magic'' comment in the
438 source before the real definition. @code{autoload} is the low-level
439 primitive for autoloading; any Lisp program can call @code{autoload} at
440 any time. Magic comments are the most convenient way to make a function
441 autoload, for packages installed along with Emacs. These comments do
442 nothing on their own, but they serve as a guide for the command
443 @code{update-file-autoloads}, which constructs calls to @code{autoload}
444 and arranges to execute them when Emacs is built.
446 @defun autoload function filename &optional docstring interactive type
447 This function defines the function (or macro) named @var{function} so as
448 to load automatically from @var{filename}. The string @var{filename}
449 specifies the file to load to get the real definition of @var{function}.
451 If @var{filename} does not contain either a directory name, or the
452 suffix @code{.el} or @code{.elc}, this function insists on adding one
453 of these suffixes, and it will not load from a file whose name is just
454 @var{filename} with no added suffix. (The variable
455 @code{load-suffixes} specifies the exact required suffixes.)
457 The argument @var{docstring} is the documentation string for the
458 function. Specifying the documentation string in the call to
459 @code{autoload} makes it possible to look at the documentation without
460 loading the function's real definition. Normally, this should be
461 identical to the documentation string in the function definition
462 itself. If it isn't, the function definition's documentation string
463 takes effect when it is loaded.
465 If @var{interactive} is non-@code{nil}, that says @var{function} can be
466 called interactively. This lets completion in @kbd{M-x} work without
467 loading @var{function}'s real definition. The complete interactive
468 specification is not given here; it's not needed unless the user
469 actually calls @var{function}, and when that happens, it's time to load
472 You can autoload macros and keymaps as well as ordinary functions.
473 Specify @var{type} as @code{macro} if @var{function} is really a macro.
474 Specify @var{type} as @code{keymap} if @var{function} is really a
475 keymap. Various parts of Emacs need to know this information without
476 loading the real definition.
478 An autoloaded keymap loads automatically during key lookup when a prefix
479 key's binding is the symbol @var{function}. Autoloading does not occur
480 for other kinds of access to the keymap. In particular, it does not
481 happen when a Lisp program gets the keymap from the value of a variable
482 and calls @code{define-key}; not even if the variable name is the same
483 symbol @var{function}.
485 @cindex function cell in autoload
486 If @var{function} already has a non-void function definition that is not
487 an autoload object, this function does nothing and returns @code{nil}.
488 Otherwise, it constructs an autoload object (@pxref{Autoload Type}),
489 and stores it as the function definition for @var{function}. The
490 autoload object has this form:
493 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
500 (symbol-function 'run-prolog)
501 @result{} (autoload "prolog" 169681 t nil)
506 In this case, @code{"prolog"} is the name of the file to load, 169681
507 refers to the documentation string in the
508 @file{emacs/etc/DOC} file (@pxref{Documentation Basics}),
509 @code{t} means the function is interactive, and @code{nil} that it is
510 not a macro or a keymap.
513 @defun autoloadp object
514 This function returns non-@code{nil} if @var{object} is an autoload
515 object. For example, to check if @code{run-prolog} is defined as an
516 autoloaded function, evaluate
519 (autoloadp (symbol-function 'run-prolog))
523 @cindex autoload errors
524 The autoloaded file usually contains other definitions and may require
525 or provide one or more features. If the file is not completely loaded
526 (due to an error in the evaluation of its contents), any function
527 definitions or @code{provide} calls that occurred during the load are
528 undone. This is to ensure that the next attempt to call any function
529 autoloading from this file will try again to load the file. If not for
530 this, then some of the functions in the file might be defined by the
531 aborted load, but fail to work properly for the lack of certain
532 subroutines not loaded successfully because they come later in the file.
534 If the autoloaded file fails to define the desired Lisp function or
535 macro, then an error is signaled with data @code{"Autoloading failed to
536 define function @var{function-name}"}.
538 @findex update-file-autoloads
539 @findex update-directory-autoloads
540 @cindex magic autoload comment
541 @cindex autoload cookie
542 @anchor{autoload cookie}
543 A magic autoload comment (often called an @dfn{autoload cookie})
544 consists of @samp{;;;###autoload}, on a line by itself,
545 just before the real definition of the function in its
546 autoloadable source file. The command @kbd{M-x update-file-autoloads}
547 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
548 (The string that serves as the autoload cookie and the name of the
549 file generated by @code{update-file-autoloads} can be changed from the
550 above defaults, see below.)
551 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
552 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
553 autoloads for all files in the current directory.
555 The same magic comment can copy any kind of form into
556 @file{loaddefs.el}. The form following the magic comment is copied
557 verbatim, @emph{except} if it is one of the forms which the autoload
558 facility handles specially (e.g., by conversion into an
559 @code{autoload} call). The forms which are not copied verbatim are
563 @item Definitions for function or function-like objects:
564 @code{defun} and @code{defmacro}; also @code{cl-defun} and
565 @code{cl-defmacro} (@pxref{Argument Lists,,,cl,Common Lisp Extensions}),
566 and @code{define-overloadable-function} (see the commentary in
567 @file{mode-local.el}).
569 @item Definitions for major or minor modes:
570 @code{define-minor-mode}, @code{define-globalized-minor-mode},
571 @code{define-generic-mode}, @code{define-derived-mode},
572 @code{easy-mmode-define-minor-mode},
573 @code{easy-mmode-define-global-mode}, @code{define-compilation-mode},
574 and @code{define-global-minor-mode}.
576 @item Other definition types:
577 @code{defcustom}, @code{defgroup}, @code{defclass}
578 (@pxref{Top,EIEIO,,eieio,EIEIO}), and @code{define-skeleton} (see the
579 commentary in @file{skeleton.el}).
582 You can also use a magic comment to execute a form at build time
583 @emph{without} executing it when the file itself is loaded. To do this,
584 write the form @emph{on the same line} as the magic comment. Since it
585 is in a comment, it does nothing when you load the source file; but
586 @kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
587 it is executed while building Emacs.
589 The following example shows how @code{doctor} is prepared for
590 autoloading with a magic comment:
595 "Switch to *doctor* buffer and start giving psychotherapy."
597 (switch-to-buffer "*doctor*")
602 Here's what that produces in @file{loaddefs.el}:
605 (autoload (quote doctor) "doctor" "\
606 Switch to *doctor* buffer and start giving psychotherapy.
612 @cindex @code{fn} in function's documentation string
613 The backslash and newline immediately following the double-quote are a
614 convention used only in the preloaded uncompiled Lisp files such as
615 @file{loaddefs.el}; they tell @code{make-docfile} to put the
616 documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
617 See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)}
618 in the usage part of the documentation string is replaced with the
619 function's name when the various help functions (@pxref{Help
620 Functions}) display it.
622 If you write a function definition with an unusual macro that is not
623 one of the known and recognized function definition methods, use of an
624 ordinary magic autoload comment would copy the whole definition into
625 @code{loaddefs.el}. That is not desirable. You can put the desired
626 @code{autoload} call into @code{loaddefs.el} instead by writing this:
629 ;;;###autoload (autoload 'foo "myfile")
634 You can use a non-default string as the autoload cookie and have the
635 corresponding autoload calls written into a file whose name is
636 different from the default @file{loaddefs.el}. Emacs provides two
637 variables to control this:
639 @defvar generate-autoload-cookie
640 The value of this variable should be a string whose syntax is a Lisp
641 comment. @kbd{M-x update-file-autoloads} copies the Lisp form that
642 follows the cookie into the autoload file it generates. The default
643 value of this variable is @code{";;;###autoload"}.
646 @defvar generated-autoload-file
647 The value of this variable names an Emacs Lisp file where the autoload
648 calls should go. The default value is @file{loaddefs.el}, but you can
649 override that, e.g., in the ``Local Variables'' section of a
650 @file{.el} file (@pxref{File Local Variables}). The autoload file is
651 assumed to contain a trailer starting with a formfeed character.
654 The following function may be used to explicitly load the library
655 specified by an autoload object:
657 @defun autoload-do-load autoload &optional name macro-only
658 This function performs the loading specified by @var{autoload}, which
659 should be an autoload object. The optional argument @var{name}, if
660 non-@code{nil}, should be a symbol whose function value is
661 @var{autoload}; in that case, the return value of this function is the
662 symbol's new function value. If the value of the optional argument
663 @var{macro-only} is @code{macro}, this function avoids loading a
664 function, only a macro.
667 @node Repeated Loading
668 @section Repeated Loading
669 @cindex repeated loading
671 You can load a given file more than once in an Emacs session. For
672 example, after you have rewritten and reinstalled a function definition
673 by editing it in a buffer, you may wish to return to the original
674 version; you can do this by reloading the file it came from.
676 When you load or reload files, bear in mind that the @code{load} and
677 @code{load-library} functions automatically load a byte-compiled file
678 rather than a non-compiled file of similar name. If you rewrite a file
679 that you intend to save and reinstall, you need to byte-compile the new
680 version; otherwise Emacs will load the older, byte-compiled file instead
681 of your newer, non-compiled file! If that happens, the message
682 displayed when loading the file includes, @samp{(compiled; note, source is
683 newer)}, to remind you to recompile it.
685 When writing the forms in a Lisp library file, keep in mind that the
686 file might be loaded more than once. For example, think about whether
687 each variable should be reinitialized when you reload the library;
688 @code{defvar} does not change the value if the variable is already
689 initialized. (@xref{Defining Variables}.)
691 The simplest way to add an element to an alist is like this:
694 (push '(leif-mode " Leif") minor-mode-alist)
698 But this would add multiple elements if the library is reloaded. To
699 avoid the problem, use @code{add-to-list} (@pxref{List Variables}):
702 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
705 Occasionally you will want to test explicitly whether a library has
706 already been loaded. If the library uses @code{provide} to provide a
707 named feature, you can use @code{featurep} earlier in the file to test
708 whether the @code{provide} call has been executed before (@pxref{Named
709 Features}). Alternatively, you could use something like this:
712 (defvar foo-was-loaded nil)
714 (unless foo-was-loaded
715 @var{execute-first-time-only}
716 (setq foo-was-loaded t))
724 @cindex requiring features
725 @cindex providing features
727 @code{provide} and @code{require} are an alternative to
728 @code{autoload} for loading files automatically. They work in terms of
729 named @dfn{features}. Autoloading is triggered by calling a specific
730 function, but a feature is loaded the first time another program asks
733 A feature name is a symbol that stands for a collection of functions,
734 variables, etc. The file that defines them should @dfn{provide} the
735 feature. Another program that uses them may ensure they are defined by
736 @dfn{requiring} the feature. This loads the file of definitions if it
737 hasn't been loaded already.
739 @cindex load error with require
740 To require the presence of a feature, call @code{require} with the
741 feature name as argument. @code{require} looks in the global variable
742 @code{features} to see whether the desired feature has been provided
743 already. If not, it loads the feature from the appropriate file. This
744 file should call @code{provide} at the top level to add the feature to
745 @code{features}; if it fails to do so, @code{require} signals an error.
747 For example, in @file{idlwave.el}, the definition for
748 @code{idlwave-complete-filename} includes the following code:
751 (defun idlwave-complete-filename ()
752 "Use the comint stuff to complete a file name."
754 (let* ((comint-file-name-chars "~/A-Za-z0-9+@@:_.$#%=@{@}\\-")
755 (comint-completion-addsuffix nil)
757 (comint-dynamic-complete-filename)))
761 The expression @code{(require 'comint)} loads the file @file{comint.el}
762 if it has not yet been loaded, ensuring that
763 @code{comint-dynamic-complete-filename} is defined. Features are
764 normally named after the files that provide them, so that
765 @code{require} need not be given the file name. (Note that it is
766 important that the @code{require} statement be outside the body of the
767 @code{let}. Loading a library while its variables are let-bound can
768 have unintended consequences, namely the variables becoming unbound
769 after the let exits.)
771 The @file{comint.el} file contains the following top-level expression:
778 This adds @code{comint} to the global @code{features} list, so that
779 @code{(require 'comint)} will henceforth know that nothing needs to be
782 @cindex byte-compiling @code{require}
783 When @code{require} is used at top level in a file, it takes effect
784 when you byte-compile that file (@pxref{Byte Compilation}) as well as
785 when you load it. This is in case the required package contains macros
786 that the byte compiler must know about. It also avoids byte compiler
787 warnings for functions and variables defined in the file loaded with
790 Although top-level calls to @code{require} are evaluated during
791 byte compilation, @code{provide} calls are not. Therefore, you can
792 ensure that a file of definitions is loaded before it is byte-compiled
793 by including a @code{provide} followed by a @code{require} for the same
794 feature, as in the following example.
798 (provide 'my-feature) ; @r{Ignored by byte compiler,}
799 ; @r{evaluated by @code{load}.}
800 (require 'my-feature) ; @r{Evaluated by byte compiler.}
805 The compiler ignores the @code{provide}, then processes the
806 @code{require} by loading the file in question. Loading the file does
807 execute the @code{provide} call, so the subsequent @code{require} call
808 does nothing when the file is loaded.
810 @defun provide feature &optional subfeatures
811 This function announces that @var{feature} is now loaded, or being
812 loaded, into the current Emacs session. This means that the facilities
813 associated with @var{feature} are or will be available for other Lisp
816 The direct effect of calling @code{provide} is if not already in
817 @var{features} then to add @var{feature} to the front of that list and
818 call any @code{eval-after-load} code waiting for it (@pxref{Hooks for
819 Loading}). The argument @var{feature} must be a symbol.
820 @code{provide} returns @var{feature}.
822 If provided, @var{subfeatures} should be a list of symbols indicating
823 a set of specific subfeatures provided by this version of
824 @var{feature}. You can test the presence of a subfeature using
825 @code{featurep}. The idea of subfeatures is that you use them when a
826 package (which is one @var{feature}) is complex enough to make it
827 useful to give names to various parts or functionalities of the
828 package, which might or might not be loaded, or might or might not be
829 present in a given version. @xref{Network Feature Testing}, for
839 @result{} (foo bar bish)
842 When a file is loaded to satisfy an autoload, and it stops due to an
843 error in the evaluation of its contents, any function definitions or
844 @code{provide} calls that occurred during the load are undone.
848 @defun require feature &optional filename noerror
849 This function checks whether @var{feature} is present in the current
850 Emacs session (using @code{(featurep @var{feature})}; see below). The
851 argument @var{feature} must be a symbol.
853 If the feature is not present, then @code{require} loads @var{filename}
854 with @code{load}. If @var{filename} is not supplied, then the name of
855 the symbol @var{feature} is used as the base file name to load.
856 However, in this case, @code{require} insists on finding @var{feature}
857 with an added @samp{.el} or @samp{.elc} suffix (possibly extended with
858 a compression suffix); a file whose name is just @var{feature} won't
859 be used. (The variable @code{load-suffixes} specifies the exact
860 required Lisp suffixes.)
862 If @var{noerror} is non-@code{nil}, that suppresses errors from actual
863 loading of the file. In that case, @code{require} returns @code{nil}
864 if loading the file fails. Normally, @code{require} returns
867 If loading the file succeeds but does not provide @var{feature},
868 @code{require} signals an error, @samp{Required feature @var{feature}
872 @defun featurep feature &optional subfeature
873 This function returns @code{t} if @var{feature} has been provided in
874 the current Emacs session (i.e., if @var{feature} is a member of
875 @code{features}.) If @var{subfeature} is non-@code{nil}, then the
876 function returns @code{t} only if that subfeature is provided as well
877 (i.e., if @var{subfeature} is a member of the @code{subfeature}
878 property of the @var{feature} symbol.)
882 The value of this variable is a list of symbols that are the features
883 loaded in the current Emacs session. Each symbol was put in this list
884 with a call to @code{provide}. The order of the elements in the
885 @code{features} list is not significant.
889 @section Which File Defined a Certain Symbol
891 @defun symbol-file symbol &optional type
892 This function returns the name of the file that defined @var{symbol}.
893 If @var{type} is @code{nil}, then any kind of definition is acceptable.
894 If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that
895 specifies function definition, variable definition, or face definition
898 The value is normally an absolute file name. It can also be @code{nil},
899 if the definition is not associated with any file. If @var{symbol}
900 specifies an autoloaded function, the value can be a relative file name
904 The basis for @code{symbol-file} is the data in the variable
908 The value of this variable is an alist that associates the names of
909 loaded library files with the names of the functions and variables
910 they defined, as well as the features they provided or required.
912 Each element in this alist describes one loaded library (including
913 libraries that are preloaded at startup). It is a list whose @sc{car}
914 is the absolute file name of the library (a string). The rest of the
915 list elements have these forms:
919 The symbol @var{var} was defined as a variable.
920 @item (defun . @var{fun})
921 The function @var{fun} was defined.
922 @item (t . @var{fun})
923 The function @var{fun} was previously an autoload before this library
924 redefined it as a function. The following element is always
925 @code{(defun . @var{fun})}, which represents defining @var{fun} as a
927 @item (autoload . @var{fun})
928 The function @var{fun} was defined as an autoload.
929 @item (defface . @var{face})
930 The face @var{face} was defined.
931 @item (require . @var{feature})
932 The feature @var{feature} was required.
933 @item (provide . @var{feature})
934 The feature @var{feature} was provided.
937 The value of @code{load-history} may have one element whose @sc{car} is
938 @code{nil}. This element describes definitions made with
939 @code{eval-buffer} on a buffer that is not visiting a file.
942 The command @code{eval-region} updates @code{load-history}, but does so
943 by adding the symbols defined to the element for the file being visited,
944 rather than replacing that element. @xref{Eval}.
948 @cindex unloading packages
951 You can discard the functions and variables loaded by a library to
952 reclaim memory for other Lisp objects. To do this, use the function
953 @code{unload-feature}:
955 @deffn Command unload-feature feature &optional force
956 This command unloads the library that provided feature @var{feature}.
957 It undefines all functions, macros, and variables defined in that
958 library with @code{defun}, @code{defalias}, @code{defsubst},
959 @code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
960 It then restores any autoloads formerly associated with those symbols.
961 (Loading saves these in the @code{autoload} property of the symbol.)
963 Before restoring the previous definitions, @code{unload-feature} runs
964 @code{remove-hook} to remove functions in the library from certain
965 hooks. These hooks include variables whose names end in @samp{-hook}
966 (or the deprecated suffix @samp{-hooks}), plus those listed in
967 @code{unload-feature-special-hooks}, as well as
968 @code{auto-mode-alist}. This is to prevent Emacs from ceasing to
969 function because important hooks refer to functions that are no longer
972 Standard unloading activities also undoes ELP profiling of functions
973 in that library, unprovides any features provided by the library, and
974 cancels timers held in variables defined by the library.
976 @vindex @var{feature}-unload-function
977 If these measures are not sufficient to prevent malfunction, a library
978 can define an explicit unloader named @code{@var{feature}-unload-function}.
979 If that symbol is defined as a function, @code{unload-feature} calls
980 it with no arguments before doing anything else. It can do whatever
981 is appropriate to unload the library. If it returns @code{nil},
982 @code{unload-feature} proceeds to take the normal unload actions.
983 Otherwise it considers the job to be done.
985 Ordinarily, @code{unload-feature} refuses to unload a library on which
986 other loaded libraries depend. (A library @var{a} depends on library
987 @var{b} if @var{a} contains a @code{require} for @var{b}.) If the
988 optional argument @var{force} is non-@code{nil}, dependencies are
989 ignored and you can unload any library.
992 The @code{unload-feature} function is written in Lisp; its actions are
993 based on the variable @code{load-history}.
995 @defvar unload-feature-special-hooks
996 This variable holds a list of hooks to be scanned before unloading a
997 library, to remove functions defined in the library.
1000 @node Hooks for Loading
1001 @section Hooks for Loading
1002 @cindex loading hooks
1003 @cindex hooks for loading
1005 You can ask for code to be executed each time Emacs loads a library,
1006 by using the variable @code{after-load-functions}:
1008 @defvar after-load-functions
1009 This abnormal hook is run after loading a file. Each function in the
1010 hook is called with a single argument, the absolute filename of the
1011 file that was just loaded.
1014 If you want code to be executed when a @emph{particular} library is
1015 loaded, use the macro @code{with-eval-after-load}:
1017 @defmac with-eval-after-load library body@dots{}
1018 This macro arranges to evaluate @var{body} at the end of loading
1019 the file @var{library}, each time @var{library} is loaded. If
1020 @var{library} is already loaded, it evaluates @var{body} right away.
1022 You don't need to give a directory or extension in the file name
1023 @var{library}. Normally, you just give a bare file name, like this:
1026 (with-eval-after-load "edebug" (def-edebug-spec c-point t))
1029 To restrict which files can trigger the evaluation, include a
1030 directory or an extension or both in @var{library}. Only a file whose
1031 absolute true name (i.e., the name with all symbolic links chased out)
1032 matches all the given name components will match. In the following
1033 example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory
1034 @code{..../foo/bar} will trigger the evaluation, but not
1038 (with-eval-after-load "foo/bar/my_inst.elc" @dots{})
1041 @var{library} can also be a feature (i.e., a symbol), in which case
1042 @var{body} is evaluated at the end of any file where
1043 @code{(provide @var{library})} is called.
1045 An error in @var{body} does not undo the load, but does prevent
1046 execution of the rest of @var{body}.
1049 Normally, well-designed Lisp programs should not use
1050 @code{eval-after-load}. If you need to examine and set the variables
1051 defined in another library (those meant for outside use), you can do
1052 it immediately---there is no need to wait until the library is loaded.
1053 If you need to call functions defined by that library, you should load
1054 the library, preferably with @code{require} (@pxref{Named Features}).