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
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 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 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
119 in the echo area during loading unless @var{nomessage} is
123 Any unhandled errors while loading a file terminate loading. If the
124 load was done for the sake of @code{autoload}, any function definitions
125 made during the loading are undone.
128 If @code{load} can't find the file to load, then normally it signals the
129 error @code{file-error} (with @samp{Cannot open load file
130 @var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
131 @code{load} just returns @code{nil}.
133 You can use the variable @code{load-read-function} to specify a function
134 for @code{load} to use instead of @code{read} for reading expressions.
137 @code{load} returns @code{t} if the file loads successfully.
140 @deffn Command load-file filename
141 This command loads the file @var{filename}. If @var{filename} is a
142 relative file name, then the current default directory is assumed.
143 This command does not use @code{load-path}, and does not append
144 suffixes. However, it does look for compressed versions (if Auto
145 Compression Mode is enabled). Use this command if you wish to specify
146 precisely the file name to load.
149 @deffn Command load-library library
150 This command loads the library named @var{library}. It is equivalent to
151 @code{load}, except for the way it reads its argument interactively.
152 @xref{Lisp Libraries,,,emacs, The GNU Emacs Manual}.
155 @defvar load-in-progress
156 This variable is non-@code{nil} if Emacs is in the process of loading a
157 file, and it is @code{nil} otherwise.
160 @defvar load-read-function
161 @anchor{Definition of load-read-function}
162 @c do not allow page break at anchor; work around Texinfo deficiency.
163 This variable specifies an alternate expression-reading function for
164 @code{load} and @code{eval-region} to use instead of @code{read}.
165 The function should accept one argument, just as @code{read} does.
167 Normally, the variable's value is @code{nil}, which means those
168 functions should use @code{read}.
170 Instead of using this variable, it is cleaner to use another, newer
171 feature: to pass the function as the @var{read-function} argument to
172 @code{eval-region}. @xref{Definition of eval-region,, Eval}.
175 For information about how @code{load} is used in building Emacs, see
176 @ref{Building Emacs}.
179 @section Load Suffixes
180 We now describe some technical details about the exact suffixes that
183 @defvar load-suffixes
184 This is a list of suffixes indicating (compiled or source) Emacs Lisp
185 files. It should not include the empty string. @code{load} uses
186 these suffixes in order when it appends Lisp suffixes to the specified
187 file name. The standard value is @code{(".elc" ".el")} which produces
188 the behavior described in the previous section.
191 @defvar load-file-rep-suffixes
192 This is a list of suffixes that indicate representations of the same
193 file. This list should normally start with the empty string.
194 When @code{load} searches for a file it appends the suffixes in this
195 list, in order, to the file name, before searching for another file.
197 Enabling Auto Compression mode appends the suffixes in
198 @code{jka-compr-load-suffixes} to this list and disabling Auto
199 Compression mode removes them again. The standard value of
200 @code{load-file-rep-suffixes} if Auto Compression mode is disabled is
201 @code{("")}. Given that the standard value of
202 @code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value
203 of @code{load-file-rep-suffixes} if Auto Compression mode is enabled
204 is @code{("" ".gz")}.
207 @defun get-load-suffixes
208 This function returns the list of all suffixes that @code{load} should
209 try, in order, when its @var{must-suffix} argument is non-@code{nil}.
210 This takes both @code{load-suffixes} and @code{load-file-rep-suffixes}
211 into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes}
212 and @code{load-file-rep-suffixes} all have their standard values, this
213 function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto
214 Compression mode is enabled and @code{(".elc" ".el")} if Auto
215 Compression mode is disabled.
218 To summarize, @code{load} normally first tries the suffixes in the
219 value of @code{(get-load-suffixes)} and then those in
220 @code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil},
221 it skips the former group, and if @var{must-suffix} is non-@code{nil},
222 it skips the latter group.
225 @section Library Search
226 @cindex library search
229 When Emacs loads a Lisp library, it searches for the library
230 in a list of directories specified by the variable @code{load-path}.
233 @cindex @code{EMACSLOADPATH} environment variable
234 The value of this variable is a list of directories to search when
235 loading files with @code{load}. Each element is a string (which must be
236 a directory name) or @code{nil} (which stands for the current working
240 The value of @code{load-path} is initialized from the environment
241 variable @code{EMACSLOADPATH}, if that exists; otherwise its default
242 value is specified in @file{emacs/src/epaths.h} when Emacs is built.
243 Then the list is expanded by adding subdirectories of the directories
246 The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
247 @samp{:} (or @samp{;}, according to the operating system) separates
248 directory names, and @samp{.} is used for the current default directory.
249 Here is an example of how to set your @code{EMACSLOADPATH} variable from
250 a @code{csh} @file{.login} file:
253 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
256 Here is how to set it using @code{sh}:
260 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
263 Here is an example of code you can place in your init file (@pxref{Init
264 File}) to add several directories to the front of your default
270 (append (list nil "/user/bil/emacs"
277 @c Wordy to rid us of an overfull hbox. --rjc 15mar92
279 In this example, the path searches the current working directory first,
280 followed then by the @file{/user/bil/emacs} directory, the
281 @file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
282 which are then followed by the standard directories for Lisp code.
284 Dumping Emacs uses a special value of @code{load-path}. If the value of
285 @code{load-path} at the end of dumping is unchanged (that is, still the
286 same special value), the dumped Emacs switches to the ordinary
287 @code{load-path} value when it starts up, as described above. But if
288 @code{load-path} has any other value at the end of dumping, that value
289 is used for execution of the dumped Emacs also.
291 Therefore, if you want to change @code{load-path} temporarily for
292 loading a few libraries in @file{site-init.el} or @file{site-load.el},
293 you should bind @code{load-path} locally with @code{let} around the
294 calls to @code{load}.
296 The default value of @code{load-path}, when running an Emacs which has
297 been installed on the system, includes two special directories (and
298 their subdirectories as well):
301 "/usr/local/share/emacs/@var{version}/site-lisp"
308 "/usr/local/share/emacs/site-lisp"
312 The first one is for locally installed packages for a particular Emacs
313 version; the second is for locally installed packages meant for use with
314 all installed Emacs versions.
316 There are several reasons why a Lisp package that works well in one
317 Emacs version can cause trouble in another. Sometimes packages need
318 updating for incompatible changes in Emacs; sometimes they depend on
319 undocumented internal Emacs data that can change without notice;
320 sometimes a newer Emacs version incorporates a version of the package,
321 and should be used only with that version.
323 Emacs finds these directories' subdirectories and adds them to
324 @code{load-path} when it starts up. Both immediate subdirectories and
325 subdirectories multiple levels down are added to @code{load-path}.
327 Not all subdirectories are included, though. Subdirectories whose
328 names do not start with a letter or digit are excluded. Subdirectories
329 named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which
330 contains a file named @file{.nosearch} is excluded. You can use these
331 methods to prevent certain subdirectories of the @file{site-lisp}
332 directories from being searched.
334 If you run Emacs from the directory where it was built---that is, an
335 executable that has not been formally installed---then @code{load-path}
336 normally contains two additional directories. These are the @code{lisp}
337 and @code{site-lisp} subdirectories of the main build directory. (Both
338 are represented as absolute file names.)
340 @deffn Command locate-library library &optional nosuffix path interactive-call
341 This command finds the precise file name for library @var{library}. It
342 searches for the library in the same way @code{load} does, and the
343 argument @var{nosuffix} has the same meaning as in @code{load}: don't
344 add suffixes @samp{.elc} or @samp{.el} to the specified name
347 If the @var{path} is non-@code{nil}, that list of directories is used
348 instead of @code{load-path}.
350 When @code{locate-library} is called from a program, it returns the file
351 name as a string. When the user runs @code{locate-library}
352 interactively, the argument @var{interactive-call} is @code{t}, and this
353 tells @code{locate-library} to display the file name in the echo area.
356 @node Loading Non-ASCII
357 @section Loading Non-@acronym{ASCII} Characters
359 When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
360 characters, these can be represented within Emacs either as unibyte
361 strings or as multibyte strings (@pxref{Text Representations}). Which
362 representation is used depends on how the file is read into Emacs. If
363 it is read with decoding into multibyte representation, the text of the
364 Lisp program will be multibyte text, and its string constants will be
365 multibyte strings. If a file containing Latin-1 characters (for
366 example) is read without decoding, the text of the program will be
367 unibyte text, and its string constants will be unibyte strings.
368 @xref{Coding Systems}.
370 To make the results more predictable, Emacs always performs decoding
371 into the multibyte representation when loading Lisp files, even if it
372 was started with the @samp{--unibyte} option. This means that string
373 constants with non-@acronym{ASCII} characters translate into multibyte
374 strings. The only exception is when a particular file specifies no
377 The reason Emacs is designed this way is so that Lisp programs give
378 predictable results, regardless of how Emacs was started. In addition,
379 this enables programs that depend on using multibyte text to work even
382 In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are
383 multibyte strings should not be noticeable, since inserting them in
384 unibyte buffers converts them to unibyte automatically. However, if
385 this does make a difference, you can force a particular Lisp file to be
386 interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
387 comment on the file's first line. With that designator, the file will
388 unconditionally be interpreted as unibyte, even in an ordinary
389 multibyte Emacs session. This can matter when making keybindings to
390 non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
396 The @dfn{autoload} facility allows you to make a function or macro
397 known in Lisp, but put off loading the file that defines it. The first
398 call to the function automatically reads the proper file to install the
399 real definition and other associated code, then runs the real definition
400 as if it had been loaded all along.
402 There are two ways to set up an autoloaded function: by calling
403 @code{autoload}, and by writing a special ``magic'' comment in the
404 source before the real definition. @code{autoload} is the low-level
405 primitive for autoloading; any Lisp program can call @code{autoload} at
406 any time. Magic comments are the most convenient way to make a function
407 autoload, for packages installed along with Emacs. These comments do
408 nothing on their own, but they serve as a guide for the command
409 @code{update-file-autoloads}, which constructs calls to @code{autoload}
410 and arranges to execute them when Emacs is built.
412 @defun autoload function filename &optional docstring interactive type
413 This function defines the function (or macro) named @var{function} so as
414 to load automatically from @var{filename}. The string @var{filename}
415 specifies the file to load to get the real definition of @var{function}.
417 If @var{filename} does not contain either a directory name, or the
418 suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
419 one of these suffixes, and it will not load from a file whose name is
420 just @var{filename} with no added suffix. (The variable
421 @code{load-suffixes} specifies the exact required suffixes.)
423 The argument @var{docstring} is the documentation string for the
424 function. Specifying the documentation string in the call to
425 @code{autoload} makes it possible to look at the documentation without
426 loading the function's real definition. Normally, this should be
427 identical to the documentation string in the function definition
428 itself. If it isn't, the function definition's documentation string
429 takes effect when it is loaded.
431 If @var{interactive} is non-@code{nil}, that says @var{function} can be
432 called interactively. This lets completion in @kbd{M-x} work without
433 loading @var{function}'s real definition. The complete interactive
434 specification is not given here; it's not needed unless the user
435 actually calls @var{function}, and when that happens, it's time to load
438 You can autoload macros and keymaps as well as ordinary functions.
439 Specify @var{type} as @code{macro} if @var{function} is really a macro.
440 Specify @var{type} as @code{keymap} if @var{function} is really a
441 keymap. Various parts of Emacs need to know this information without
442 loading the real definition.
444 An autoloaded keymap loads automatically during key lookup when a prefix
445 key's binding is the symbol @var{function}. Autoloading does not occur
446 for other kinds of access to the keymap. In particular, it does not
447 happen when a Lisp program gets the keymap from the value of a variable
448 and calls @code{define-key}; not even if the variable name is the same
449 symbol @var{function}.
451 @cindex function cell in autoload
452 If @var{function} already has a non-void function definition that is not
453 an autoload object, @code{autoload} does nothing and returns @code{nil}.
454 If the function cell of @var{function} is void, or is already an autoload
455 object, then it is defined as an autoload object like this:
458 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
465 (symbol-function 'run-prolog)
466 @result{} (autoload "prolog" 169681 t nil)
471 In this case, @code{"prolog"} is the name of the file to load, 169681
472 refers to the documentation string in the
473 @file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
474 @code{t} means the function is interactive, and @code{nil} that it is
475 not a macro or a keymap.
478 @cindex autoload errors
479 The autoloaded file usually contains other definitions and may require
480 or provide one or more features. If the file is not completely loaded
481 (due to an error in the evaluation of its contents), any function
482 definitions or @code{provide} calls that occurred during the load are
483 undone. This is to ensure that the next attempt to call any function
484 autoloading from this file will try again to load the file. If not for
485 this, then some of the functions in the file might be defined by the
486 aborted load, but fail to work properly for the lack of certain
487 subroutines not loaded successfully because they come later in the file.
489 If the autoloaded file fails to define the desired Lisp function or
490 macro, then an error is signaled with data @code{"Autoloading failed to
491 define function @var{function-name}"}.
493 @findex update-file-autoloads
494 @findex update-directory-autoloads
495 @cindex magic autoload comment
496 @cindex autoload cookie
497 @anchor{autoload cookie}
498 A magic autoload comment (often called an @dfn{autoload cookie})
499 consists of @samp{;;;###autoload}, on a line by itself,
500 just before the real definition of the function in its
501 autoloadable source file. The command @kbd{M-x update-file-autoloads}
502 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
503 (The string that serves as the autoload cookie and the name of the
504 file generated by @code{update-file-autoloads} can be changed from the
505 above defaults, see below.)
506 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
507 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
508 autoloads for all files in the current directory.
510 The same magic comment can copy any kind of form into
511 @file{loaddefs.el}. If the form following the magic comment is not a
512 function-defining form or a @code{defcustom} form, it is copied
513 verbatim. ``Function-defining forms'' include @code{define-skeleton},
514 @code{define-derived-mode}, @code{define-generic-mode} and
515 @code{define-minor-mode} as well as @code{defun} and
516 @code{defmacro}. To save space, a @code{defcustom} form is converted to
517 a @code{defvar} in @file{loaddefs.el}, with some additional information
518 if it uses @code{:require}.
520 You can also use a magic comment to execute a form at build time
521 @emph{without} executing it when the file itself is loaded. To do this,
522 write the form @emph{on the same line} as the magic comment. Since it
523 is in a comment, it does nothing when you load the source file; but
524 @kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
525 it is executed while building Emacs.
527 The following example shows how @code{doctor} is prepared for
528 autoloading with a magic comment:
533 "Switch to *doctor* buffer and start giving psychotherapy."
535 (switch-to-buffer "*doctor*")
540 Here's what that produces in @file{loaddefs.el}:
543 (autoload (quote doctor) "doctor" "\
544 Switch to *doctor* buffer and start giving psychotherapy.
550 @cindex @code{fn} in function's documentation string
551 The backslash and newline immediately following the double-quote are a
552 convention used only in the preloaded uncompiled Lisp files such as
553 @file{loaddefs.el}; they tell @code{make-docfile} to put the
554 documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
555 See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)}
556 in the usage part of the documentation string is replaced with the
557 function's name when the various help functions (@pxref{Help
558 Functions}) display it.
560 If you write a function definition with an unusual macro that is not
561 one of the known and recognized function definition methods, use of an
562 ordinary magic autoload comment would copy the whole definition into
563 @code{loaddefs.el}. That is not desirable. You can put the desired
564 @code{autoload} call into @code{loaddefs.el} instead by writing this:
567 ;;;###autoload (autoload 'foo "myfile")
572 You can use a non-default string as the autoload cookie and have the
573 corresponding autoload calls written into a file whose name is
574 different from the default @file{loaddefs.el}. Emacs provides two
575 variables to control this:
577 @defvar generate-autoload-cookie
578 The value of this variable should be a string whose syntax is a Lisp
579 comment. @kbd{M-x update-file-autoloads} copies the Lisp form that
580 follows the cookie into the autoload file it generates. The default
581 value of this variable is @code{";;;###autoload"}.
584 @defvar generated-autoload-file
585 The value of this variable names an Emacs Lisp file where the autoload
586 calls should go. The default value is @file{loaddefs.el}, but you can
587 override that, e.g., in the ``Local Variables'' section of a
588 @file{.el} file (@pxref{File Local Variables}). The autoload file is
589 assumed to contain a trailer starting with a formfeed character.
592 @node Repeated Loading
593 @section Repeated Loading
594 @cindex repeated loading
596 You can load a given file more than once in an Emacs session. For
597 example, after you have rewritten and reinstalled a function definition
598 by editing it in a buffer, you may wish to return to the original
599 version; you can do this by reloading the file it came from.
601 When you load or reload files, bear in mind that the @code{load} and
602 @code{load-library} functions automatically load a byte-compiled file
603 rather than a non-compiled file of similar name. If you rewrite a file
604 that you intend to save and reinstall, you need to byte-compile the new
605 version; otherwise Emacs will load the older, byte-compiled file instead
606 of your newer, non-compiled file! If that happens, the message
607 displayed when loading the file includes, @samp{(compiled; note, source is
608 newer)}, to remind you to recompile it.
610 When writing the forms in a Lisp library file, keep in mind that the
611 file might be loaded more than once. For example, think about whether
612 each variable should be reinitialized when you reload the library;
613 @code{defvar} does not change the value if the variable is already
614 initialized. (@xref{Defining Variables}.)
616 The simplest way to add an element to an alist is like this:
619 (push '(leif-mode " Leif") minor-mode-alist)
623 But this would add multiple elements if the library is reloaded. To
624 avoid the problem, use @code{add-to-list} (@pxref{List Variables}):
627 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
630 Occasionally you will want to test explicitly whether a library has
631 already been loaded. If the library uses @code{provide} to provide a
632 named feature, you can use @code{featurep} earlier in the file to test
633 whether the @code{provide} call has been executed before (@pxref{Named
634 Features}). Alternatively, you could use something like this:
637 (defvar foo-was-loaded nil)
639 (unless foo-was-loaded
640 @var{execute-first-time-only}
641 (setq foo-was-loaded t))
649 @cindex requiring features
650 @cindex providing features
652 @code{provide} and @code{require} are an alternative to
653 @code{autoload} for loading files automatically. They work in terms of
654 named @dfn{features}. Autoloading is triggered by calling a specific
655 function, but a feature is loaded the first time another program asks
658 A feature name is a symbol that stands for a collection of functions,
659 variables, etc. The file that defines them should @dfn{provide} the
660 feature. Another program that uses them may ensure they are defined by
661 @dfn{requiring} the feature. This loads the file of definitions if it
662 hasn't been loaded already.
664 @cindex load error with require
665 To require the presence of a feature, call @code{require} with the
666 feature name as argument. @code{require} looks in the global variable
667 @code{features} to see whether the desired feature has been provided
668 already. If not, it loads the feature from the appropriate file. This
669 file should call @code{provide} at the top level to add the feature to
670 @code{features}; if it fails to do so, @code{require} signals an error.
672 For example, in @file{emacs/lisp/prolog.el},
673 the definition for @code{run-prolog} includes the following code:
677 "Run an inferior Prolog process, with I/O via buffer *prolog*."
680 (switch-to-buffer (make-comint "prolog" prolog-program-name))
681 (inferior-prolog-mode))
685 The expression @code{(require 'comint)} loads the file @file{comint.el}
686 if it has not yet been loaded. This ensures that @code{make-comint} is
687 defined. Features are normally named after the files that provide them,
688 so that @code{require} need not be given the file name.
690 The @file{comint.el} file contains the following top-level expression:
697 This adds @code{comint} to the global @code{features} list, so that
698 @code{(require 'comint)} will henceforth know that nothing needs to be
701 @cindex byte-compiling @code{require}
702 When @code{require} is used at top level in a file, it takes effect
703 when you byte-compile that file (@pxref{Byte Compilation}) as well as
704 when you load it. This is in case the required package contains macros
705 that the byte compiler must know about. It also avoids byte compiler
706 warnings for functions and variables defined in the file loaded with
709 Although top-level calls to @code{require} are evaluated during
710 byte compilation, @code{provide} calls are not. Therefore, you can
711 ensure that a file of definitions is loaded before it is byte-compiled
712 by including a @code{provide} followed by a @code{require} for the same
713 feature, as in the following example.
717 (provide 'my-feature) ; @r{Ignored by byte compiler,}
718 ; @r{evaluated by @code{load}.}
719 (require 'my-feature) ; @r{Evaluated by byte compiler.}
724 The compiler ignores the @code{provide}, then processes the
725 @code{require} by loading the file in question. Loading the file does
726 execute the @code{provide} call, so the subsequent @code{require} call
727 does nothing when the file is loaded.
729 @defun provide feature &optional subfeatures
730 This function announces that @var{feature} is now loaded, or being
731 loaded, into the current Emacs session. This means that the facilities
732 associated with @var{feature} are or will be available for other Lisp
735 The direct effect of calling @code{provide} is if not already in
736 @var{features} then to add @var{feature} to the front of that list and
737 call any @code{eval-after-load} code waiting for it (@pxref{Hooks for
738 Loading}). The argument @var{feature} must be a symbol.
739 @code{provide} returns @var{feature}.
741 If provided, @var{subfeatures} should be a list of symbols indicating
742 a set of specific subfeatures provided by this version of
743 @var{feature}. You can test the presence of a subfeature using
744 @code{featurep}. The idea of subfeatures is that you use them when a
745 package (which is one @var{feature}) is complex enough to make it
746 useful to give names to various parts or functionalities of the
747 package, which might or might not be loaded, or might or might not be
748 present in a given version. @xref{Network Feature Testing}, for
758 @result{} (foo bar bish)
761 When a file is loaded to satisfy an autoload, and it stops due to an
762 error in the evaluation of its contents, any function definitions or
763 @code{provide} calls that occurred during the load are undone.
767 @defun require feature &optional filename noerror
768 This function checks whether @var{feature} is present in the current
769 Emacs session (using @code{(featurep @var{feature})}; see below). The
770 argument @var{feature} must be a symbol.
772 If the feature is not present, then @code{require} loads @var{filename}
773 with @code{load}. If @var{filename} is not supplied, then the name of
774 the symbol @var{feature} is used as the base file name to load.
775 However, in this case, @code{require} insists on finding @var{feature}
776 with an added @samp{.el} or @samp{.elc} suffix (possibly extended with
777 a compression suffix); a file whose name is just @var{feature} won't
778 be used. (The variable @code{load-suffixes} specifies the exact
779 required Lisp suffixes.)
781 If @var{noerror} is non-@code{nil}, that suppresses errors from actual
782 loading of the file. In that case, @code{require} returns @code{nil}
783 if loading the file fails. Normally, @code{require} returns
786 If loading the file succeeds but does not provide @var{feature},
787 @code{require} signals an error, @samp{Required feature @var{feature}
791 @defun featurep feature &optional subfeature
792 This function returns @code{t} if @var{feature} has been provided in
793 the current Emacs session (i.e.@:, if @var{feature} is a member of
794 @code{features}.) If @var{subfeature} is non-@code{nil}, then the
795 function returns @code{t} only if that subfeature is provided as well
796 (i.e.@: if @var{subfeature} is a member of the @code{subfeature}
797 property of the @var{feature} symbol.)
801 The value of this variable is a list of symbols that are the features
802 loaded in the current Emacs session. Each symbol was put in this list
803 with a call to @code{provide}. The order of the elements in the
804 @code{features} list is not significant.
808 @section Which File Defined a Certain Symbol
810 @defun symbol-file symbol &optional type
811 This function returns the name of the file that defined @var{symbol}.
812 If @var{type} is @code{nil}, then any kind of definition is acceptable.
813 If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that
814 specifies function definition, variable definition, or face definition
817 The value is normally an absolute file name. It can also be @code{nil},
818 if the definition is not associated with any file. If @var{symbol}
819 specifies an autoloaded function, the value can be a relative file name
823 The basis for @code{symbol-file} is the data in the variable
827 The value of this variable is an alist that associates the names of
828 loaded library files with the names of the functions and variables
829 they defined, as well as the features they provided or required.
831 Each element in this alist describes one loaded library (including
832 libraries that are preloaded at startup). It is a list whose @sc{car}
833 is the absolute file name of the library (a string). The rest of the
834 list elements have these forms:
838 The symbol @var{var} was defined as a variable.
839 @item (defun . @var{fun})
840 The function @var{fun} was defined.
841 @item (t . @var{fun})
842 The function @var{fun} was previously an autoload before this library
843 redefined it as a function. The following element is always
844 @code{(defun . @var{fun})}, which represents defining @var{fun} as a
846 @item (autoload . @var{fun})
847 The function @var{fun} was defined as an autoload.
848 @item (defface . @var{face})
849 The face @var{face} was defined.
850 @item (require . @var{feature})
851 The feature @var{feature} was required.
852 @item (provide . @var{feature})
853 The feature @var{feature} was provided.
856 The value of @code{load-history} may have one element whose @sc{car} is
857 @code{nil}. This element describes definitions made with
858 @code{eval-buffer} on a buffer that is not visiting a file.
861 The command @code{eval-region} updates @code{load-history}, but does so
862 by adding the symbols defined to the element for the file being visited,
863 rather than replacing that element. @xref{Eval}.
867 @cindex unloading packages
870 You can discard the functions and variables loaded by a library to
871 reclaim memory for other Lisp objects. To do this, use the function
872 @code{unload-feature}:
874 @deffn Command unload-feature feature &optional force
875 This command unloads the library that provided feature @var{feature}.
876 It undefines all functions, macros, and variables defined in that
877 library with @code{defun}, @code{defalias}, @code{defsubst},
878 @code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
879 It then restores any autoloads formerly associated with those symbols.
880 (Loading saves these in the @code{autoload} property of the symbol.)
882 Before restoring the previous definitions, @code{unload-feature} runs
883 @code{remove-hook} to remove functions in the library from certain
884 hooks. These hooks include variables whose names end in @samp{hook}
885 or @samp{-hooks}, plus those listed in
886 @code{unload-feature-special-hooks}, as well as
887 @code{auto-mode-alist}. This is to prevent Emacs from ceasing to
888 function because important hooks refer to functions that are no longer
891 Standard unloading activities also undoes ELP profiling of functions
892 in that library, unprovides any features provided by the library, and
893 cancels timers held in variables defined by the library.
895 @vindex @var{feature}-unload-function
896 If these measures are not sufficient to prevent malfunction, a library
897 can define an explicit unloader named @code{@var{feature}-unload-function}.
898 If that symbol is defined as a function, @code{unload-feature} calls
899 it with no arguments before doing anything else. It can do whatever
900 is appropriate to unload the library. If it returns @code{nil},
901 @code{unload-feature} proceeds to take the normal unload actions.
902 Otherwise it considers the job to be done.
904 Ordinarily, @code{unload-feature} refuses to unload a library on which
905 other loaded libraries depend. (A library @var{a} depends on library
906 @var{b} if @var{a} contains a @code{require} for @var{b}.) If the
907 optional argument @var{force} is non-@code{nil}, dependencies are
908 ignored and you can unload any library.
911 The @code{unload-feature} function is written in Lisp; its actions are
912 based on the variable @code{load-history}.
914 @defvar unload-feature-special-hooks
915 This variable holds a list of hooks to be scanned before unloading a
916 library, to remove functions defined in the library.
919 @node Hooks for Loading
920 @section Hooks for Loading
921 @cindex loading hooks
922 @cindex hooks for loading
924 You can ask for code to be executed each time Emacs loads a library,
925 by using the variable @code{after-load-functions}:
927 @defvar after-load-functions
928 This abnormal hook is run after loading a file. Each function in the
929 hook is called with a single argument, the absolute filename of the
930 file that was just loaded.
933 If you want code to be executed when a @emph{particular} library is
934 loaded, use the function @code{eval-after-load}:
936 @defun eval-after-load library form
937 This function arranges to evaluate @var{form} at the end of loading
938 the file @var{library}, each time @var{library} is loaded. If
939 @var{library} is already loaded, it evaluates @var{form} right away.
940 Don't forget to quote @var{form}!
942 You don't need to give a directory or extension in the file name
943 @var{library}. Normally, you just give a bare file name, like this:
946 (eval-after-load "edebug" '(def-edebug-spec c-point t))
949 To restrict which files can trigger the evaluation, include a
950 directory or an extension or both in @var{library}. Only a file whose
951 absolute true name (i.e., the name with all symbolic links chased out)
952 matches all the given name components will match. In the following
953 example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory
954 @code{..../foo/bar} will trigger the evaluation, but not
958 (eval-after-load "foo/bar/my_inst.elc" @dots{})
961 @var{library} can also be a feature (i.e.@: a symbol), in which case
962 @var{form} is evaluated when @code{(provide @var{library})} is called.
964 An error in @var{form} does not undo the load, but does prevent
965 execution of the rest of @var{form}.
968 Normally, well-designed Lisp programs should not use
969 @code{eval-after-load}. If you need to examine and set the variables
970 defined in another library (those meant for outside use), you can do
971 it immediately---there is no need to wait until the library is loaded.
972 If you need to call functions defined by that library, you should load
973 the library, preferably with @code{require} (@pxref{Named Features}).
975 But it is OK to use @code{eval-after-load} in your personal
976 customizations if you don't feel that they must meet the design
977 standards for programs meant for wider use.
979 @defvar after-load-alist
980 This variable stores an alist built by @code{eval-after-load},
981 containing the expressions to evaluate when certain libraries are
982 loaded. Each element looks like this:
985 (@var{regexp-or-feature} @var{forms}@dots{})
988 The key @var{regexp-or-feature} is either a regular expression or a
989 symbol, and the value is a list of forms. The forms are evaluated
990 when the key matches the absolute true name or feature name of the
991 library being loaded.
995 arch-tag: df731f89-0900-4389-a436-9105241b6f7a