2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/loading.info
8 @node Loading, Byte Compilation, Macros, Top
14 Loading a file of Lisp code means bringing its contents into the Lisp
15 environment in the form of Lisp objects. SXEmacs 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-current-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 * 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.
49 @node How Programs Do Loading
50 @section How Programs Do Loading
52 SXEmacs Lisp has several interfaces for loading. For example,
53 @code{autoload} creates a placeholder object for a function in a file;
54 trying to call the autoloading function loads the file to get the
55 function's real definition (@pxref{Autoload}). @code{require} loads a
56 file if it isn't already loaded (@pxref{Named Features}). Ultimately, all
57 these facilities call the @code{load} function to do the work.
59 @defun load filename &optional missing-ok nomessage nosuffix
60 This function finds and opens a file of Lisp code, evaluates all the
61 forms in it, and closes the file.
63 To find the file, @code{load} first looks for a file named
64 @file{@var{filename}.elc}, that is, for a file whose name is
65 @var{filename} with @samp{.elc} appended. If such a file exists, it is
66 loaded. If there is no file by that name, then @code{load} looks for a
67 file named @file{@var{filename}.el}. If that file exists, it is loaded.
68 Finally, if neither of those names is found, @code{load} looks for a
69 file named @var{filename} with nothing appended, and loads it if it
70 exists. (The @code{load} function is not clever about looking at
71 @var{filename}. In the perverse case of a file named @file{foo.el.el},
72 evaluation of @code{(load "foo.el")} will indeed find it.)
74 If the optional argument @var{nosuffix} is non-@code{nil}, then the
75 suffixes @samp{.elc} and @samp{.el} are not tried. In this case, you
76 must specify the precise file name you want.
78 If @var{filename} is a relative file name, such as @file{foo} or
79 @file{baz/foo.bar}, @code{load} searches for the file using the variable
80 @code{load-path}. It appends @var{filename} to each of the directories
81 listed in @code{load-path}, and loads the first file it finds whose name
82 matches. The current default directory is tried only if it is specified
83 in @code{load-path}, where @code{nil} stands for the default directory.
84 @code{load} tries all three possible suffixes in the first directory in
85 @code{load-path}, then all three suffixes in the second directory, and
88 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
89 means you should consider recompiling @file{foo.el}. @xref{Byte
92 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
93 in the echo area during loading unless @var{nomessage} is
97 Any unhandled errors while loading a file terminate loading. If the
98 load was done for the sake of @code{autoload}, any function definitions
99 made during the loading are undone.
102 If @code{load} can't find the file to load, then normally it signals the
103 error @code{file-error} (with @samp{Cannot open load file
104 @var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
105 @code{load} just returns @code{nil}.
107 You can use the variable @code{load-read-function} to specify a function
108 for @code{load} to use instead of @code{read} for reading expressions.
111 @code{load} returns @code{t} if the file loads successfully.
115 @deffn Command load-file filename
116 This function loads the file @var{filename}. If @var{filename} is an
117 absolute file name, then it is loaded. If it is relative, then the
118 current default directory is assumed. @code{load-path} is not used, and
119 suffixes are not appended. Use this function if you wish to specify
120 the file to be loaded exactly.
123 @deffn Command load-library library
124 This function loads the library named @var{library}. A library is
125 nothing more than a file that may be loaded as described earlier. This
126 function is identical to @code{load}, save that it reads a file name
127 interactively with completion.
132 @cindex @code{EMACSLOADPATH} environment variable
133 The value of this variable is a list of directories to search when
134 loading files with @code{load}. Each element is a string (which must be
135 a directory name) or @code{nil} (which stands for the current working
136 directory). The value of @code{load-path} is initialized from the
137 environment variable @code{EMACSLOADPATH}, if that exists; otherwise its
138 default value is specified in @file{emacs/src/paths.h} when SXEmacs is
141 The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
142 @samp{:} (or @samp{;}, according to the operating system) separates
143 directory names, and @samp{.} is used for the current default directory.
144 Here is an example of how to set your @code{EMACSLOADPATH} variable from
145 a @code{csh} @file{.login} file:
147 @c This overfull hbox is OK. --rjc 16mar92
149 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
152 Here is how to set it using @code{sh}:
156 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
159 Here is an example of code you can place in a @file{init.el} file to add
160 several directories to the front of your default @code{load-path}:
165 (append (list nil "/user/bil/emacs"
172 @c Wordy to rid us of an overfull hbox. --rjc 15mar92
174 In this example, the path searches the current working directory first,
175 followed then by the @file{/user/bil/emacs} directory, the
176 @file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
177 which are then followed by the standard directories for Lisp code.
179 The command line options @samp{-l} or @samp{-load} specify a Lisp
180 library to load as part of SXEmacs startup.
183 Since this file might be in the current directory, Emacs 18 temporarily
184 adds the current directory to the front of @code{load-path} so the file
185 can be found there. Newer Emacs versions also find such files in the
186 current directory, but without altering @code{load-path}.
189 Dumping SXEmacs uses a special value of @code{load-path}. If the value of
190 @code{load-path} at the end of dumping is unchanged (that is, still the
191 same special value), the dumped SXEmacs switches to the ordinary
192 @code{load-path} value when it starts up, as described above. But if
193 @code{load-path} has any other value at the end of dumping, that value
194 is used for execution of the dumped SXEmacs also.
196 Therefore, if you want to change @code{load-path} temporarily for
197 loading a few libraries in @file{site-init.el} or @file{site-load.el},
198 you should bind @code{load-path} locally with @code{let} around the
199 calls to @code{load}.
202 @defun locate-file filename path-list &optional suffixes mode
203 This function searches for a file in the same way that @code{load} does,
204 and returns the file found (if any). (In fact, @code{load} uses this
205 function to search through @code{load-path}.) It searches for
206 @var{filename} through @var{path-list}, expanded by one of the optional
207 @var{suffixes} (string of suffixes separated by @samp{:}s), checking for
208 access @var{mode} (0|1|2|4 = exists|executable|writable|readable),
211 @code{locate-file} keeps hash tables of the directories it searches
212 through, in order to speed things up. It tries valiantly to not get
213 confused in the face of a changing and unpredictable environment, but
214 can occasionally get tripped up. In this case, you will have to call
215 @code{locate-file-clear-hashing} to get it back on track. See that
216 function for details.
219 @defun locate-file-clear-hashing path
220 This function clears the hash records for the specified list of
221 directories. @code{locate-file} uses a hashing scheme to speed lookup, and
222 will correctly track the following environmental changes:
226 changes of any sort to the list of directories to be searched.
228 addition and deletion of non-shadowing files (see below) from the
229 directories in the list.
231 byte-compilation of a .el file into a .elc file.
234 @code{locate-file} will primarily get confused if you add a file that
235 shadows (i.e. has the same name as) another file further down in the
236 directory list. In this case, you must call
237 @code{locate-file-clear-hashing}.
240 @defvar load-in-progress
241 This variable is non-@code{nil} if SXEmacs is in the process of loading a
242 file, and it is @code{nil} otherwise.
245 @defvar load-read-function
246 This variable specifies an alternate expression-reading function for
247 @code{load} and @code{eval-region} to use instead of @code{read}.
248 The function should accept one argument, just as @code{read} does.
250 Normally, the variable's value is @code{nil}, which means those
251 functions should use @code{read}.
254 @defopt load-warn-when-source-newer
255 This variable specifies whether @code{load} should check whether the
256 source is newer than the binary. If this variable is true, then when a
257 @samp{.elc} file is being loaded and the corresponding @samp{.el} is
258 newer, a warning message will be printed. The default is @code{nil},
259 but it is bound to @code{t} during the initial loadup.
262 @defopt load-warn-when-source-only
263 This variable specifies whether @code{load} should warn when loading a
264 @samp{.el} file instead of an @samp{.elc}. If this variable is true,
265 then when @code{load} is called with a filename without an extension,
266 and the @samp{.elc} version doesn't exist but the @samp{.el} version
267 does, then a message will be printed. If an explicit extension is
268 passed to @code{load}, no warning will be printed. The default is
269 @code{nil}, but it is bound to @code{t} during the initial loadup.
272 @defopt load-ignore-elc-files
273 This variable specifies whether @code{load} should ignore @samp{.elc}
274 files when a suffix is not given. This is normally used only to
275 bootstrap the @samp{.elc} files when building SXEmacs, when you use the
276 command @samp{make all-elc}. (This forces the @samp{.el} versions to be
277 loaded in the process of compiling those same files, so that existing
278 out-of-date @samp{.elc} files do not make it mess things up.)
281 To learn how @code{load} is used to build SXEmacs,
282 see @ref{Building SXEmacs}.
289 The @dfn{autoload} facility allows you to make a function or macro
290 known in Lisp, but put off loading the file that defines it. The first
291 call to the function automatically reads the proper file to install the
292 real definition and other associated code, then runs the real definition
293 as if it had been loaded all along.
295 There are two ways to set up an autoloaded function: by calling
296 @code{autoload}, and by writing a special ``magic'' comment in the
297 source before the real definition. @code{autoload} is the low-level
298 primitive for autoloading; any Lisp program can call @code{autoload} at
299 any time. Magic comments do nothing on their own; they serve as a guide
300 for the command @code{update-file-autoloads}, which constructs calls to
301 @code{autoload} and arranges to execute them when SXEmacs is built. Magic
302 comments are the most convenient way to make a function autoload, but
303 only for packages installed along with SXEmacs.
305 @defun autoload function filename &optional docstring interactive type
306 This function defines the function (or macro) named @var{function} so as
307 to load automatically from @var{filename}. The string @var{filename}
308 specifies the file to load to get the real definition of @var{function}.
310 The argument @var{docstring} is the documentation string for the
311 function. Normally, this is identical to the documentation string in
312 the function definition itself. Specifying the documentation string in
313 the call to @code{autoload} makes it possible to look at the
314 documentation without loading the function's real definition.
316 If @var{interactive} is non-@code{nil}, then the function can be called
317 interactively. This lets completion in @kbd{M-x} work without loading
318 the function's real definition. The complete interactive specification
319 need not be given here; it's not needed unless the user actually calls
320 @var{function}, and when that happens, it's time to load the real
323 You can autoload macros and keymaps as well as ordinary functions.
324 Specify @var{type} as @code{macro} if @var{function} is really a macro.
325 Specify @var{type} as @code{keymap} if @var{function} is really a keymap.
326 Various parts of SXEmacs need to know this information without loading the
329 An autoloaded keymap loads automatically during key lookup when a prefix
330 key's binding is the symbol @var{function}. Autoloading does not occur
331 for other kinds of access to the keymap. In particular, it does not
332 happen when a Lisp program gets the keymap from the value of a variable
333 and calls @code{define-key}; not even if the variable name is the same
334 symbol @var{function}.
336 @cindex function cell in autoload
337 If @var{function} already has a non-void function definition that is not
338 an autoload object, @code{autoload} does nothing and returns @code{nil}.
339 If the function cell of @var{function} is void, or is already an autoload
340 object, then it is defined as an autoload object like this:
343 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
350 (symbol-function 'run-prolog)
351 @result{} (autoload "prolog" 169681 t nil)
356 In this case, @code{"prolog"} is the name of the file to load, 169681
357 refers to the documentation string in the @file{DOC} file
358 (@pxref{Documentation Basics}), @code{t} means the function is
359 interactive, and @code{nil} that it is not a macro or a keymap.
362 @cindex autoload errors
363 The autoloaded file usually contains other definitions and may require
364 or provide one or more features. If the file is not completely loaded
365 (due to an error in the evaluation of its contents), any function
366 definitions or @code{provide} calls that occurred during the load are
367 undone. This is to ensure that the next attempt to call any function
368 autoloading from this file will try again to load the file. If not for
369 this, then some of the functions in the file might appear defined, but
370 they might fail to work properly for the lack of certain subroutines
371 defined later in the file and not loaded successfully.
373 SXEmacs as distributed comes with many autoloaded functions.
374 The calls to @code{autoload} are in the file @file{loaddefs.el}.
375 There is a convenient way of updating them automatically.
377 If the autoloaded file fails to define the desired Lisp function or
378 macro, then an error is signaled with data @code{"Autoloading failed to
379 define function @var{function-name}"}.
381 @findex update-file-autoloads
382 @findex update-directory-autoloads
383 A magic autoload comment looks like @samp{;;;###autoload}, on a line
384 by itself, just before the real definition of the function in its
385 autoloadable source file. The command @kbd{M-x update-file-autoloads}
386 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
387 Building SXEmacs loads @file{loaddefs.el} and thus calls @code{autoload}.
388 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
389 autoloads for all files in the current directory.
391 The same magic comment can copy any kind of form into
392 @file{loaddefs.el}. If the form following the magic comment is not a
393 function definition, it is copied verbatim. You can also use a magic
394 comment to execute a form at build time @emph{without} executing it when
395 the file itself is loaded. To do this, write the form @dfn{on the same
396 line} as the magic comment. Since it is in a comment, it does nothing
397 when you load the source file; but @code{update-file-autoloads} copies
398 it to @file{loaddefs.el}, where it is executed while building SXEmacs.
400 The following example shows how @code{doctor} is prepared for
401 autoloading with a magic comment:
406 "Switch to *doctor* buffer and start giving psychotherapy."
408 (switch-to-buffer "*doctor*")
413 Here's what that produces in @file{loaddefs.el}:
416 (autoload 'doctor "doctor"
418 Switch to *doctor* buffer and start giving psychotherapy."
423 The backslash and newline immediately following the double-quote are a
424 convention used only in the preloaded Lisp files such as
425 @file{loaddefs.el}; they tell @code{make-docfile} to put the
426 documentation string in the @file{DOC} file. @xref{Building SXEmacs}.
429 @node Repeated Loading
430 @section Repeated Loading
431 @cindex repeated loading
433 You may load one file more than once in a SXEmacs session. For
434 example, after you have rewritten and reinstalled a function definition
435 by editing it in a buffer, you may wish to return to the original
436 version; you can do this by reloading the file it came from.
438 When you load or reload files, bear in mind that the @code{load} and
439 @code{load-library} functions automatically load a byte-compiled file
440 rather than a non-compiled file of similar name. If you rewrite a file
441 that you intend to save and reinstall, remember to byte-compile it if
442 necessary; otherwise you may find yourself inadvertently reloading the
443 older, byte-compiled file instead of your newer, non-compiled file!
445 When writing the forms in a Lisp library file, keep in mind that the
446 file might be loaded more than once. For example, the choice of
447 @code{defvar} vs.@: @code{defconst} for defining a variable depends on
448 whether it is desirable to reinitialize the variable if the library is
449 reloaded: @code{defconst} does so, and @code{defvar} does not.
450 (@xref{Defining Variables}.)
452 The simplest way to add an element to an alist is like this:
455 (setq minor-mode-alist
456 (cons '(leif-mode " Leif") minor-mode-alist))
460 But this would add multiple elements if the library is reloaded.
461 To avoid the problem, write this:
464 (or (assq 'leif-mode minor-mode-alist)
465 (setq minor-mode-alist
466 (cons '(leif-mode " Leif") minor-mode-alist)))
469 To add an element to a list just once, use @code{add-to-list}
470 (@pxref{Setting Variables}).
472 Occasionally you will want to test explicitly whether a library has
473 already been loaded. Here's one way to test, in a library, whether it
474 has been loaded before:
477 (defvar foo-was-loaded)
479 (if (not (boundp 'foo-was-loaded))
480 @var{execute-first-time-only})
482 (setq foo-was-loaded t)
486 If the library uses @code{provide} to provide a named feature, you can
487 use @code{featurep} to test whether the library has been loaded.
489 @xref{Named Features}.
496 @cindex requiring features
497 @cindex providing features
499 @code{provide} and @code{require} are an alternative to
500 @code{autoload} for loading files automatically. They work in terms of
501 named @dfn{features}. Autoloading is triggered by calling a specific
502 function, but a feature is loaded the first time another program asks
505 A feature name is a symbol that stands for a collection of functions,
506 variables, etc. The file that defines them should @dfn{provide} the
507 feature. Another program that uses them may ensure they are defined by
508 @dfn{requiring} the feature. This loads the file of definitions if it
509 hasn't been loaded already.
511 To require the presence of a feature, call @code{require} with the
512 feature name as argument. @code{require} looks in the global variable
513 @code{features} to see whether the desired feature has been provided
514 already. If not, it loads the feature from the appropriate file. This
515 file should call @code{provide} at the top level to add the feature to
516 @code{features}; if it fails to do so, @code{require} signals an error.
517 @cindex load error with require
519 Features are normally named after the files that provide them, so that
520 @code{require} need not be given the file name.
522 For example, in @file{emacs/lisp/prolog.el},
523 the definition for @code{run-prolog} includes the following code:
527 "Run an inferior Prolog process, input and output via buffer *prolog*."
530 (switch-to-buffer (make-comint "prolog" prolog-program-name))
531 (inferior-prolog-mode))
535 The expression @code{(require 'comint)} loads the file @file{comint.el}
536 if it has not yet been loaded. This ensures that @code{make-comint} is
539 The @file{comint.el} file contains the following top-level expression:
546 This adds @code{comint} to the global @code{features} list, so that
547 @code{(require 'comint)} will henceforth know that nothing needs to be
550 @cindex byte-compiling @code{require}
551 When @code{require} is used at top level in a file, it takes effect
552 when you byte-compile that file (@pxref{Byte Compilation}) as well as
553 when you load it. This is in case the required package contains macros
554 that the byte compiler must know about.
556 Although top-level calls to @code{require} are evaluated during
557 byte compilation, @code{provide} calls are not. Therefore, you can
558 ensure that a file of definitions is loaded before it is byte-compiled
559 by including a @code{provide} followed by a @code{require} for the same
560 feature, as in the following example.
564 (provide 'my-feature) ; @r{Ignored by byte compiler,}
565 ; @r{evaluated by @code{load}.}
566 (require 'my-feature) ; @r{Evaluated by byte compiler.}
571 The compiler ignores the @code{provide}, then processes the
572 @code{require} by loading the file in question. Loading the file does
573 execute the @code{provide} call, so the subsequent @code{require} call
574 does nothing while loading.
576 @defun provide feature
577 This function announces that @var{feature} is now loaded, or being
578 loaded, into the current SXEmacs session. This means that the facilities
579 associated with @var{feature} are or will be available for other Lisp
582 The direct effect of calling @code{provide} is to add @var{feature} to
583 the front of the list @code{features} if it is not already in the list.
584 The argument @var{feature} must be a symbol. @code{provide} returns
594 @result{} (foo bar bish)
597 When a file is loaded to satisfy an autoload, and it stops due to an
598 error in the evaluating its contents, any function definitions or
599 @code{provide} calls that occurred during the load are undone.
603 @defun require feature &optional filename
604 This function checks whether @var{feature} is present in the current
605 SXEmacs session (using @code{(featurep @var{feature})}; see below). If it
606 is not, then @code{require} loads @var{filename} with @code{load}. If
607 @var{filename} is not supplied, then the name of the symbol
608 @var{feature} is used as the file name to load.
610 If loading the file fails to provide @var{feature}, @code{require}
611 signals an error, @samp{Required feature @var{feature} was not
616 This function returns @code{t} if feature @var{fexp} is present in this
617 SXEmacs. Use this to conditionalize execution of lisp code based on the
618 presence or absence of emacs or environment extensions.
620 @var{fexp} can be a symbol, a number, or a list.
622 If @var{fexp} is a symbol, it is looked up in the @code{features} variable,
623 and @code{t} is returned if it is found, @code{nil} otherwise.
625 If @var{fexp} is a number, the function returns @code{t} if this SXEmacs
626 has an equal or greater number than @var{fexp}, @code{nil} otherwise.
627 Note that minor SXEmacs version is expected to be 2 decimal places wide,
628 so @code{(featurep 22.1)} will return @code{nil} on SXEmacs 22.1---you
629 must write @code{(featurep 22.01)}, unless you wish to match for SXEmacs
632 If @var{fexp} is a list whose car is the symbol @code{and}, the function
633 returns @code{t} if all the features in its cdr are present, @code{nil}
636 If @var{fexp} is a list whose car is the symbol @code{or}, the function
637 returns @code{t} if any the features in its cdr are present, @code{nil}
640 If @var{fexp} is a list whose car is the symbol @code{not}, the function
641 returns @code{t} if the feature is not present, @code{nil} otherwise.
647 @result{} ; @r{t on SXEmacs.}
649 (featurep '(and sxemacs gnus))
650 @result{} ; @r{t on SXEmacs with Gnus loaded.}
652 (featurep '(or tty-frames (and emacs 19.30)))
653 @result{} ; @r{t if this Emacs supports TTY frames.}
655 (featurep '(or (and sxemacs 22.01) (and xemacs 21.04) (and emacs 21.3)))
656 @result{} ; @r{t on SXEmacs >=22.1, XEmacs >=21.4, or FSF Emacs >=21.3.}
659 @strong{Please note:} The advanced arguments of this function (anything other than a
660 symbol) are not yet supported by FSF Emacs. If you feel they are useful
661 for supporting multiple Emacs variants, lobby Richard Stallman at
662 @samp{<bug-gnu-emacs@@prep.ai.mit.edu>}.
666 The value of this variable is a list of symbols that are the features
667 loaded in the current SXEmacs session. Each symbol was put in this list
668 with a call to @code{provide}. The order of the elements in the
669 @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{defconst}, @code{defvar}, @code{defun},
686 @code{defmacro}, @code{defsubst}, @code{define-function} and
687 @code{defalias}. It then restores any autoloads formerly associated
688 with those symbols. (Loading saves these in the @code{autoload}
689 property of the symbol.)
691 Ordinarily, @code{unload-feature} refuses to unload a library on which
692 other loaded libraries depend. A library @var{a} depends on library
693 @var{b} if @var{a} contains a @code{require} for @var{b}. If the
694 optional argument @var{force} is non-@code{nil}, dependencies are
695 ignored and you can unload any library.
698 The @code{unload-feature} function is written in Lisp; its actions are
699 based on the variable @code{load-history}.
702 This variable's value is an alist connecting library names with the
703 names of functions and variables they define, the features they provide,
704 and the features they require.
706 Each element is a list and describes one library. The @sc{car} of the
707 list is the name of the library, as a string. The rest of the list is
708 composed of these kinds of objects:
712 Symbols that were defined by this library.
714 Lists of the form @code{(require . @var{feature})} indicating
715 features that were required.
717 Lists of the form @code{(provide . @var{feature})} indicating
718 features that were provided.
721 The value of @code{load-history} may have one element whose @sc{car} is
722 @code{nil}. This element describes definitions made with
723 @code{eval-buffer} on a buffer that is not visiting a file.
726 The command @code{eval-region} updates @code{load-history}, but does so
727 by adding the symbols defined to the element for the file being visited,
728 rather than replacing that element.
731 @node Hooks for Loading
732 @section Hooks for Loading
733 @cindex loading hooks
734 @cindex hooks for loading
736 You can ask for code to be executed if and when a particular library is
737 loaded, by calling @code{eval-after-load}.
739 @defun eval-after-load library form
740 This function arranges to evaluate @var{form} at the end of loading the
741 library @var{library}, if and when @var{library} is loaded. If
742 @var{library} is already loaded, it evaluates @var{form} right away.
744 The library name @var{library} must exactly match the argument of
745 @code{load}. To get the proper results when an installed library is
746 found by searching @code{load-path}, you should not include any
747 directory names in @var{library}.
749 An error in @var{form} does not undo the load, but does prevent
750 execution of the rest of @var{form}.
753 In general, well-designed Lisp programs should not use this feature.
754 The clean and modular ways to interact with a Lisp library are (1)
755 examine and set the library's variables (those which are meant for
756 outside use), and (2) call the library's functions. If you wish to
757 do (1), you can do it immediately---there is no need to wait for when
758 the library is loaded. To do (2), you must load the library (preferably
759 with @code{require}).
761 But it is ok to use @code{eval-after-load} in your personal customizations
762 if you don't feel they must meet the design standards of programs to be
765 @defvar after-load-alist
766 An alist of expressions to evaluate if and when particular libraries are
767 loaded. Each element looks like this:
770 (@var{filename} @var{forms}@dots{})
773 When @code{load} is run and the file-name argument is @var{filename},
774 the @var{forms} in the corresponding element are executed at the end of
777 @var{filename} must match exactly! Normally @var{filename} is the name
778 of a library, with no directory specified, since that is how @code{load}
779 is normally called. An error in @var{forms} does not undo the load, but
780 does prevent execution of the rest of the @var{forms}.
782 The function @code{load} checks @code{after-load-alist} in order to
783 implement @code{eval-after-load}.