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