2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/loading
7 @node Loading, Byte Compilation, Customization, Top
13 Loading a file of Lisp code means bringing its contents into the
14 Lisp environment in the form of Lisp objects. Emacs finds and opens
15 the file, reads the text, evaluates each form, and then closes the
16 file. Such a file is also called a @dfn{Lisp library}.
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
34 * How Programs Do Loading:: The @code{load} function and others.
35 * Load Suffixes:: Details about the suffixes that @code{load} tries.
36 * Library Search:: Finding a library to load.
37 * Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files.
38 * Autoload:: Setting up a function to autoload.
39 * Repeated Loading:: Precautions about loading a file twice.
40 * Named Features:: Loading a library if it isn't already loaded.
41 * Where Defined:: Finding which file defined a certain symbol.
42 * Unloading:: How to "unload" a library that was loaded.
43 * Hooks for Loading:: Providing code to be run when
44 particular libraries are loaded.
47 @node How Programs Do Loading
48 @section How Programs Do Loading
50 Emacs Lisp has several interfaces for loading. For example,
51 @code{autoload} creates a placeholder object for a function defined in a
52 file; trying to call the autoloading function loads the file to get the
53 function's real definition (@pxref{Autoload}). @code{require} loads a
54 file if it isn't already loaded (@pxref{Named Features}). Ultimately,
55 all these facilities call the @code{load} function to do the work.
57 @defun load filename &optional missing-ok nomessage nosuffix must-suffix
58 This function finds and opens a file of Lisp code, evaluates all the
59 forms in it, and closes the file.
61 To find the file, @code{load} first looks for a file named
62 @file{@var{filename}.elc}, that is, for a file whose name is
63 @var{filename} with the extension @samp{.elc} appended. If such a
64 file exists, it is loaded. If there is no file by that name, then
65 @code{load} looks for a file named @file{@var{filename}.el}. If that
66 file exists, it is loaded. Finally, if neither of those names is
67 found, @code{load} looks for a file named @var{filename} with nothing
68 appended, and loads it if it exists. (The @code{load} function is not
69 clever about looking at @var{filename}. In the perverse case of a
70 file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will
73 If Auto Compression mode is enabled, as it is by default, then if
74 @code{load} can not find a file, it searches for a compressed version
75 of the file before trying other file names. It decompresses and loads
76 it if it exists. It looks for compressed versions by appending each
77 of the suffixes in @code{jka-compr-load-suffixes} to the file name.
78 The value of this variable must be a list of strings. Its standard
79 value is @code{(".gz")}.
81 If the optional argument @var{nosuffix} is non-@code{nil}, then
82 @code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In
83 this case, you must specify the precise file name you want, except
84 that, if Auto Compression mode is enabled, @code{load} will still use
85 @code{jka-compr-load-suffixes} to find compressed versions. By
86 specifying the precise file name and using @code{t} for
87 @var{nosuffix}, you can prevent file names like @file{foo.el.el} from
90 If the optional argument @var{must-suffix} is non-@code{nil}, then
91 @code{load} insists that the file name used must end in either
92 @samp{.el} or @samp{.elc} (possibly extended with a compression
93 suffix), unless it contains an explicit directory name.
95 If @var{filename} is a relative file name, such as @file{foo} or
96 @file{baz/foo.bar}, @code{load} searches for the file using the variable
97 @code{load-path}. It appends @var{filename} to each of the directories
98 listed in @code{load-path}, and loads the first file it finds whose name
99 matches. The current default directory is tried only if it is specified
100 in @code{load-path}, where @code{nil} stands for the default directory.
101 @code{load} tries all three possible suffixes in the first directory in
102 @code{load-path}, then all three suffixes in the second directory, and
103 so on. @xref{Library Search}.
105 Whatever the name under which the file is eventually found, and the
106 directory where Emacs found it, Emacs sets the value of the variable
107 @code{load-file-name} to that file's name.
109 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
110 means you should consider recompiling @file{foo.el}. @xref{Byte
113 When loading a source file (not compiled), @code{load} performs
114 character set translation just as Emacs would do when visiting the file.
115 @xref{Coding Systems}.
117 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
118 in the echo area during loading unless @var{nomessage} is
122 Any unhandled errors while loading a file terminate loading. If the
123 load was done for the sake of @code{autoload}, any function definitions
124 made during the loading are undone.
127 If @code{load} can't find the file to load, then normally it signals the
128 error @code{file-error} (with @samp{Cannot open load file
129 @var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
130 @code{load} just returns @code{nil}.
132 You can use the variable @code{load-read-function} to specify a function
133 for @code{load} to use instead of @code{read} for reading expressions.
136 @code{load} returns @code{t} if the file loads successfully.
139 @deffn Command load-file filename
140 This command loads the file @var{filename}. If @var{filename} is a
141 relative file name, then the current default directory is assumed.
142 This command does not use @code{load-path}, and does not append
143 suffixes. However, it does look for compressed versions (if Auto
144 Compression Mode is enabled). Use this command if you wish to specify
145 precisely the file name to load.
148 @deffn Command load-library library
149 This command loads the library named @var{library}. It is equivalent to
150 @code{load}, except for the way it reads its argument interactively.
151 @xref{Lisp Libraries,,,emacs, The GNU Emacs Manual}.
154 @defvar load-in-progress
155 This variable is non-@code{nil} if Emacs is in the process of loading a
156 file, and it is @code{nil} otherwise.
159 @defvar load-file-name
160 When Emacs is in the process of loading a file, this variable's value
161 is the name of that file, as Emacs found it during the search
162 described earlier in this section.
165 @defvar load-read-function
166 @anchor{Definition of load-read-function}
167 @c do not allow page break at anchor; work around Texinfo deficiency.
168 This variable specifies an alternate expression-reading function for
169 @code{load} and @code{eval-region} to use instead of @code{read}.
170 The function should accept one argument, just as @code{read} does.
172 Normally, the variable's value is @code{nil}, which means those
173 functions should use @code{read}.
175 Instead of using this variable, it is cleaner to use another, newer
176 feature: to pass the function as the @var{read-function} argument to
177 @code{eval-region}. @xref{Definition of eval-region,, Eval}.
180 For information about how @code{load} is used in building Emacs, see
181 @ref{Building Emacs}.
184 @section Load Suffixes
185 We now describe some technical details about the exact suffixes that
188 @defvar load-suffixes
189 This is a list of suffixes indicating (compiled or source) Emacs Lisp
190 files. It should not include the empty string. @code{load} uses
191 these suffixes in order when it appends Lisp suffixes to the specified
192 file name. The standard value is @code{(".elc" ".el")} which produces
193 the behavior described in the previous section.
196 @defvar load-file-rep-suffixes
197 This is a list of suffixes that indicate representations of the same
198 file. This list should normally start with the empty string.
199 When @code{load} searches for a file it appends the suffixes in this
200 list, in order, to the file name, before searching for another file.
202 Enabling Auto Compression mode appends the suffixes in
203 @code{jka-compr-load-suffixes} to this list and disabling Auto
204 Compression mode removes them again. The standard value of
205 @code{load-file-rep-suffixes} if Auto Compression mode is disabled is
206 @code{("")}. Given that the standard value of
207 @code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value
208 of @code{load-file-rep-suffixes} if Auto Compression mode is enabled
209 is @code{("" ".gz")}.
212 @defun get-load-suffixes
213 This function returns the list of all suffixes that @code{load} should
214 try, in order, when its @var{must-suffix} argument is non-@code{nil}.
215 This takes both @code{load-suffixes} and @code{load-file-rep-suffixes}
216 into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes}
217 and @code{load-file-rep-suffixes} all have their standard values, this
218 function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto
219 Compression mode is enabled and @code{(".elc" ".el")} if Auto
220 Compression mode is disabled.
223 To summarize, @code{load} normally first tries the suffixes in the
224 value of @code{(get-load-suffixes)} and then those in
225 @code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil},
226 it skips the former group, and if @var{must-suffix} is non-@code{nil},
227 it skips the latter group.
230 @section Library Search
231 @cindex library search
234 When Emacs loads a Lisp library, it searches for the library
235 in a list of directories specified by the variable @code{load-path}.
238 @cindex @code{EMACSLOADPATH} environment variable
239 The value of this variable is a list of directories to search when
240 loading files with @code{load}. Each element is a string (which must be
241 a directory name) or @code{nil} (which stands for the current working
245 Each time Emacs starts up, it sets up the value of @code{load-path}
246 in several steps. First, it initializes @code{load-path} to the
247 directories specified by the environment variable @env{EMACSLOADPATH},
248 if that exists. The syntax of @env{EMACSLOADPATH} is the same as used
249 for @code{PATH}; directory names are separated by @samp{:} (or
250 @samp{;}, on some operating systems), and @samp{.} stands for the
251 current default directory. Here is an example of how to set
252 @env{EMACSLOADPATH} variable from @command{sh}:
256 EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
260 Here is how to set it from @code{csh}:
263 setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
266 If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs
267 initializes @code{load-path} with the following two directories:
270 "/usr/local/share/emacs/@var{version}/site-lisp"
277 "/usr/local/share/emacs/site-lisp"
281 The first one is for locally installed packages for a particular Emacs
282 version; the second is for locally installed packages meant for use
283 with all installed Emacs versions.
285 If you run Emacs from the directory where it was built---that is, an
286 executable that has not been formally installed---Emacs puts two more
287 directories in @code{load-path}. These are the @code{lisp} and
288 @code{site-lisp} subdirectories of the main build directory. (Both
289 are represented as absolute file names.)
291 Next, Emacs ``expands'' the initial list of directories in
292 @code{load-path} by adding the subdirectories of those directories.
293 Both immediate subdirectories and subdirectories multiple levels down
294 are added. But it excludes subdirectories whose names do not start
295 with a letter or digit, and subdirectories named @file{RCS} or
296 @file{CVS}, and subdirectories containing a file named
299 Next, Emacs adds any extra load directory that you specify using the
300 @samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The
301 GNU Emacs Manual}). It also adds the directories where optional
302 packages are installed, if any (@pxref{Packaging Basics}).
304 It is common to add code to one's init file (@pxref{Init File}) to
305 add one or more directories to @code{load-path}. For example:
308 (push "~/.emacs.d/lisp" load-path)
311 Dumping Emacs uses a special value of @code{load-path}. If the
312 value of @code{load-path} at the end of dumping is unchanged (that is,
313 still the same special value), the dumped Emacs switches to the
314 ordinary @code{load-path} value when it starts up, as described above.
315 But if @code{load-path} has any other value at the end of dumping,
316 that value is used for execution of the dumped Emacs also.
318 @deffn Command locate-library library &optional nosuffix path interactive-call
319 This command finds the precise file name for library @var{library}. It
320 searches for the library in the same way @code{load} does, and the
321 argument @var{nosuffix} has the same meaning as in @code{load}: don't
322 add suffixes @samp{.elc} or @samp{.el} to the specified name
325 If the @var{path} is non-@code{nil}, that list of directories is used
326 instead of @code{load-path}.
328 When @code{locate-library} is called from a program, it returns the file
329 name as a string. When the user runs @code{locate-library}
330 interactively, the argument @var{interactive-call} is @code{t}, and this
331 tells @code{locate-library} to display the file name in the echo area.
334 @cindex shadowed Lisp files
335 @deffn Command list-load-path-shadows &optional stringp
336 This command shows a list of @dfn{shadowed} Emacs Lisp files. A
337 shadowed file is one that will not normally be loaded, despite being
338 in a directory on @code{load-path}, due to the existence of another
339 similarly-named file in a directory earlier on @code{load-path}.
341 For instance, suppose @code{load-path} is set to
344 ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
348 and that both these directories contain a file named @file{foo.el}.
349 Then @code{(require 'foo)} never loads the file in the second
350 directory. Such a situation might indicate a problem in the way Emacs
353 When called from Lisp, this function prints a message listing the
354 shadowed files, instead of displaying them in a buffer. If the
355 optional argument @code{stringp} is non-@code{nil}, it instead returns
356 the shadowed files as a string.
359 @node Loading Non-ASCII
360 @section Loading Non-@acronym{ASCII} Characters
362 When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
363 characters, these can be represented within Emacs either as unibyte
364 strings or as multibyte strings (@pxref{Text Representations}). Which
365 representation is used depends on how the file is read into Emacs. If
366 it is read with decoding into multibyte representation, the text of the
367 Lisp program will be multibyte text, and its string constants will be
368 multibyte strings. If a file containing Latin-1 characters (for
369 example) is read without decoding, the text of the program will be
370 unibyte text, and its string constants will be unibyte strings.
371 @xref{Coding Systems}.
373 In most Emacs Lisp programs, the fact that non-@acronym{ASCII}
374 strings are multibyte strings should not be noticeable, since
375 inserting them in unibyte buffers converts them to unibyte
376 automatically. However, if this does make a difference, you can force
377 a particular Lisp file to be interpreted as unibyte by writing
378 @samp{-*-unibyte: t;-*-} in a comment on the file's first line. With
379 that designator, the file will unconditionally be interpreted as
380 unibyte, even in an ordinary multibyte Emacs session. This can matter
381 when making keybindings to non-@acronym{ASCII} characters written as
382 @code{?v@var{literal}}.
388 The @dfn{autoload} facility allows you to register the existence of
389 a function or macro, but put off loading the file that defines it.
390 The first call to the function automatically reads the proper file, in
391 order to install the real definition and other associated code, then
392 runs the real definition as if it had been loaded all along.
394 There are two ways to set up an autoloaded function: by calling
395 @code{autoload}, and by writing a special ``magic'' comment in the
396 source before the real definition. @code{autoload} is the low-level
397 primitive for autoloading; any Lisp program can call @code{autoload} at
398 any time. Magic comments are the most convenient way to make a function
399 autoload, for packages installed along with Emacs. These comments do
400 nothing on their own, but they serve as a guide for the command
401 @code{update-file-autoloads}, which constructs calls to @code{autoload}
402 and arranges to execute them when Emacs is built.
404 @defun autoload function filename &optional docstring interactive type
405 This function defines the function (or macro) named @var{function} so as
406 to load automatically from @var{filename}. The string @var{filename}
407 specifies the file to load to get the real definition of @var{function}.
409 If @var{filename} does not contain either a directory name, or the
410 suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
411 one of these suffixes, and it will not load from a file whose name is
412 just @var{filename} with no added suffix. (The variable
413 @code{load-suffixes} specifies the exact required suffixes.)
415 The argument @var{docstring} is the documentation string for the
416 function. Specifying the documentation string in the call to
417 @code{autoload} makes it possible to look at the documentation without
418 loading the function's real definition. Normally, this should be
419 identical to the documentation string in the function definition
420 itself. If it isn't, the function definition's documentation string
421 takes effect when it is loaded.
423 If @var{interactive} is non-@code{nil}, that says @var{function} can be
424 called interactively. This lets completion in @kbd{M-x} work without
425 loading @var{function}'s real definition. The complete interactive
426 specification is not given here; it's not needed unless the user
427 actually calls @var{function}, and when that happens, it's time to load
430 You can autoload macros and keymaps as well as ordinary functions.
431 Specify @var{type} as @code{macro} if @var{function} is really a macro.
432 Specify @var{type} as @code{keymap} if @var{function} is really a
433 keymap. Various parts of Emacs need to know this information without
434 loading the real definition.
436 An autoloaded keymap loads automatically during key lookup when a prefix
437 key's binding is the symbol @var{function}. Autoloading does not occur
438 for other kinds of access to the keymap. In particular, it does not
439 happen when a Lisp program gets the keymap from the value of a variable
440 and calls @code{define-key}; not even if the variable name is the same
441 symbol @var{function}.
443 @cindex function cell in autoload
444 If @var{function} already has a non-void function definition that is not
445 an autoload object, @code{autoload} does nothing and returns @code{nil}.
446 If the function cell of @var{function} is void, or is already an autoload
447 object, then it is defined as an autoload object like this:
450 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
457 (symbol-function 'run-prolog)
458 @result{} (autoload "prolog" 169681 t nil)
463 In this case, @code{"prolog"} is the name of the file to load, 169681
464 refers to the documentation string in the
465 @file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
466 @code{t} means the function is interactive, and @code{nil} that it is
467 not a macro or a keymap.
470 @cindex autoload errors
471 The autoloaded file usually contains other definitions and may require
472 or provide one or more features. If the file is not completely loaded
473 (due to an error in the evaluation of its contents), any function
474 definitions or @code{provide} calls that occurred during the load are
475 undone. This is to ensure that the next attempt to call any function
476 autoloading from this file will try again to load the file. If not for
477 this, then some of the functions in the file might be defined by the
478 aborted load, but fail to work properly for the lack of certain
479 subroutines not loaded successfully because they come later in the file.
481 If the autoloaded file fails to define the desired Lisp function or
482 macro, then an error is signaled with data @code{"Autoloading failed to
483 define function @var{function-name}"}.
485 @findex update-file-autoloads
486 @findex update-directory-autoloads
487 @cindex magic autoload comment
488 @cindex autoload cookie
489 @anchor{autoload cookie}
490 A magic autoload comment (often called an @dfn{autoload cookie})
491 consists of @samp{;;;###autoload}, on a line by itself,
492 just before the real definition of the function in its
493 autoloadable source file. The command @kbd{M-x update-file-autoloads}
494 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
495 (The string that serves as the autoload cookie and the name of the
496 file generated by @code{update-file-autoloads} can be changed from the
497 above defaults, see below.)
498 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
499 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
500 autoloads for all files in the current directory.
502 The same magic comment can copy any kind of form into
503 @file{loaddefs.el}. If the form following the magic comment is not a
504 function-defining form or a @code{defcustom} form, it is copied
505 verbatim. ``Function-defining forms'' include @code{define-skeleton},
506 @code{define-derived-mode}, @code{define-generic-mode} and
507 @code{define-minor-mode} as well as @code{defun} and
508 @code{defmacro}. To save space, a @code{defcustom} form is converted to
509 a @code{defvar} in @file{loaddefs.el}, with some additional information
510 if it uses @code{:require}.
512 You can also use a magic comment to execute a form at build time
513 @emph{without} executing it when the file itself is loaded. To do this,
514 write the form @emph{on the same line} as the magic comment. Since it
515 is in a comment, it does nothing when you load the source file; but
516 @kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
517 it is executed while building Emacs.
519 The following example shows how @code{doctor} is prepared for
520 autoloading with a magic comment:
525 "Switch to *doctor* buffer and start giving psychotherapy."
527 (switch-to-buffer "*doctor*")
532 Here's what that produces in @file{loaddefs.el}:
535 (autoload (quote doctor) "doctor" "\
536 Switch to *doctor* buffer and start giving psychotherapy.
542 @cindex @code{fn} in function's documentation string
543 The backslash and newline immediately following the double-quote are a
544 convention used only in the preloaded uncompiled Lisp files such as
545 @file{loaddefs.el}; they tell @code{make-docfile} to put the
546 documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
547 See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)}
548 in the usage part of the documentation string is replaced with the
549 function's name when the various help functions (@pxref{Help
550 Functions}) display it.
552 If you write a function definition with an unusual macro that is not
553 one of the known and recognized function definition methods, use of an
554 ordinary magic autoload comment would copy the whole definition into
555 @code{loaddefs.el}. That is not desirable. You can put the desired
556 @code{autoload} call into @code{loaddefs.el} instead by writing this:
559 ;;;###autoload (autoload 'foo "myfile")
564 You can use a non-default string as the autoload cookie and have the
565 corresponding autoload calls written into a file whose name is
566 different from the default @file{loaddefs.el}. Emacs provides two
567 variables to control this:
569 @defvar generate-autoload-cookie
570 The value of this variable should be a string whose syntax is a Lisp
571 comment. @kbd{M-x update-file-autoloads} copies the Lisp form that
572 follows the cookie into the autoload file it generates. The default
573 value of this variable is @code{";;;###autoload"}.
576 @defvar generated-autoload-file
577 The value of this variable names an Emacs Lisp file where the autoload
578 calls should go. The default value is @file{loaddefs.el}, but you can
579 override that, e.g., in the ``Local Variables'' section of a
580 @file{.el} file (@pxref{File Local Variables}). The autoload file is
581 assumed to contain a trailer starting with a formfeed character.
584 @node Repeated Loading
585 @section Repeated Loading
586 @cindex repeated loading
588 You can load a given file more than once in an Emacs session. For
589 example, after you have rewritten and reinstalled a function definition
590 by editing it in a buffer, you may wish to return to the original
591 version; you can do this by reloading the file it came from.
593 When you load or reload files, bear in mind that the @code{load} and
594 @code{load-library} functions automatically load a byte-compiled file
595 rather than a non-compiled file of similar name. If you rewrite a file
596 that you intend to save and reinstall, you need to byte-compile the new
597 version; otherwise Emacs will load the older, byte-compiled file instead
598 of your newer, non-compiled file! If that happens, the message
599 displayed when loading the file includes, @samp{(compiled; note, source is
600 newer)}, to remind you to recompile it.
602 When writing the forms in a Lisp library file, keep in mind that the
603 file might be loaded more than once. For example, think about whether
604 each variable should be reinitialized when you reload the library;
605 @code{defvar} does not change the value if the variable is already
606 initialized. (@xref{Defining Variables}.)
608 The simplest way to add an element to an alist is like this:
611 (push '(leif-mode " Leif") minor-mode-alist)
615 But this would add multiple elements if the library is reloaded. To
616 avoid the problem, use @code{add-to-list} (@pxref{List Variables}):
619 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
622 Occasionally you will want to test explicitly whether a library has
623 already been loaded. If the library uses @code{provide} to provide a
624 named feature, you can use @code{featurep} earlier in the file to test
625 whether the @code{provide} call has been executed before (@pxref{Named
626 Features}). Alternatively, you could use something like this:
629 (defvar foo-was-loaded nil)
631 (unless foo-was-loaded
632 @var{execute-first-time-only}
633 (setq foo-was-loaded t))
641 @cindex requiring features
642 @cindex providing features
644 @code{provide} and @code{require} are an alternative to
645 @code{autoload} for loading files automatically. They work in terms of
646 named @dfn{features}. Autoloading is triggered by calling a specific
647 function, but a feature is loaded the first time another program asks
650 A feature name is a symbol that stands for a collection of functions,
651 variables, etc. The file that defines them should @dfn{provide} the
652 feature. Another program that uses them may ensure they are defined by
653 @dfn{requiring} the feature. This loads the file of definitions if it
654 hasn't been loaded already.
656 @cindex load error with require
657 To require the presence of a feature, call @code{require} with the
658 feature name as argument. @code{require} looks in the global variable
659 @code{features} to see whether the desired feature has been provided
660 already. If not, it loads the feature from the appropriate file. This
661 file should call @code{provide} at the top level to add the feature to
662 @code{features}; if it fails to do so, @code{require} signals an error.
664 For example, in @file{idlwave.el}, the definition for
665 @code{idlwave-complete-filename} includes the following code:
668 (defun idlwave-complete-filename ()
669 "Use the comint stuff to complete a file name."
671 (let* ((comint-file-name-chars "~/A-Za-z0-9+@:_.$#%=@{@}\\-")
672 (comint-completion-addsuffix nil)
674 (comint-dynamic-complete-filename)))
678 The expression @code{(require 'comint)} loads the file @file{comint.el}
679 if it has not yet been loaded, ensuring that
680 @code{comint-dynamic-complete-filename} is defined. Features are
681 normally named after the files that provide them, so that
682 @code{require} need not be given the file name. (Note that it is
683 important that the @code{require} statement be outside the body of the
684 @code{let}. Loading a library while its variables are let-bound can
685 have unintended consequences, namely the variables becoming unbound
686 after the let exits.)
688 The @file{comint.el} file contains the following top-level expression:
695 This adds @code{comint} to the global @code{features} list, so that
696 @code{(require 'comint)} will henceforth know that nothing needs to be
699 @cindex byte-compiling @code{require}
700 When @code{require} is used at top level in a file, it takes effect
701 when you byte-compile that file (@pxref{Byte Compilation}) as well as
702 when you load it. This is in case the required package contains macros
703 that the byte compiler must know about. It also avoids byte compiler
704 warnings for functions and variables defined in the file loaded with
707 Although top-level calls to @code{require} are evaluated during
708 byte compilation, @code{provide} calls are not. Therefore, you can
709 ensure that a file of definitions is loaded before it is byte-compiled
710 by including a @code{provide} followed by a @code{require} for the same
711 feature, as in the following example.
715 (provide 'my-feature) ; @r{Ignored by byte compiler,}
716 ; @r{evaluated by @code{load}.}
717 (require 'my-feature) ; @r{Evaluated by byte compiler.}
722 The compiler ignores the @code{provide}, then processes the
723 @code{require} by loading the file in question. Loading the file does
724 execute the @code{provide} call, so the subsequent @code{require} call
725 does nothing when the file is loaded.
727 @defun provide feature &optional subfeatures
728 This function announces that @var{feature} is now loaded, or being
729 loaded, into the current Emacs session. This means that the facilities
730 associated with @var{feature} are or will be available for other Lisp
733 The direct effect of calling @code{provide} is if not already in
734 @var{features} then to add @var{feature} to the front of that list and
735 call any @code{eval-after-load} code waiting for it (@pxref{Hooks for
736 Loading}). The argument @var{feature} must be a symbol.
737 @code{provide} returns @var{feature}.
739 If provided, @var{subfeatures} should be a list of symbols indicating
740 a set of specific subfeatures provided by this version of
741 @var{feature}. You can test the presence of a subfeature using
742 @code{featurep}. The idea of subfeatures is that you use them when a
743 package (which is one @var{feature}) is complex enough to make it
744 useful to give names to various parts or functionalities of the
745 package, which might or might not be loaded, or might or might not be
746 present in a given version. @xref{Network Feature Testing}, for
756 @result{} (foo bar bish)
759 When a file is loaded to satisfy an autoload, and it stops due to an
760 error in the evaluation of its contents, any function definitions or
761 @code{provide} calls that occurred during the load are undone.
765 @defun require feature &optional filename noerror
766 This function checks whether @var{feature} is present in the current
767 Emacs session (using @code{(featurep @var{feature})}; see below). The
768 argument @var{feature} must be a symbol.
770 If the feature is not present, then @code{require} loads @var{filename}
771 with @code{load}. If @var{filename} is not supplied, then the name of
772 the symbol @var{feature} is used as the base file name to load.
773 However, in this case, @code{require} insists on finding @var{feature}
774 with an added @samp{.el} or @samp{.elc} suffix (possibly extended with
775 a compression suffix); a file whose name is just @var{feature} won't
776 be used. (The variable @code{load-suffixes} specifies the exact
777 required Lisp suffixes.)
779 If @var{noerror} is non-@code{nil}, that suppresses errors from actual
780 loading of the file. In that case, @code{require} returns @code{nil}
781 if loading the file fails. Normally, @code{require} returns
784 If loading the file succeeds but does not provide @var{feature},
785 @code{require} signals an error, @samp{Required feature @var{feature}
789 @defun featurep feature &optional subfeature
790 This function returns @code{t} if @var{feature} has been provided in
791 the current Emacs session (i.e.@:, if @var{feature} is a member of
792 @code{features}.) If @var{subfeature} is non-@code{nil}, then the
793 function returns @code{t} only if that subfeature is provided as well
794 (i.e.@: if @var{subfeature} is a member of the @code{subfeature}
795 property of the @var{feature} symbol.)
799 The value of this variable is a list of symbols that are the features
800 loaded in the current Emacs session. Each symbol was put in this list
801 with a call to @code{provide}. The order of the elements in the
802 @code{features} list is not significant.
806 @section Which File Defined a Certain Symbol
808 @defun symbol-file symbol &optional type
809 This function returns the name of the file that defined @var{symbol}.
810 If @var{type} is @code{nil}, then any kind of definition is acceptable.
811 If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that
812 specifies function definition, variable definition, or face definition
815 The value is normally an absolute file name. It can also be @code{nil},
816 if the definition is not associated with any file. If @var{symbol}
817 specifies an autoloaded function, the value can be a relative file name
821 The basis for @code{symbol-file} is the data in the variable
825 The value of this variable is an alist that associates the names of
826 loaded library files with the names of the functions and variables
827 they defined, as well as the features they provided or required.
829 Each element in this alist describes one loaded library (including
830 libraries that are preloaded at startup). It is a list whose @sc{car}
831 is the absolute file name of the library (a string). The rest of the
832 list elements have these forms:
836 The symbol @var{var} was defined as a variable.
837 @item (defun . @var{fun})
838 The function @var{fun} was defined.
839 @item (t . @var{fun})
840 The function @var{fun} was previously an autoload before this library
841 redefined it as a function. The following element is always
842 @code{(defun . @var{fun})}, which represents defining @var{fun} as a
844 @item (autoload . @var{fun})
845 The function @var{fun} was defined as an autoload.
846 @item (defface . @var{face})
847 The face @var{face} was defined.
848 @item (require . @var{feature})
849 The feature @var{feature} was required.
850 @item (provide . @var{feature})
851 The feature @var{feature} was provided.
854 The value of @code{load-history} may have one element whose @sc{car} is
855 @code{nil}. This element describes definitions made with
856 @code{eval-buffer} on a buffer that is not visiting a file.
859 The command @code{eval-region} updates @code{load-history}, but does so
860 by adding the symbols defined to the element for the file being visited,
861 rather than replacing that element. @xref{Eval}.
865 @cindex unloading packages
868 You can discard the functions and variables loaded by a library to
869 reclaim memory for other Lisp objects. To do this, use the function
870 @code{unload-feature}:
872 @deffn Command unload-feature feature &optional force
873 This command unloads the library that provided feature @var{feature}.
874 It undefines all functions, macros, and variables defined in that
875 library with @code{defun}, @code{defalias}, @code{defsubst},
876 @code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
877 It then restores any autoloads formerly associated with those symbols.
878 (Loading saves these in the @code{autoload} property of the symbol.)
880 Before restoring the previous definitions, @code{unload-feature} runs
881 @code{remove-hook} to remove functions in the library from certain
882 hooks. These hooks include variables whose names end in @samp{hook}
883 or @samp{-hooks}, plus those listed in
884 @code{unload-feature-special-hooks}, as well as
885 @code{auto-mode-alist}. This is to prevent Emacs from ceasing to
886 function because important hooks refer to functions that are no longer
889 Standard unloading activities also undoes ELP profiling of functions
890 in that library, unprovides any features provided by the library, and
891 cancels timers held in variables defined by the library.
893 @vindex @var{feature}-unload-function
894 If these measures are not sufficient to prevent malfunction, a library
895 can define an explicit unloader named @code{@var{feature}-unload-function}.
896 If that symbol is defined as a function, @code{unload-feature} calls
897 it with no arguments before doing anything else. It can do whatever
898 is appropriate to unload the library. If it returns @code{nil},
899 @code{unload-feature} proceeds to take the normal unload actions.
900 Otherwise it considers the job to be done.
902 Ordinarily, @code{unload-feature} refuses to unload a library on which
903 other loaded libraries depend. (A library @var{a} depends on library
904 @var{b} if @var{a} contains a @code{require} for @var{b}.) If the
905 optional argument @var{force} is non-@code{nil}, dependencies are
906 ignored and you can unload any library.
909 The @code{unload-feature} function is written in Lisp; its actions are
910 based on the variable @code{load-history}.
912 @defvar unload-feature-special-hooks
913 This variable holds a list of hooks to be scanned before unloading a
914 library, to remove functions defined in the library.
917 @node Hooks for Loading
918 @section Hooks for Loading
919 @cindex loading hooks
920 @cindex hooks for loading
922 You can ask for code to be executed each time Emacs loads a library,
923 by using the variable @code{after-load-functions}:
925 @defvar after-load-functions
926 This abnormal hook is run after loading a file. Each function in the
927 hook is called with a single argument, the absolute filename of the
928 file that was just loaded.
931 If you want code to be executed when a @emph{particular} library is
932 loaded, use the function @code{eval-after-load}:
934 @defun eval-after-load library form
935 This function arranges to evaluate @var{form} at the end of loading
936 the file @var{library}, each time @var{library} is loaded. If
937 @var{library} is already loaded, it evaluates @var{form} right away.
938 Don't forget to quote @var{form}!
940 You don't need to give a directory or extension in the file name
941 @var{library}. Normally, you just give a bare file name, like this:
944 (eval-after-load "edebug" '(def-edebug-spec c-point t))
947 To restrict which files can trigger the evaluation, include a
948 directory or an extension or both in @var{library}. Only a file whose
949 absolute true name (i.e., the name with all symbolic links chased out)
950 matches all the given name components will match. In the following
951 example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory
952 @code{..../foo/bar} will trigger the evaluation, but not
956 (eval-after-load "foo/bar/my_inst.elc" @dots{})
959 @var{library} can also be a feature (i.e.@: a symbol), in which case
960 @var{form} is evaluated at the end of any file where
961 @code{(provide @var{library})} is called.
963 An error in @var{form} does not undo the load, but does prevent
964 execution of the rest of @var{form}.
967 Normally, well-designed Lisp programs should not use
968 @code{eval-after-load}. If you need to examine and set the variables
969 defined in another library (those meant for outside use), you can do
970 it immediately---there is no need to wait until the library is loaded.
971 If you need to call functions defined by that library, you should load
972 the library, preferably with @code{require} (@pxref{Named Features}).
974 @defvar after-load-alist
975 This variable stores an alist built by @code{eval-after-load},
976 containing the expressions to evaluate when certain libraries are
977 loaded. Each element looks like this:
980 (@var{regexp-or-feature} @var{forms}@dots{})
983 The key @var{regexp-or-feature} is either a regular expression or a
984 symbol, and the value is a list of forms. The forms are evaluated
985 when the key matches the absolute true name or feature name of the
986 library being loaded.