2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/loading
6 @node Loading, Byte Compilation, Customization, Top
12 Loading a file of Lisp code means bringing its contents into the Lisp
13 environment in the form of Lisp objects. Emacs finds and opens the
14 file, reads the text, evaluates each form, and then closes the file.
16 The load functions evaluate all the expressions in a file just
17 as the @code{eval-current-buffer} function evaluates all the
18 expressions in a buffer. The difference is that the load functions
19 read and evaluate the text in the file as found on disk, not the text
22 @cindex top-level form
23 The loaded file must contain Lisp expressions, either as source code
24 or as byte-compiled code. Each form in the file is called a
25 @dfn{top-level form}. There is no special format for the forms in a
26 loadable file; any form in a file may equally well be typed directly
27 into a buffer and evaluated there. (Indeed, most code is tested this
28 way.) Most often, the forms are function definitions and variable
31 A file containing Lisp code is often called a @dfn{library}. Thus,
32 the ``Rmail library'' is a file containing code for Rmail mode.
33 Similarly, a ``Lisp library directory'' is a directory of files
37 * How Programs Do Loading:: The @code{load} function and others.
38 * Library Search:: Finding a library to load.
39 * Loading Non-ASCII:: Non-@sc{ASCII} characters in Emacs Lisp files.
40 * Autoload:: Setting up a function to autoload.
41 * Repeated Loading:: Precautions about loading a file twice.
42 * Named Features:: Loading a library if it isn't already loaded.
43 * Unloading:: How to ``unload'' a library that was loaded.
44 * Hooks for Loading:: Providing code to be run when
45 particular libraries are loaded.
48 @node How Programs Do Loading
49 @section How Programs Do Loading
51 Emacs Lisp has several interfaces for loading. For example,
52 @code{autoload} creates a placeholder object for a function defined in a
53 file; trying to call the autoloading function loads the file to get the
54 function's real definition (@pxref{Autoload}). @code{require} loads a
55 file if it isn't already loaded (@pxref{Named Features}). Ultimately,
56 all these facilities call the @code{load} function to do the work.
58 @defun load filename &optional missing-ok nomessage nosuffix must-suffix
59 This function finds and opens a file of Lisp code, evaluates all the
60 forms in it, and closes the file.
62 To find the file, @code{load} first looks for a file named
63 @file{@var{filename}.elc}, that is, for a file whose name is
64 @var{filename} with @samp{.elc} appended. If such a file exists, it is
65 loaded. If there is no file by that name, then @code{load} looks for a
66 file named @file{@var{filename}.el}. If that file exists, it is loaded.
67 Finally, if neither of those names is found, @code{load} looks for a
68 file named @var{filename} with nothing appended, and loads it if it
69 exists. (The @code{load} function is not clever about looking at
70 @var{filename}. In the perverse case of a file named @file{foo.el.el},
71 evaluation of @code{(load "foo.el")} will indeed find it.)
73 If the optional argument @var{nosuffix} is non-@code{nil}, then the
74 suffixes @samp{.elc} and @samp{.el} are not tried. In this case, you
75 must specify the precise file name you want. By specifying the precise
76 file name and using @code{t} for @var{nosuffix}, you can prevent
77 perverse file names such as @file{foo.el.el} from being tried.
79 If the optional argument @var{must-suffix} is non-@code{nil}, then
80 @code{load} insists that the file name used must end in either
81 @samp{.el} or @samp{.elc}, unless it contains an explicit directory
82 name. If @var{filename} does not contain an explicit directory name,
83 and does not end in a suffix, then @code{load} insists on adding one.
85 If @var{filename} is a relative file name, such as @file{foo} or
86 @file{baz/foo.bar}, @code{load} searches for the file using the variable
87 @code{load-path}. It appends @var{filename} to each of the directories
88 listed in @code{load-path}, and loads the first file it finds whose name
89 matches. The current default directory is tried only if it is specified
90 in @code{load-path}, where @code{nil} stands for the default directory.
91 @code{load} tries all three possible suffixes in the first directory in
92 @code{load-path}, then all three suffixes in the second directory, and
93 so on. @xref{Library Search}.
95 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
96 means you should consider recompiling @file{foo.el}. @xref{Byte
99 When loading a source file (not compiled), @code{load} performs
100 character set translation just as Emacs would do when visiting the file.
101 @xref{Coding Systems}.
103 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
104 in the echo area during loading unless @var{nomessage} is
108 Any unhandled errors while loading a file terminate loading. If the
109 load was done for the sake of @code{autoload}, any function definitions
110 made during the loading are undone.
113 If @code{load} can't find the file to load, then normally it signals the
114 error @code{file-error} (with @samp{Cannot open load file
115 @var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
116 @code{load} just returns @code{nil}.
118 You can use the variable @code{load-read-function} to specify a function
119 for @code{load} to use instead of @code{read} for reading expressions.
122 @code{load} returns @code{t} if the file loads successfully.
125 @deffn Command load-file filename
126 This command loads the file @var{filename}. If @var{filename} is a
127 relative file name, then the current default directory is assumed.
128 @code{load-path} is not used, and suffixes are not appended. Use this
129 command if you wish to specify precisely the file name to load.
132 @deffn Command load-library library
133 This command loads the library named @var{library}. It is equivalent to
134 @code{load}, except in how it reads its argument interactively.
137 @defvar load-in-progress
138 This variable is non-@code{nil} if Emacs is in the process of loading a
139 file, and it is @code{nil} otherwise.
142 @defvar load-read-function
143 This variable specifies an alternate expression-reading function for
144 @code{load} and @code{eval-region} to use instead of @code{read}.
145 The function should accept one argument, just as @code{read} does.
147 Normally, the variable's value is @code{nil}, which means those
148 functions should use @code{read}.
150 @strong{Note:} Instead of using this variable, it is cleaner to use
151 another, newer feature: to pass the function as the @var{read-function}
152 argument to @code{eval-region}. @xref{Eval}.
155 For information about how @code{load} is used in building Emacs, see
156 @ref{Building Emacs}.
159 @section Library Search
161 When Emacs loads a Lisp library, it searches for the library
162 in a list of directories specified by the variable @code{load-path}.
165 @cindex @code{EMACSLOADPATH} environment variable
166 The value of this variable is a list of directories to search when
167 loading files with @code{load}. Each element is a string (which must be
168 a directory name) or @code{nil} (which stands for the current working
172 The value of @code{load-path} is initialized from the environment
173 variable @code{EMACSLOADPATH}, if that exists; otherwise its default
174 value is specified in @file{emacs/src/paths.h} when Emacs is built.
175 Then the list is expanded by adding subdirectories of the directories
178 The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
179 @samp{:} (or @samp{;}, according to the operating system) separates
180 directory names, and @samp{.} is used for the current default directory.
181 Here is an example of how to set your @code{EMACSLOADPATH} variable from
182 a @code{csh} @file{.login} file:
185 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
188 Here is how to set it using @code{sh}:
192 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
195 Here is an example of code you can place in a @file{.emacs} file to add
196 several directories to the front of your default @code{load-path}:
201 (append (list nil "/user/bil/emacs"
208 @c Wordy to rid us of an overfull hbox. --rjc 15mar92
210 In this example, the path searches the current working directory first,
211 followed then by the @file{/user/bil/emacs} directory, the
212 @file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
213 which are then followed by the standard directories for Lisp code.
215 Dumping Emacs uses a special value of @code{load-path}. If the value of
216 @code{load-path} at the end of dumping is unchanged (that is, still the
217 same special value), the dumped Emacs switches to the ordinary
218 @code{load-path} value when it starts up, as described above. But if
219 @code{load-path} has any other value at the end of dumping, that value
220 is used for execution of the dumped Emacs also.
222 Therefore, if you want to change @code{load-path} temporarily for
223 loading a few libraries in @file{site-init.el} or @file{site-load.el},
224 you should bind @code{load-path} locally with @code{let} around the
225 calls to @code{load}.
227 The default value of @code{load-path}, when running an Emacs which has
228 been installed on the system, includes two special directories (and
229 their subdirectories as well):
232 "/usr/local/share/emacs/@var{version}/site-lisp"
239 "/usr/local/share/emacs/site-lisp"
243 The first one is for locally installed packages for a particular Emacs
244 version; the second is for locally installed packages meant for use with
245 all installed Emacs versions.
247 There are several reasons why a Lisp package that works well in one
248 Emacs version can cause trouble in another. Sometimes packages need
249 updating for incompatible changes in Emacs; sometimes they depend on
250 undocumented internal Emacs data that can change without notice;
251 sometimes a newer Emacs version incorporates a version of the package,
252 and should be used only with that version.
254 Emacs finds these directories' subdirectories and adds them to
255 @code{load-path} when it starts up. Both immediate subdirectories and
256 subdirectories multiple levels down are added to @code{load-path}.
258 Not all subdirectories are included, though. Subdirectories whose
259 names do not start with a letter or digit are excluded. Subdirectories
260 named @file{RCS} are excluded. Also, a subdirectory which contains a
261 file named @file{.nosearch} is excluded. You can use these methods to
262 prevent certain subdirectories of the @file{site-lisp} directories from
265 If you run Emacs from the directory where it was built---that is, an
266 executable that has not been formally installed---then @code{load-path}
267 normally contains two additional directories. These are the @code{lisp}
268 and @code{site-lisp} subdirectories of the main build directory. (Both
269 are represented as absolute file names.)
271 @deffn Command locate-library library &optional nosuffix path interactive-call
272 This command finds the precise file name for library @var{library}. It
273 searches for the library in the same way @code{load} does, and the
274 argument @var{nosuffix} has the same meaning as in @code{load}: don't
275 add suffixes @samp{.elc} or @samp{.el} to the specified name
278 If the @var{path} is non-@code{nil}, that list of directories is used
279 instead of @code{load-path}.
281 When @code{locate-library} is called from a program, it returns the file
282 name as a string. When the user runs @code{locate-library}
283 interactively, the argument @var{interactive-call} is @code{t}, and this
284 tells @code{locate-library} to display the file name in the echo area.
287 @node Loading Non-ASCII
288 @section Loading Non-ASCII Characters
290 When Emacs Lisp programs contain string constants with non-@sc{ASCII}
291 characters, these can be represented within Emacs either as unibyte
292 strings or as multibyte strings (@pxref{Text Representations}). Which
293 representation is used depends on how the file is read into Emacs. If
294 it is read with decoding into multibyte representation, the text of the
295 Lisp program will be multibyte text, and its string constants will be
296 multibyte strings. If a file containing Latin-1 characters (for
297 example) is read without decoding, the text of the program will be
298 unibyte text, and its string constants will be unibyte strings.
299 @xref{Coding Systems}.
301 To make the results more predictable, Emacs always performs decoding
302 into the multibyte representation when loading Lisp files, even if it
303 was started with the @samp{--unibyte} option. This means that string
304 constants with non-@sc{ASCII} characters translate into multibyte
305 strings. The only exception is when a particular file specifies no
308 The reason Emacs is designed this way is so that Lisp programs give
309 predictable results, regardless of how Emacs was started. In addition,
310 this enables programs that depend on using multibyte text to work even
311 in a unibyte Emacs. Of course, such programs should be designed to
312 notice whether the user prefers unibyte or multibyte text, by checking
313 @code{default-enable-multibyte-characters}, and convert representations
316 In most Emacs Lisp programs, the fact that non-@sc{ASCII} strings are
317 multibyte strings should not be noticeable, since inserting them in
318 unibyte buffers converts them to unibyte automatically. However, if
319 this does make a difference, you can force a particular Lisp file to be
320 interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
321 comment on the file's first line. With that designator, the file will
322 be unconditionally be interpreted as unibyte, even in an ordinary
323 multibyte Emacs session.
329 The @dfn{autoload} facility allows you to make a function or macro
330 known in Lisp, but put off loading the file that defines it. The first
331 call to the function automatically reads the proper file to install the
332 real definition and other associated code, then runs the real definition
333 as if it had been loaded all along.
335 There are two ways to set up an autoloaded function: by calling
336 @code{autoload}, and by writing a special ``magic'' comment in the
337 source before the real definition. @code{autoload} is the low-level
338 primitive for autoloading; any Lisp program can call @code{autoload} at
339 any time. Magic comments are the most convenient way to make a function
340 autoload, for packages installed along with Emacs. These comments do
341 nothing on their own, but they serve as a guide for the command
342 @code{update-file-autoloads}, which constructs calls to @code{autoload}
343 and arranges to execute them when Emacs is built.
345 @defun autoload function filename &optional docstring interactive type
346 This function defines the function (or macro) named @var{function} so as
347 to load automatically from @var{filename}. The string @var{filename}
348 specifies the file to load to get the real definition of @var{function}.
350 If @var{filename} does not contain either a directory name, or the
351 suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
352 one of these suffixes, and it will not load from a file whose name is
353 just @var{filename} with no added suffix.
355 The argument @var{docstring} is the documentation string for the
356 function. Normally, this should be identical to the documentation string
357 in the function definition itself. Specifying the documentation string
358 in the call to @code{autoload} makes it possible to look at the
359 documentation without loading the function's real definition.
361 If @var{interactive} is non-@code{nil}, that says @var{function} can be
362 called interactively. This lets completion in @kbd{M-x} work without
363 loading @var{function}'s real definition. The complete interactive
364 specification is not given here; it's not needed unless the user
365 actually calls @var{function}, and when that happens, it's time to load
368 You can autoload macros and keymaps as well as ordinary functions.
369 Specify @var{type} as @code{macro} if @var{function} is really a macro.
370 Specify @var{type} as @code{keymap} if @var{function} is really a
371 keymap. Various parts of Emacs need to know this information without
372 loading the real definition.
374 An autoloaded keymap loads automatically during key lookup when a prefix
375 key's binding is the symbol @var{function}. Autoloading does not occur
376 for other kinds of access to the keymap. In particular, it does not
377 happen when a Lisp program gets the keymap from the value of a variable
378 and calls @code{define-key}; not even if the variable name is the same
379 symbol @var{function}.
381 @cindex function cell in autoload
382 If @var{function} already has a non-void function definition that is not
383 an autoload object, @code{autoload} does nothing and returns @code{nil}.
384 If the function cell of @var{function} is void, or is already an autoload
385 object, then it is defined as an autoload object like this:
388 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
395 (symbol-function 'run-prolog)
396 @result{} (autoload "prolog" 169681 t nil)
401 In this case, @code{"prolog"} is the name of the file to load, 169681
402 refers to the documentation string in the
403 @file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
404 @code{t} means the function is interactive, and @code{nil} that it is
405 not a macro or a keymap.
408 @cindex autoload errors
409 The autoloaded file usually contains other definitions and may require
410 or provide one or more features. If the file is not completely loaded
411 (due to an error in the evaluation of its contents), any function
412 definitions or @code{provide} calls that occurred during the load are
413 undone. This is to ensure that the next attempt to call any function
414 autoloading from this file will try again to load the file. If not for
415 this, then some of the functions in the file might be defined by the
416 aborted load, but fail to work properly for the lack of certain
417 subroutines not loaded successfully because they come later in the file.
419 If the autoloaded file fails to define the desired Lisp function or
420 macro, then an error is signaled with data @code{"Autoloading failed to
421 define function @var{function-name}"}.
423 @findex update-file-autoloads
424 @findex update-directory-autoloads
425 A magic autoload comment consists of @samp{;;;###autoload}, on a line
426 by itself, just before the real definition of the function in its
427 autoloadable source file. The command @kbd{M-x update-file-autoloads}
428 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
429 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
430 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
431 autoloads for all files in the current directory.
433 The same magic comment can copy any kind of form into
434 @file{loaddefs.el}. If the form following the magic comment is not a
435 function definition, it is copied verbatim. You can also use a magic
436 comment to execute a form at build time @emph{without} executing it when
437 the file itself is loaded. To do this, write the form @emph{on the same
438 line} as the magic comment. Since it is in a comment, it does nothing
439 when you load the source file; but @kbd{M-x update-file-autoloads}
440 copies it to @file{loaddefs.el}, where it is executed while building
443 The following example shows how @code{doctor} is prepared for
444 autoloading with a magic comment:
449 "Switch to *doctor* buffer and start giving psychotherapy."
451 (switch-to-buffer "*doctor*")
456 Here's what that produces in @file{loaddefs.el}:
459 (autoload 'doctor "doctor"
461 Switch to *doctor* buffer and start giving psychotherapy."
466 The backslash and newline immediately following the double-quote are a
467 convention used only in the preloaded Lisp files such as
468 @file{loaddefs.el}; they tell @code{make-docfile} to put the
469 documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
471 @node Repeated Loading
472 @section Repeated Loading
473 @cindex repeated loading
475 You can load a given file more than once in an Emacs session. For
476 example, after you have rewritten and reinstalled a function definition
477 by editing it in a buffer, you may wish to return to the original
478 version; you can do this by reloading the file it came from.
480 When you load or reload files, bear in mind that the @code{load} and
481 @code{load-library} functions automatically load a byte-compiled file
482 rather than a non-compiled file of similar name. If you rewrite a file
483 that you intend to save and reinstall, you need to byte-compile the new
484 version; otherwise Emacs will load the older, byte-compiled file instead
485 of your newer, non-compiled file! If that happens, the message
486 displayed when loading the file includes, @samp{(compiled; note, source is
487 newer)}, to remind you to recompile it.
489 When writing the forms in a Lisp library file, keep in mind that the
490 file might be loaded more than once. For example, think about whether
491 each variable should be reinitialized when you reload the library;
492 @code{defvar} does not change the value if the variable is already
493 initialized. (@xref{Defining Variables}.)
495 The simplest way to add an element to an alist is like this:
498 (setq minor-mode-alist
499 (cons '(leif-mode " Leif") minor-mode-alist))
503 But this would add multiple elements if the library is reloaded.
504 To avoid the problem, write this:
507 (or (assq 'leif-mode minor-mode-alist)
508 (setq minor-mode-alist
509 (cons '(leif-mode " Leif") minor-mode-alist)))
512 To add an element to a list just once, you can also use @code{add-to-list}
513 (@pxref{Setting Variables}).
515 Occasionally you will want to test explicitly whether a library has
516 already been loaded. Here's one way to test, in a library, whether it
517 has been loaded before:
520 (defvar foo-was-loaded nil)
522 (unless foo-was-loaded
523 @var{execute-first-time-only}
524 (setq foo-was-loaded t))
528 If the library uses @code{provide} to provide a named feature, you can
529 use @code{featurep} earlier in the file to test whether the
530 @code{provide} call has been executed before.
532 @xref{Named Features}.
538 @cindex requiring features
539 @cindex providing features
541 @code{provide} and @code{require} are an alternative to
542 @code{autoload} for loading files automatically. They work in terms of
543 named @dfn{features}. Autoloading is triggered by calling a specific
544 function, but a feature is loaded the first time another program asks
547 A feature name is a symbol that stands for a collection of functions,
548 variables, etc. The file that defines them should @dfn{provide} the
549 feature. Another program that uses them may ensure they are defined by
550 @dfn{requiring} the feature. This loads the file of definitions if it
551 hasn't been loaded already.
553 To require the presence of a feature, call @code{require} with the
554 feature name as argument. @code{require} looks in the global variable
555 @code{features} to see whether the desired feature has been provided
556 already. If not, it loads the feature from the appropriate file. This
557 file should call @code{provide} at the top level to add the feature to
558 @code{features}; if it fails to do so, @code{require} signals an error.
559 @cindex load error with require
561 For example, in @file{emacs/lisp/prolog.el},
562 the definition for @code{run-prolog} includes the following code:
566 "Run an inferior Prolog process, with I/O via buffer *prolog*."
569 (switch-to-buffer (make-comint "prolog" prolog-program-name))
570 (inferior-prolog-mode))
574 The expression @code{(require 'comint)} loads the file @file{comint.el}
575 if it has not yet been loaded. This ensures that @code{make-comint} is
576 defined. Features are normally named after the files that provide them,
577 so that @code{require} need not be given the file name.
579 The @file{comint.el} file contains the following top-level expression:
586 This adds @code{comint} to the global @code{features} list, so that
587 @code{(require 'comint)} will henceforth know that nothing needs to be
590 @cindex byte-compiling @code{require}
591 When @code{require} is used at top level in a file, it takes effect
592 when you byte-compile that file (@pxref{Byte Compilation}) as well as
593 when you load it. This is in case the required package contains macros
594 that the byte compiler must know about.
596 Although top-level calls to @code{require} are evaluated during
597 byte compilation, @code{provide} calls are not. Therefore, you can
598 ensure that a file of definitions is loaded before it is byte-compiled
599 by including a @code{provide} followed by a @code{require} for the same
600 feature, as in the following example.
604 (provide 'my-feature) ; @r{Ignored by byte compiler,}
605 ; @r{evaluated by @code{load}.}
606 (require 'my-feature) ; @r{Evaluated by byte compiler.}
611 The compiler ignores the @code{provide}, then processes the
612 @code{require} by loading the file in question. Loading the file does
613 execute the @code{provide} call, so the subsequent @code{require} call
614 does nothing when the file is loaded.
616 @defun provide feature
617 This function announces that @var{feature} is now loaded, or being
618 loaded, into the current Emacs session. This means that the facilities
619 associated with @var{feature} are or will be available for other Lisp
622 The direct effect of calling @code{provide} is to add @var{feature} to
623 the front of the list @code{features} if it is not already in the list.
624 The argument @var{feature} must be a symbol. @code{provide} returns
634 @result{} (foo bar bish)
637 When a file is loaded to satisfy an autoload, and it stops due to an
638 error in the evaluating its contents, any function definitions or
639 @code{provide} calls that occurred during the load are undone.
643 @defun require feature &optional filename
644 This function checks whether @var{feature} is present in the current
645 Emacs session (using @code{(featurep @var{feature})}; see below). The
646 argument @var{feature} must be a symbol.
648 If the feature is not present, then @code{require} loads @var{filename}
649 with @code{load}. If @var{filename} is not supplied, then the name of
650 the symbol @var{feature} is used as the base file name to load.
651 However, in this case, @code{require} insists on finding @var{feature}
652 with an added suffix; a file whose name is just @var{feature} won't be
655 If loading the file fails to provide @var{feature}, @code{require}
656 signals an error, @samp{Required feature @var{feature} was not
660 @defun featurep feature
661 This function returns @code{t} if @var{feature} has been provided in the
662 current Emacs session (i.e., if @var{feature} is a member of
667 The value of this variable is a list of symbols that are the features
668 loaded in the current Emacs session. Each symbol was put in this list
669 with a call to @code{provide}. The order of the elements in the
670 @code{features} list is not significant.
678 You can discard the functions and variables loaded by a library to
679 reclaim memory for other Lisp objects. To do this, use the function
680 @code{unload-feature}:
682 @deffn Command unload-feature feature &optional force
683 This command unloads the library that provided feature @var{feature}.
684 It undefines all functions, macros, and variables defined in that
685 library with @code{defun}, @code{defalias}, @code{defsubst},
686 @code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
687 It then restores any autoloads formerly associated with those symbols.
688 (Loading saves these in the @code{autoload} property of the symbol.)
690 Before restoring the previous definitions, @code{unload-feature} runs
691 @code{remove-hook} to remove functions in the library from certain
692 hooks. These hooks include variables whose names end in @samp{hook} or
693 @samp{-hooks}, plus those listed in @code{loadhist-special-hooks}. This
694 is to prevent Emacs from ceasing to function because important hooks
695 refer to functions that are no longer defined.
697 @vindex @var{feature}-unload-hook
698 If these measures are not sufficient to prevent malfunction, a library
699 can define an explicit unload hook. If @code{@var{feature}-unload-hook}
700 is defined, it is run as a normal hook before restoring the previous
701 definitions, @emph{instead of} the usual hook-removing actions. The
702 unload hook ought to undo all the global state changes made by the
703 library that might cease to work once the library is unloaded.
705 Ordinarily, @code{unload-feature} refuses to unload a library on which
706 other loaded libraries depend. (A library @var{a} depends on library
707 @var{b} if @var{a} contains a @code{require} for @var{b}.) If the
708 optional argument @var{force} is non-@code{nil}, dependencies are
709 ignored and you can unload any library.
712 The @code{unload-feature} function is written in Lisp; its actions are
713 based on the variable @code{load-history}.
716 This variable's value is an alist connecting library names with the
717 names of functions and variables they define, the features they provide,
718 and the features they require.
720 Each element is a list and describes one library. The @sc{car} of the
721 list is the name of the library, as a string. The rest of the list is
722 composed of these kinds of objects:
726 Symbols that were defined by this library.
728 Lists of the form @code{(require . @var{feature})} indicating
729 features that were required.
731 Lists of the form @code{(provide . @var{feature})} indicating
732 features that were provided.
735 The value of @code{load-history} may have one element whose @sc{car} is
736 @code{nil}. This element describes definitions made with
737 @code{eval-buffer} on a buffer that is not visiting a file.
740 The command @code{eval-region} updates @code{load-history}, but does so
741 by adding the symbols defined to the element for the file being visited,
742 rather than replacing that element. @xref{Eval}.
744 Preloaded libraries don't contribute to @code{load-history}.
746 @tindex loadhist-special-hooks
747 @defvar loadhist-special-hooks
748 This variable holds a list of hooks to be scanned before unloading a
749 library, to remove functions defined in the library.
752 @node Hooks for Loading
753 @section Hooks for Loading
754 @cindex loading hooks
755 @cindex hooks for loading
757 You can ask for code to be executed if and when a particular library is
758 loaded, by calling @code{eval-after-load}.
760 @defun eval-after-load library form
761 This function arranges to evaluate @var{form} at the end of loading the
762 library @var{library}, if and when @var{library} is loaded. If
763 @var{library} is already loaded, it evaluates @var{form} right away.
765 The library name @var{library} must exactly match the argument of
766 @code{load}. To get the proper results when an installed library is
767 found by searching @code{load-path}, you should not include any
768 directory names in @var{library}.
770 An error in @var{form} does not undo the load, but does prevent
771 execution of the rest of @var{form}.
774 In general, well-designed Lisp programs should not use this feature.
775 The clean and modular ways to interact with a Lisp library are (1)
776 examine and set the library's variables (those which are meant for
777 outside use), and (2) call the library's functions. If you wish to
778 do (1), you can do it immediately---there is no need to wait for when
779 the library is loaded. To do (2), you must load the library (preferably
780 with @code{require}).
782 But it is OK to use @code{eval-after-load} in your personal
783 customizations if you don't feel they must meet the design standards for
784 programs meant for wider use.
786 @defvar after-load-alist
787 An alist of expressions to evaluate if and when particular libraries are
788 loaded. Each element looks like this:
791 (@var{filename} @var{forms}@dots{})
794 The function @code{load} checks @code{after-load-alist} in order to
795 implement @code{eval-after-load}.