comparison lispref/loading.texi @ 6453:974a37e5c414

Initial revision
author Richard M. Stallman <rms@gnu.org>
date Mon, 21 Mar 1994 17:36:52 +0000
parents
children 2f1305fcecf6
comparison
equal deleted inserted replaced
6452:8c7032348e93 6453:974a37e5c414
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
11
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.
15
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.
21
22 @cindex top-level form
23 The loaded file must contain Lisp expressions, either as source code
24 or, optionally, as byte-compiled code. Each form in the file is called
25 a @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.
30
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.
35
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 * 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
45
46 @node How Programs Do Loading
47 @section How Programs Do Loading
48
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{Features}). Ultimately, all
54 these facilities call the @code{load} function to do the work.
55
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.
59
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 names @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.)
70
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.
74
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.
84
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}.
88
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}.
92
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}, certain kinds of
96 top-level forms, those which define functions, are undone.
97
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}.
103
104 @code{load} returns @code{t} if the file loads successfully.
105 @end defun
106
107 @ignore
108 @deffn Command load-file filename
109 This function loads the file @var{filename}. If @var{filename} is an
110 absolute file name, then it is loaded. If it is relative, then the
111 current default directory is assumed. @code{load-path} is not used, and
112 suffixes are not appended. Use this function if you wish to specify
113 the file to be loaded exactly.
114 @end deffn
115
116 @deffn Command load-library library
117 This function loads the library named @var{library}. A library is
118 nothing more than a file that may be loaded as described earlier. This
119 function is identical to @code{load}, save that it reads a file name
120 interactively with completion.
121 @end deffn
122 @end ignore
123
124 @defopt load-path
125 @cindex @code{EMACSLOADPATH} environment variable
126 The value of this variable is a list of directories to search when
127 loading files with @code{load}. Each element is a string (which must be
128 a directory name) or @code{nil} (which stands for the current working
129 directory). The value of @code{load-path} is initialized from the
130 environment variable @code{EMACSLOADPATH}, if that exists; otherwise its
131 default value is specified in @file{emacs/src/paths.h} when Emacs is
132 built.
133
134 The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
135 @samp{:} separates directory names, and @samp{.} is used for the current
136 default directory. Here is an example of how to set your
137 @code{EMACSLOADPATH} variable from a @code{csh} @file{.login} file:
138
139 @c This overfull hbox is OK. --rjc 16mar92
140 @smallexample
141 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
142 @end smallexample
143
144 Here is how to set it using @code{sh}:
145
146 @smallexample
147 export EMACSLOADPATH
148 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
149 @end smallexample
150
151 Here is an example of code you can place in a @file{.emacs} file to add
152 several directories to the front of your default @code{load-path}:
153
154 @smallexample
155 (setq load-path
156 (append (list nil "/user/bil/emacs"
157 "/usr/local/lisplib"
158 (expand-file-name "~/emacs"))
159 load-path))
160 @end smallexample
161
162 @c Wordy to rid us of an overfull hbox. --rjc 15mar92
163 @noindent
164 In this example, the path searches the current working directory first,
165 followed then by the @file{/user/bil/emacs} directory and then by
166 the @file{/usr/local/lisplib} directory,
167 which are then followed by the standard directories for Lisp code.
168
169 The command line options @samp{-l} or @samp{-load} specify Lispa library
170 to load. Since this file might be in the current directory, Emacs 18
171 temporarily adds the current directory to the front of @code{load-path}
172 so the file can be found there. Newer Emacs versions also find such
173 files in the current directory, but without altering @code{load-path}.
174 @end defopt
175
176 @defvar load-in-progress
177 This variable is non-@code{nil} if Emacs is in the process of loading a
178 file, and it is @code{nil} otherwise. This is how @code{defun} and
179 @code{provide} determine whether a load is in progress, so that their
180 effect can be undone if the load fails.
181 @end defvar
182
183 To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}.
184
185 @node Autoload
186 @section Autoload
187 @cindex autoload
188
189 The @dfn{autoload} facility allows you to make a function or macro
190 available but put off loading its actual definition. The first call to
191 the function automatically reads the proper file to install the real
192 definition and other associated code, then runs the real definition
193 as if it had been loaded all along.
194
195 There are two ways to set up an autoloaded function: by calling
196 @code{autoload}, and by writing a special ``magic'' comment in the
197 source before the real definition. @code{autoload} is the low-level
198 primitive for autoloading; any Lisp program can call @code{autoload} at
199 any time. Magic comments do nothing on their own; they serve as a guide
200 for the command @code{update-file-autoloads}, which constructs calls to
201 @code{autoload} and arranges to execute them when Emacs is built. Magic
202 comments are the most convenient way to make a function autoload, but
203 only for packages installed along with Emacs.
204
205 @defun autoload symbol filename &optional docstring interactive type
206 This function defines the function (or macro) named @var{symbol} so as
207 to load automatically from @var{filename}. The string @var{filename}
208 specifies the file to load to get the real definition of @var{function}.
209
210 The argument @var{docstring} is the documentation string for the
211 function. Normally, this is the identical to the documentation string
212 in the function definition itself. Specifying the documentation string
213 in the call to @code{autoload} makes it possible to look at the
214 documentation without loading the function's real definition.
215
216 If @var{interactive} is non-@code{nil}, then the function can be called
217 interactively. This lets completion in @kbd{M-x} work without loading
218 the function's real definition. The complete interactive specification
219 need not be given here; it's not needed unless the user actually calls
220 @var{function}, and when that happens, it's time to load the real
221 definition.
222
223 You can autoload macros and keymaps as well as ordinary functions.
224 Specify @var{type} as @code{macro} if @var{function} is really a macro.
225 Specify @var{type} as @code{keymap} if @var{function} is really a
226 keymap. Various parts of Emacs need to know this information without
227 loading the real definition.
228
229 @cindex function cell in autoload
230 If @var{symbol} already has a non-void function definition that is not
231 an autoload object, @code{autoload} does nothing and returns @code{nil}.
232 If the function cell of @var{symbol} is void, or is already an autoload
233 object, then it is defined as an autoload object like this:
234
235 @example
236 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
237 @end example
238
239 For example,
240
241 @example
242 (symbol-function 'run-prolog)
243 @result{} (autoload "prolog" 169681 t nil)
244 @end example
245
246 @noindent
247 In this case, @code{"prolog"} is the name of the file to load, 169681
248 refers to the documentation string in the @file{emacs/etc/DOC} file
249 (@pxref{Documentation Basics}), @code{t} means the function is
250 interactive, and @code{nil} that it is not a macro or a keymap.
251 @end defun
252
253 @cindex autoload errors
254 The autoloaded file usually contains other definitions and may require
255 or provide one or more features. If the file is not completely loaded
256 (due to an error in the evaluation of its contents), any function
257 definitions or @code{provide} calls that occurred during the load are
258 undone. This is to ensure that the next attempt to call any function
259 autoloading from this file will try again to load the file. If not for
260 this, then some of the functions in the file might appear defined, but
261 they might fail to work properly for the lack of certain subroutines
262 defined later in the file and not loaded successfully.
263
264 If the autoloaded file fails to define the desired Lisp function or
265 macro, then an error is signaled with data @code{"Autoloading failed to
266 define function @var{function-name}"}.
267
268 @findex update-file-autoloads
269 @findex update-directory-autoloads
270 A magic autoload comment looks like @samp{;;;###autoload}, on a line
271 by itself, just before the real definition of the function in its
272 autoloadable source file. The command @kbd{M-x update-file-autoloads}
273 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
274 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
275 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
276 autoloads for all files in the current directory.
277
278 The same magic comment can copy any kind of form into
279 @file{loaddefs.el}. If the form following the magic comment is not a
280 function definition, it is copied verbatim. You can also use a magic
281 comment to execute a form at build time executing it when the file
282 itself is loaded. To do this, write the form @dfn{on the same line} as
283 the magic comment. Since it is in a comment, it does nothing when you
284 load the source file; but @code{update-file-autoloads} copies it to
285 @file{loaddefs.el}, where it is executed while building Emacs.
286
287 The following example shows how @code{doctor} is prepared for
288 autoloading with a magic comment:
289
290 @smallexample
291 ;;;###autoload
292 (defun doctor ()
293 "Switch to *doctor* buffer and start giving psychotherapy."
294 (interactive)
295 (switch-to-buffer "*doctor*")
296 (doctor-mode))
297 @end smallexample
298
299 @noindent
300 Here's what that produces in @file{loaddefs.el}:
301
302 @smallexample
303 (autoload 'doctor "doctor"
304 "\
305 Switch to *doctor* buffer and start giving psychotherapy."
306 t)
307 @end smallexample
308
309 @noindent
310 The backslash and newline immediately following the double-quote are a
311 convention used only in the preloaded Lisp files such as
312 @file{loaddefs.el}; they tell @code{make-docfile} to put the
313 documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
314
315 @node Repeated Loading
316 @comment node-name, next, previous, up
317 @section Repeated Loading
318 @cindex repeated loading
319
320 You may load one file more than once in an Emacs session. For
321 example, after you have rewritten and reinstalled a function definition
322 by editing it in a buffer, you may wish to return to the original
323 version; you can do this by reloading the file it came from.
324
325 When you load or reload files, bear in mind that the @code{load} and
326 @code{load-library} functions automatically load a byte-compiled file
327 rather than a non-compiled file of similar name. If you rewrite a file
328 that you intend to save and reinstall, remember to byte-compile it if
329 necessary; otherwise you may find yourself inadvertently reloading the
330 older, byte-compiled file instead of your newer, non-compiled file!
331
332 When writing the forms in a Lisp library file, keep in mind that the
333 file might be loaded more than once. For example, the choice of
334 @code{defvar} vs.@: @code{defconst} for defining a variable depends on
335 whether it is desirable to reinitialize the variable if the library is
336 reloaded: @code{defconst} does so, and @code{defvar} does not.
337 (@xref{Defining Variables}.)
338
339 The simplest way to add an element to an alist is like this:
340
341 @example
342 (setq minor-mode-alist
343 (cons '(leif-mode " Leif") minor-mode-alist))
344 @end example
345
346 @noindent
347 But this would add multiple elements if the library is reloaded.
348 To avoid the problem, write this:
349
350 @example
351 (or (assq 'leif-mode minor-mode-alist)
352 (setq minor-mode-alist
353 (cons '(leif-mode " Leif") minor-mode-alist)))
354 @end example
355
356 Occasionally you will want to test explicitly whether a library has
357 already been loaded. Here's one way to test, in a library, whether it
358 has been loaded before:
359
360 @example
361 (if (not (boundp 'foo-was-loaded))
362 @var{execute-first-time-only})
363
364 (setq foo-was-loaded t)
365 @end example
366
367 @noindent
368 If the library uses @code{provide} to provide a named feature, you can
369 use @code{featurep} to test whether the library has been loaded.
370 @xref{Features}.
371
372 @node Features
373 @section Features
374 @cindex features
375 @cindex requiring features
376 @cindex providing features
377
378 @code{provide} and @code{require} are an alternative to
379 @code{autoload} for loading files automatically. They work in terms of
380 named @dfn{features}. Autoloading is triggered by calling a specific
381 function, but a feature is loaded the first time another program asks
382 for it by name.
383
384 A feature name is a symbol that stands for a collection of functions,
385 variables, etc. The file that defines them should @dfn{provide} the
386 feature. Another program that uses them may ensure they are defined by
387 @dfn{requiring} the feature. This loads the file of definitions if it
388 hasn't been loaded already.
389
390 To require the presence of a feature, call @code{require} with the
391 feature name as argument. @code{require} looks in the global variable
392 @code{features} to see whether the desired feature has been provided
393 already. If not, it loads the feature from the appropriate file. This
394 file should call @code{provide} at the top-level to add the feature to
395 @code{features}; if it fails to do so, @code{require} signals an error.
396 @cindex load error with require
397
398 Features are normally named after the files that provide them, so that
399 @code{require} need not be given the file name.
400
401 For example, in @file{emacs/lisp/prolog.el},
402 the definition for @code{run-prolog} includes the following code:
403
404 @smallexample
405 (defun run-prolog ()
406 "Run an inferior Prolog process, input and output via buffer *prolog*."
407 (interactive)
408 (require 'comint)
409 (switch-to-buffer (make-comint "prolog" prolog-program-name))
410 (inferior-prolog-mode))
411 @end smallexample
412
413 @noindent
414 The expression @code{(require 'comint)} loads the file @file{comint.el}
415 if it has not yet been loaded. This ensures that @code{make-comint} is
416 defined.
417
418 The @file{comint.el} file contains the following top-level expression:
419
420 @smallexample
421 (provide 'comint)
422 @end smallexample
423
424 @noindent
425 This adds @code{comint} to the global @code{features} list, so that
426 @code{(require 'comint)} will henceforth know that nothing needs to be
427 done.
428
429 @cindex byte-compiling @code{require}
430 When @code{require} is used at top-level in a file, it takes effect
431 when you byte-compile that file (@pxref{Byte Compilation}) as well as
432 when you load it. This is in case the required package contains macros
433 that the byte compiler must know about.
434
435 Although top-level calls to @code{require} are evaluated during
436 byte compilation, @code{provide} calls are not. Therefore, you can
437 ensure that a file of definitions is loaded before it is byte-compiled
438 by including a @code{provide} followed by a @code{require} for the same
439 feature, as in the following example.
440
441 @smallexample
442 @group
443 (provide 'my-feature) ; @r{Ignored by byte compiler,}
444 ; @r{evaluated by @code{load}.}
445 (require 'my-feature) ; @r{Evaluated by byte compiler.}
446 @end group
447 @end smallexample
448
449 @defun provide feature
450 This function announces that @var{feature} is now loaded, or being
451 loaded, into the current Emacs session. This means that the facilities
452 associated with @var{feature} are or will be available for other Lisp
453 programs.
454
455 The direct effect of calling @code{provide} is to add @var{feature} to
456 the front of the list @code{features} if it is not already in the list.
457 The argument @var{feature} must be a symbol. @code{provide} returns
458 @var{feature}.
459
460 @smallexample
461 features
462 @result{} (bar bish)
463
464 (provide 'foo)
465 @result{} foo
466 features
467 @result{} (foo bar bish)
468 @end smallexample
469
470 If the file isn't completely loaded, due to an error in the evaluating
471 its contents, any function definitions or @code{provide} calls that
472 occurred during the load are undone. @xref{Autoload}.
473 @end defun
474
475 @defun require feature &optional filename
476 This function checks whether @var{feature} is present in the current
477 Emacs session (using @code{(featurep @var{feature})}; see below). If it
478 is not, then @code{require} loads @var{filename} with @code{load}. If
479 @var{filename} is not supplied, then the name of the symbol
480 @var{feature} is used as the file name to load.
481
482 If loading the file fails to provide @var{feature}, @code{require}
483 signals an error, @samp{Required feature @var{feature} was not
484 provided}.
485 @end defun
486
487 @defun featurep feature
488 This function returns @code{t} if @var{feature} has been provided in the
489 current Emacs session (i.e., @var{feature} is a member of
490 @code{features}.)
491 @end defun
492
493 @defvar features
494 The value of this variable is a list of symbols that are the features
495 loaded in the current Emacs session. Each symbol was put in this list
496 with a call to @code{provide}. The order of the elements in the
497 @code{features} list is not significant.
498 @end defvar
499
500 @node Unloading
501 @section Unloading
502 @cindex unloading
503
504 @c Emacs 19 feature
505 You can discard the functions and variables loaded by a library to
506 reclaim memory for other Lisp objects. To do this, use the function
507 @code{unload-feature}:
508
509 @deffn Command unload-feature feature
510 This command unloads the library that provided feature @var{feature}.
511 It undefines all functions and variables defined with @code{defvar},
512 @code{defmacro}, @code{defconst}, @code{defsubst} and @code{defalias} by
513 that library. It then restores any autoloads associated with those
514 symbols.
515 @end deffn
516
517 The @code{unload-feature} function is written in Lisp; its actions are
518 based on the variable @code{load-history}.
519
520 @defvar load-history
521 This variable's value is an alist connecting library names with the
522 names of functions and variables they define, the features they provide,
523 and the features they require.
524
525 Each element is a list and describes one library. The @sc{car} of the
526 list is the name of the library, as a string. The rest of the list is
527 composed of these kinds of objects:
528
529 @itemize @bullet
530 @item
531 Symbols, which were defined as functions or variables.
532 @item
533 Lists of the form @code{(require . @var{feature})} indicating
534 features that were required.
535 @item
536 Lists of the form @code{(provide . @var{feature})} indicating
537 features that were provided.
538 @end itemize
539
540 The value of @code{load-history} may have one element whose @sc{car} is
541 @code{nil}. This element describes definitions made with
542 @code{eval-buffer} on a buffer that is not visiting a file.
543 @end defvar
544
545 The command @code{eval-region} updates @code{load-history}, but does so
546 by adding the symbols defined to the element for the file being visited,
547 rather than replacing that element.
548
549 @node Hooks for Loading
550 @section Hooks for Loading
551 @cindex loading hooks
552 @cindex hooks for loading
553
554 You can ask for code to be executed if and when a particular library is
555 loaded, by calling @code{eval-after-load}.
556
557 @defun eval-after-load library form
558 This function arranges to evaluate @var{form} at the end of loading the
559 library @var{library}, if and when @var{library} is loaded.
560
561 The library name @var{library} must exactly match the argument of
562 @code{load}. To get the proper results when an installed library is
563 found by searching @code{load-path}, you should not include any
564 directory names in @var{library}.
565
566 An error in @var{form} does not undo the load, but does prevent
567 execution of the rest of @var{form}.
568 @end defun
569
570 @defvar after-load-alist
571 An alist of expressions to evaluate if and when particular libraries are
572 loaded. Each element looks like this:
573
574 @example
575 (@var{filename} @var{forms}@dots{})
576 @end example
577
578 The function @code{load} checks @code{after-load-alist} in order to
579 implement @code{eval-after-load}.
580 @end defvar
581
582 @c Emacs 19 feature