new version
[emacs.git] / lispref / loading.texi
blob29c2480f1f5ef17ebb606f53f611b3fde9aaa48d
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/loading
6 @node Loading, Byte Compilation, Macros, Top
7 @chapter Loading
8 @cindex loading
9 @cindex library
10 @cindex Lisp library
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
20 in an Emacs buffer.
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
29 definitions.
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
34 containing Lisp code.
36 @menu
37 * How Programs Do Loading::     The @code{load} function and others.
38 * Autoload::                    Setting up a function to autoload.
39 * Repeated Loading::            Precautions about loading a file twice.
40 * Named Features::              Loading a library if it isn't already loaded.
41 * Unloading::                   How to ``unload'' a library that was loaded.
42 * Hooks for Loading::           Providing code to be run when
43                                   particular libraries are loaded.
44 @end menu
46 @node How Programs Do Loading
47 @section How Programs Do Loading
49   Emacs Lisp has several interfaces for loading.  For example,
50 @code{autoload} creates a placeholder object for a function in a file;
51 trying to call the autoloading function loads the file to get the
52 function's real definition (@pxref{Autoload}).  @code{require} loads a
53 file if it isn't already loaded (@pxref{Named Features}).  Ultimately, all
54 these facilities call the @code{load} function to do the work.
56 @defun load filename &optional missing-ok nomessage nosuffix
57 This function finds and opens a file of Lisp code, evaluates all the
58 forms in it, and closes the file.
60 To find the file, @code{load} first looks for a file named
61 @file{@var{filename}.elc}, that is, for a file whose name is
62 @var{filename} with @samp{.elc} appended.  If such a file exists, it is
63 loaded.  If there is no file by that name, then @code{load} looks for a
64 file named @file{@var{filename}.el}.  If that file exists, it is loaded.
65 Finally, if neither of those names is found, @code{load} looks for a
66 file named @var{filename} with nothing appended, and loads it if it
67 exists.  (The @code{load} function is not clever about looking at
68 @var{filename}.  In the perverse case of a file named @file{foo.el.el},
69 evaluation of @code{(load "foo.el")} will indeed find it.)
71 If the optional argument @var{nosuffix} is non-@code{nil}, then the
72 suffixes @samp{.elc} and @samp{.el} are not tried.  In this case, you
73 must specify the precise file name you want.
75 If @var{filename} is a relative file name, such as @file{foo} or
76 @file{baz/foo.bar}, @code{load} searches for the file using the variable
77 @code{load-path}.  It appends @var{filename} to each of the directories
78 listed in @code{load-path}, and loads the first file it finds whose name
79 matches.  The current default directory is tried only if it is specified
80 in @code{load-path}, where @code{nil} stands for the default directory.
81 @code{load} tries all three possible suffixes in the first directory in
82 @code{load-path}, then all three suffixes in the second directory, and
83 so on.
85 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
86 means you should consider recompiling @file{foo.el}.  @xref{Byte
87 Compilation}.
89 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
90 in the echo area during loading unless @var{nomessage} is
91 non-@code{nil}.
93 @cindex load errors
94 Any unhandled errors while loading a file terminate loading.  If the
95 load was done for the sake of @code{autoload}, any function definitions
96 made during the loading are undone.
98 @kindex file-error
99 If @code{load} can't find the file to load, then normally it signals the
100 error @code{file-error} (with @samp{Cannot open load file
101 @var{filename}}).  But if @var{missing-ok} is non-@code{nil}, then
102 @code{load} just returns @code{nil}.
104 You can use the variable @code{load-read-function} to specify a function
105 for @code{load} to use instead of @code{read} for reading expressions.
106 See below.
108 @code{load} returns @code{t} if the file loads successfully.
109 @end defun
111 @ignore
112 @deffn Command load-file filename
113 This function loads the file @var{filename}.  If @var{filename} is an
114 absolute file name, then it is loaded.  If it is relative, then the
115 current default directory is assumed.  @code{load-path} is not used, and
116 suffixes are not appended.  Use this function if you wish to specify
117 the file to be loaded exactly.
118 @end deffn
120 @deffn Command load-library library
121 This function loads the library named @var{library}.  A library is
122 nothing more than a file that may be loaded as described earlier.  This
123 function is identical to @code{load}, save that it reads a file name
124 interactively with completion.
125 @end deffn
126 @end ignore
128 @defopt load-path
129 @cindex @code{EMACSLOADPATH} environment variable
130 The value of this variable is a list of directories to search when
131 loading files with @code{load}.  Each element is a string (which must be
132 a directory name) or @code{nil} (which stands for the current working
133 directory).  The value of @code{load-path} is initialized from the
134 environment variable @code{EMACSLOADPATH}, if that exists; otherwise its
135 default value is specified in @file{emacs/src/paths.h} when Emacs is
136 built.
138 The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
139 @samp{:} (or @samp{;}, according to the operating system) separates
140 directory names, and @samp{.} is used for the current default directory.
141 Here is an example of how to set your @code{EMACSLOADPATH} variable from
142 a @code{csh} @file{.login} file:
144 @c This overfull hbox is OK.  --rjc 16mar92
145 @smallexample
146 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
147 @end smallexample
149 Here is how to set it using @code{sh}:
151 @smallexample
152 export EMACSLOADPATH
153 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
154 @end smallexample
156 Here is an example of code you can place in a @file{.emacs} file to add
157 several directories to the front of your default @code{load-path}:
159 @smallexample
160 @group
161 (setq load-path
162       (append (list nil "/user/bil/emacs"
163                     "/usr/local/lisplib"
164                     "~/emacs")
165               load-path))
166 @end group
167 @end smallexample
169 @c Wordy to rid us of an overfull hbox.  --rjc 15mar92
170 @noindent
171 In this example, the path searches the current working directory first,
172 followed then by the @file{/user/bil/emacs} directory, the
173 @file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
174 which are then followed by the standard directories for Lisp code.
176 The command line options @samp{-l} or @samp{-load} specify a Lisp
177 library to load as part of Emacs startup.  Since this file might be in
178 the current directory, Emacs 18 temporarily adds the current directory
179 to the front of @code{load-path} so the file can be found there.  Newer
180 Emacs versions also find such files in the current directory, but
181 without altering @code{load-path}.
183 Dumping Emacs uses a special value of @code{load-path}.  If the value of
184 @code{load-path} at the end of dumping is unchanged (that is, still the
185 same special value), the dumped Emacs switches to the ordinary
186 @code{load-path} value when it starts up, as described above.  But if
187 @code{load-path} has any other value at the end of dumping, that value
188 is used for execution of the dumped Emacs also.
190 Therefore, if you want to change @code{load-path} temporarily for
191 loading a few libraries in @file{site-init.el} or @file{site-load.el},
192 you should bind @code{load-path} locally with @code{let} around the
193 calls to @code{load}.
194 @end defopt
196   The default value of @code{load-path}, when running an Emacs which has
197 been installed on the system, looks like this:
199 @smallexample
200 ("/usr/local/share/emacs/@var{version}/site-lisp"
201  "/usr/local/share/emacs/site-lisp"
202  "/usr/local/share/emacs/@var{version}/lisp")
203 @end smallexample
205   The last of these three directories is where the Lisp files of Emacs
206 itself are installed; the first two are for additional Lisp packages
207 installed at your site.  The first directory is for locally installed
208 packages that belong with a particular Emacs version; the second is for
209 locally installed packages that can be used with any installed Emacs
210 version.
212   There are several reasons why a Lisp package that works well in one
213 Emacs version can cause trouble in another.  Sometimes packages need
214 updating for incompatible changes in Emacs; sometimes they depend on
215 undocumented internal Emacs data that can change without notice;
216 sometimes a newer Emacs version incorporates a version of the package,
217 and should be used only with that version.
219   If you run Emacs from the directory where it was built---that is, an
220 executable that has not been formally installed---then @code{load-path}
221 normally contains two additional directories.  These are the @code{lisp}
222 and @code{site-lisp} subdirectories of the main build directory.  (Both
223 are represented as absolute file names.)
225 @defvar load-in-progress
226 This variable is non-@code{nil} if Emacs is in the process of loading a
227 file, and it is @code{nil} otherwise.
228 @end defvar
230 @defvar load-read-function
231 This variable specifies an alternate expression-reading function for
232 @code{load} and @code{eval-region} to use instead of @code{read}.
233 The function should accept one argument, just as @code{read} does.
235 Normally, the variable's value is @code{nil}, which means those
236 functions should use @code{read}.
237 @end defvar
239   To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}.
241 @node Autoload
242 @section Autoload
243 @cindex autoload
245   The @dfn{autoload} facility allows you to make a function or macro
246 known in Lisp, but put off loading the file that defines it.  The first
247 call to the function automatically reads the proper file to install the
248 real definition and other associated code, then runs the real definition
249 as if it had been loaded all along.
251   There are two ways to set up an autoloaded function: by calling
252 @code{autoload}, and by writing a special ``magic'' comment in the
253 source before the real definition.  @code{autoload} is the low-level
254 primitive for autoloading; any Lisp program can call @code{autoload} at
255 any time.  Magic comments do nothing on their own; they serve as a guide
256 for the command @code{update-file-autoloads}, which constructs calls to
257 @code{autoload} and arranges to execute them when Emacs is built.  Magic
258 comments are the most convenient way to make a function autoload, but
259 only for packages installed along with Emacs.
261 @defun autoload function filename &optional docstring interactive type
262 This function defines the function (or macro) named @var{function} so as
263 to load automatically from @var{filename}.  The string @var{filename}
264 specifies the file to load to get the real definition of @var{function}.
266 The argument @var{docstring} is the documentation string for the
267 function.  Normally, this is the identical to the documentation string
268 in the function definition itself.  Specifying the documentation string
269 in the call to @code{autoload} makes it possible to look at the
270 documentation without loading the function's real definition.
272 If @var{interactive} is non-@code{nil}, then the function can be called
273 interactively.  This lets completion in @kbd{M-x} work without loading
274 the function's real definition.  The complete interactive specification
275 need not be given here; it's not needed unless the user actually calls
276 @var{function}, and when that happens, it's time to load the real
277 definition.
279 You can autoload macros and keymaps as well as ordinary functions.
280 Specify @var{type} as @code{macro} if @var{function} is really a macro.
281 Specify @var{type} as @code{keymap} if @var{function} is really a
282 keymap.  Various parts of Emacs need to know this information without
283 loading the real definition.
285 An autoloaded keymap loads automatically during key lookup when a prefix
286 key's binding is the symbol @var{function}.  Autoloading does not occur
287 for other kinds of access to the keymap.  In particular, it does not
288 happen when a Lisp program gets the keymap from the value of a variable
289 and calls @code{define-key}; not even if the variable name is the same
290 symbol @var{function}.
292 @cindex function cell in autoload
293 If @var{function} already has a non-void function definition that is not
294 an autoload object, @code{autoload} does nothing and returns @code{nil}.
295 If the function cell of @var{function} is void, or is already an autoload
296 object, then it is defined as an autoload object like this:
298 @example
299 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
300 @end example
302 For example, 
304 @example
305 @group
306 (symbol-function 'run-prolog)
307      @result{} (autoload "prolog" 169681 t nil)
308 @end group
309 @end example
311 @noindent
312 In this case, @code{"prolog"} is the name of the file to load, 169681
313 refers to the documentation string in the @file{emacs/etc/DOC} file
314 (@pxref{Documentation Basics}), @code{t} means the function is
315 interactive, and @code{nil} that it is not a macro or a keymap.
316 @end defun
318 @cindex autoload errors
319   The autoloaded file usually contains other definitions and may require
320 or provide one or more features.  If the file is not completely loaded
321 (due to an error in the evaluation of its contents), any function
322 definitions or @code{provide} calls that occurred during the load are
323 undone.  This is to ensure that the next attempt to call any function
324 autoloading from this file will try again to load the file.  If not for
325 this, then some of the functions in the file might appear defined, but
326 they might fail to work properly for the lack of certain subroutines
327 defined later in the file and not loaded successfully.
329   If the autoloaded file fails to define the desired Lisp function or
330 macro, then an error is signaled with data @code{"Autoloading failed to
331 define function @var{function-name}"}.
333 @findex update-file-autoloads
334 @findex update-directory-autoloads
335   A magic autoload comment looks like @samp{;;;###autoload}, on a line
336 by itself, just before the real definition of the function in its
337 autoloadable source file.  The command @kbd{M-x update-file-autoloads}
338 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
339 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
340 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
341 autoloads for all files in the current directory.
343   The same magic comment can copy any kind of form into
344 @file{loaddefs.el}.  If the form following the magic comment is not a
345 function definition, it is copied verbatim.  You can also use a magic
346 comment to execute a form at build time @emph{without} executing it when
347 the file itself is loaded.  To do this, write the form @emph{on the same
348 line} as the magic comment.  Since it is in a comment, it does nothing
349 when you load the source file; but @code{update-file-autoloads} copies
350 it to @file{loaddefs.el}, where it is executed while building Emacs.
352   The following example shows how @code{doctor} is prepared for
353 autoloading with a magic comment:
355 @smallexample
356 ;;;###autoload
357 (defun doctor ()
358   "Switch to *doctor* buffer and start giving psychotherapy."
359   (interactive)
360   (switch-to-buffer "*doctor*")
361   (doctor-mode))
362 @end smallexample
364 @noindent
365 Here's what that produces in @file{loaddefs.el}:
367 @smallexample
368 (autoload 'doctor "doctor"
369   "\
370 Switch to *doctor* buffer and start giving psychotherapy."
371   t)
372 @end smallexample
374 @noindent
375 The backslash and newline immediately following the double-quote are a
376 convention used only in the preloaded Lisp files such as
377 @file{loaddefs.el}; they tell @code{make-docfile} to put the
378 documentation string in the @file{etc/DOC} file.  @xref{Building Emacs}.
380 @node Repeated Loading
381 @section Repeated Loading
382 @cindex repeated loading
384   You may load one file more than once in an Emacs session.  For
385 example, after you have rewritten and reinstalled a function definition
386 by editing it in a buffer, you may wish to return to the original
387 version; you can do this by reloading the file it came from.
389   When you load or reload files, bear in mind that the @code{load} and
390 @code{load-library} functions automatically load a byte-compiled file
391 rather than a non-compiled file of similar name.  If you rewrite a file
392 that you intend to save and reinstall, remember to byte-compile it if
393 necessary; otherwise you may find yourself inadvertently reloading the
394 older, byte-compiled file instead of your newer, non-compiled file!
396   When writing the forms in a Lisp library file, keep in mind that the
397 file might be loaded more than once.  For example, the choice of
398 @code{defvar} vs.@: @code{defconst} for defining a variable depends on
399 whether it is desirable to reinitialize the variable if the library is
400 reloaded: @code{defconst} does so, and @code{defvar} does not.
401 (@xref{Defining Variables}.)
403   The simplest way to add an element to an alist is like this:
405 @example
406 (setq minor-mode-alist
407       (cons '(leif-mode " Leif") minor-mode-alist))
408 @end example
410 @noindent
411 But this would add multiple elements if the library is reloaded.
412 To avoid the problem, write this:
414 @example
415 (or (assq 'leif-mode minor-mode-alist)
416     (setq minor-mode-alist
417           (cons '(leif-mode " Leif") minor-mode-alist)))
418 @end example
420   To add an element to a list just once, use @code{add-to-list}
421 (@pxref{Setting Variables}).
423   Occasionally you will want to test explicitly whether a library has
424 already been loaded.  Here's one way to test, in a library, whether it
425 has been loaded before:
427 @example
428 (defvar foo-was-loaded)
430 (if (not (boundp 'foo-was-loaded))
431     @var{execute-first-time-only})
433 (setq foo-was-loaded t)
434 @end example
436 @noindent
437 If the library uses @code{provide} to provide a named feature, you can
438 use @code{featurep} to test whether the library has been loaded.
439 @ifinfo
440 @xref{Named Features}.
441 @end ifinfo
443 @node Named Features
444 @section Features
445 @cindex features
446 @cindex requiring features
447 @cindex providing features
449   @code{provide} and @code{require} are an alternative to
450 @code{autoload} for loading files automatically.  They work in terms of
451 named @dfn{features}.  Autoloading is triggered by calling a specific
452 function, but a feature is loaded the first time another program asks
453 for it by name.
455   A feature name is a symbol that stands for a collection of functions,
456 variables, etc.  The file that defines them should @dfn{provide} the
457 feature.  Another program that uses them may ensure they are defined by
458 @dfn{requiring} the feature.  This loads the file of definitions if it
459 hasn't been loaded already.
461   To require the presence of a feature, call @code{require} with the
462 feature name as argument.  @code{require} looks in the global variable
463 @code{features} to see whether the desired feature has been provided
464 already.  If not, it loads the feature from the appropriate file.  This
465 file should call @code{provide} at the top level to add the feature to
466 @code{features}; if it fails to do so, @code{require} signals an error.
467 @cindex load error with require
469   Features are normally named after the files that provide them, so that
470 @code{require} need not be given the file name.
472   For example, in @file{emacs/lisp/prolog.el}, 
473 the definition for @code{run-prolog} includes the following code:
475 @smallexample
476 (defun run-prolog ()
477   "Run an inferior Prolog process, with I/O via buffer *prolog*."
478   (interactive)
479   (require 'comint)
480   (switch-to-buffer (make-comint "prolog" prolog-program-name))
481   (inferior-prolog-mode))
482 @end smallexample
484 @noindent
485 The expression @code{(require 'comint)} loads the file @file{comint.el}
486 if it has not yet been loaded.  This ensures that @code{make-comint} is
487 defined.
489 The @file{comint.el} file contains the following top-level expression:
491 @smallexample
492 (provide 'comint)
493 @end smallexample
495 @noindent
496 This adds @code{comint} to the global @code{features} list, so that
497 @code{(require 'comint)} will henceforth know that nothing needs to be
498 done.
500 @cindex byte-compiling @code{require}
501   When @code{require} is used at top level in a file, it takes effect
502 when you byte-compile that file (@pxref{Byte Compilation}) as well as
503 when you load it.  This is in case the required package contains macros
504 that the byte compiler must know about.
506   Although top-level calls to @code{require} are evaluated during
507 byte compilation, @code{provide} calls are not.  Therefore, you can
508 ensure that a file of definitions is loaded before it is byte-compiled
509 by including a @code{provide} followed by a @code{require} for the same
510 feature, as in the following example.
512 @smallexample
513 @group
514 (provide 'my-feature)  ; @r{Ignored by byte compiler,}
515                        ;   @r{evaluated by @code{load}.}
516 (require 'my-feature)  ; @r{Evaluated by byte compiler.}
517 @end group
518 @end smallexample
520 @noindent
521 The compiler ignores the @code{provide}, then processes the
522 @code{require} by loading the file in question.  Loading the file does
523 execute the @code{provide} call, so the subsequent @code{require} call
524 does nothing while loading.
526 @defun provide feature
527 This function announces that @var{feature} is now loaded, or being
528 loaded, into the current Emacs session.  This means that the facilities
529 associated with @var{feature} are or will be available for other Lisp
530 programs.
532 The direct effect of calling @code{provide} is to add @var{feature} to
533 the front of the list @code{features} if it is not already in the list.
534 The argument @var{feature} must be a symbol.  @code{provide} returns
535 @var{feature}.
537 @smallexample
538 features
539      @result{} (bar bish)
541 (provide 'foo)
542      @result{} foo
543 features
544      @result{} (foo bar bish)
545 @end smallexample
547 When a file is loaded to satisfy an autoload, and it stops due to an
548 error in the evaluating its contents, any function definitions or
549 @code{provide} calls that occurred during the load are undone.
550 @xref{Autoload}.
551 @end defun
553 @defun require feature &optional filename
554 This function checks whether @var{feature} is present in the current
555 Emacs session (using @code{(featurep @var{feature})}; see below).  If it
556 is not, then @code{require} loads @var{filename} with @code{load}.  If
557 @var{filename} is not supplied, then the name of the symbol
558 @var{feature} is used as the file name to load.
560 If loading the file fails to provide @var{feature}, @code{require}
561 signals an error, @samp{Required feature @var{feature} was not
562 provided}.
563 @end defun
565 @defun featurep feature
566 This function returns @code{t} if @var{feature} has been provided in the
567 current Emacs session (i.e., @var{feature} is a member of
568 @code{features}.)
569 @end defun
571 @defvar features
572 The value of this variable is a list of symbols that are the features
573 loaded in the current Emacs session.  Each symbol was put in this list
574 with a call to @code{provide}.  The order of the elements in the
575 @code{features} list is not significant.
576 @end defvar
578 @node Unloading
579 @section Unloading
580 @cindex unloading
582 @c Emacs 19 feature
583   You can discard the functions and variables loaded by a library to
584 reclaim memory for other Lisp objects.  To do this, use the function
585 @code{unload-feature}:
587 @deffn Command unload-feature feature &optional force
588 This command unloads the library that provided feature @var{feature}.
589 It undefines all functions, macros, and variables defined in that
590 library with @code{defconst}, @code{defvar}, @code{defun},
591 @code{defmacro}, @code{defsubst} and @code{defalias}.  It then restores
592 any autoloads formerly associated with those symbols.  (Loading
593 saves these in the @code{autoload} property of the symbol.)
595 Ordinarily, @code{unload-feature} refuses to unload a library on which
596 other loaded libraries depend.  (A library @var{a} depends on library
597 @var{b} if @var{a} contains a @code{require} for @var{b}.)  If the
598 optional argument @var{force} is non-@code{nil}, dependencies are
599 ignored and you can unload any library.
600 @end deffn
602   The @code{unload-feature} function is written in Lisp; its actions are
603 based on the variable @code{load-history}.
605 @defvar load-history
606 This variable's value is an alist connecting library names with the
607 names of functions and variables they define, the features they provide,
608 and the features they require.
610 Each element is a list and describes one library.  The @sc{car} of the
611 list is the name of the library, as a string.  The rest of the list is
612 composed of these kinds of objects:
614 @itemize @bullet
615 @item
616 Symbols that were defined by this library.
617 @item
618 Lists of the form @code{(require . @var{feature})} indicating
619 features that were required.
620 @item
621 Lists of the form @code{(provide . @var{feature})} indicating
622 features that were provided.
623 @end itemize
625 The value of @code{load-history} may have one element whose @sc{car} is
626 @code{nil}.  This element describes definitions made with
627 @code{eval-buffer} on a buffer that is not visiting a file.
628 @end defvar
630   The command @code{eval-region} updates @code{load-history}, but does so
631 by adding the symbols defined to the element for the file being visited,
632 rather than replacing that element.
634 @node Hooks for Loading
635 @section Hooks for Loading
636 @cindex loading hooks
637 @cindex hooks for loading
639 You can ask for code to be executed if and when a particular library is
640 loaded, by calling @code{eval-after-load}.
642 @defun eval-after-load library form
643 This function arranges to evaluate @var{form} at the end of loading the
644 library @var{library}, if and when @var{library} is loaded.  If
645 @var{library} is already loaded, it evaluates @var{form} right away.
647 The library name @var{library} must exactly match the argument of
648 @code{load}.  To get the proper results when an installed library is
649 found by searching @code{load-path}, you should not include any
650 directory names in @var{library}.
652 An error in @var{form} does not undo the load, but does prevent
653 execution of the rest of @var{form}.
654 @end defun
656 In general, well-designed Lisp programs should not use this feature.
657 The clean and modular ways to interact with a Lisp library are (1)
658 examine and set the library's variables (those which are meant for
659 outside use), and (2) call the library's functions.  If you wish to
660 do (1), you can do it immediately---there is no need to wait for when
661 the library is loaded.  To do (2), you must load the library (preferably
662 with @code{require}).
664 But it is ok to use @code{eval-after-load} in your personal customizations
665 if you don't feel they must meet the design standards of programs to be
666 released.
668 @defvar after-load-alist
669 An alist of expressions to evaluate if and when particular libraries are
670 loaded.  Each element looks like this:
672 @example
673 (@var{filename} @var{forms}@dots{})
674 @end example
676 The function @code{load} checks @code{after-load-alist} in order to
677 implement @code{eval-after-load}.
678 @end defvar
680 @c Emacs 19 feature