*** empty log message ***
[emacs.git] / lispref / loading.texi
blobb78fb92ad823e3053ab207ab76e6ee4a30f85f64
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003,
4 @c   2004, 2005, 2006 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/loading
7 @node Loading, Byte Compilation, Customization, Top
8 @chapter Loading
9 @cindex loading
10 @cindex library
11 @cindex Lisp library
13   Loading a file of Lisp code means bringing its contents into the Lisp
14 environment in the form of Lisp objects.  Emacs finds and opens the
15 file, reads the text, evaluates each form, and then closes the file.
17   The load functions evaluate all the expressions in a file just
18 as the @code{eval-current-buffer} function evaluates all the
19 expressions in a buffer.  The difference is that the load functions
20 read and evaluate the text in the file as found on disk, not the text
21 in an Emacs buffer.
23 @cindex top-level form
24   The loaded file must contain Lisp expressions, either as source code
25 or as byte-compiled code.  Each form in the file is called a
26 @dfn{top-level form}.  There is no special format for the forms in a
27 loadable file; any form in a file may equally well be typed directly
28 into a buffer and evaluated there.  (Indeed, most code is tested this
29 way.)  Most often, the forms are function definitions and variable
30 definitions.
32   A file containing Lisp code is often called a @dfn{library}.  Thus,
33 the ``Rmail library'' is a file containing code for Rmail mode.
34 Similarly, a ``Lisp library directory'' is a directory of files
35 containing Lisp code.
37 @menu
38 * How Programs Do Loading:: The @code{load} function and others.
39 * Library Search::          Finding a library to load.
40 * Loading Non-ASCII::       Non-@acronym{ASCII} characters in Emacs Lisp files.
41 * Autoload::                Setting up a function to autoload.
42 * Repeated Loading::        Precautions about loading a file twice.
43 * Named Features::          Loading a library if it isn't already loaded.
44 * Where Defined::           Finding which file defined a certain symbol.
45 * Unloading::               How to ``unload'' a library that was loaded.
46 * Hooks for Loading::       Providing code to be run when
47                               particular libraries are loaded.
48 @end menu
50 @node How Programs Do Loading
51 @section How Programs Do Loading
53   Emacs Lisp has several interfaces for loading.  For example,
54 @code{autoload} creates a placeholder object for a function defined in a
55 file; trying to call the autoloading function loads the file to get the
56 function's real definition (@pxref{Autoload}).  @code{require} loads a
57 file if it isn't already loaded (@pxref{Named Features}).  Ultimately,
58 all these facilities call the @code{load} function to do the work.
60 @defun load filename &optional missing-ok nomessage nosuffix must-suffix
61 This function finds and opens a file of Lisp code, evaluates all the
62 forms in it, and closes the file.
64 To find the file, @code{load} first looks for a file named
65 @file{@var{filename}.elc}, that is, for a file whose name is
66 @var{filename} with @samp{.elc} appended.  If such a file exists, it is
67 loaded.  If there is no file by that name, then @code{load} looks for a
68 file named @file{@var{filename}.el}.  If that file exists, it is loaded.
69 Finally, if neither of those names is found, @code{load} looks for a
70 file named @var{filename} with nothing appended, and loads it if it
71 exists.  (The @code{load} function is not clever about looking at
72 @var{filename}.  In the perverse case of a file named @file{foo.el.el},
73 evaluation of @code{(load "foo.el")} will indeed find it.)
75 If the optional argument @var{nosuffix} is non-@code{nil}, then the
76 suffixes @samp{.elc} and @samp{.el} are not tried.  In this case, you
77 must specify the precise file name you want.  By specifying the precise
78 file name and using @code{t} for @var{nosuffix}, you can prevent
79 perverse file names such as @file{foo.el.el} from being tried.
81 If the optional argument @var{must-suffix} is non-@code{nil}, then
82 @code{load} insists that the file name used must end in either
83 @samp{.el} or @samp{.elc}, unless it contains an explicit directory
84 name.  If @var{filename} does not contain an explicit directory name,
85 and does not end in a suffix, then @code{load} insists on adding one.
87 If @var{filename} is a relative file name, such as @file{foo} or
88 @file{baz/foo.bar}, @code{load} searches for the file using the variable
89 @code{load-path}.  It appends @var{filename} to each of the directories
90 listed in @code{load-path}, and loads the first file it finds whose name
91 matches.  The current default directory is tried only if it is specified
92 in @code{load-path}, where @code{nil} stands for the default directory.
93 @code{load} tries all three possible suffixes in the first directory in
94 @code{load-path}, then all three suffixes in the second directory, and
95 so on.  @xref{Library Search}.
97 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
98 means you should consider recompiling @file{foo.el}.  @xref{Byte
99 Compilation}.
101 When loading a source file (not compiled), @code{load} performs
102 character set translation just as Emacs would do when visiting the file.
103 @xref{Coding Systems}.
105 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
106 in the echo area during loading unless @var{nomessage} is
107 non-@code{nil}.
109 @cindex load errors
110 Any unhandled errors while loading a file terminate loading.  If the
111 load was done for the sake of @code{autoload}, any function definitions
112 made during the loading are undone.
114 @kindex file-error
115 If @code{load} can't find the file to load, then normally it signals the
116 error @code{file-error} (with @samp{Cannot open load file
117 @var{filename}}).  But if @var{missing-ok} is non-@code{nil}, then
118 @code{load} just returns @code{nil}.
120 You can use the variable @code{load-read-function} to specify a function
121 for @code{load} to use instead of @code{read} for reading expressions.
122 See below.
124 @code{load} returns @code{t} if the file loads successfully.
125 @end defun
127 @deffn Command load-file filename
128 This command loads the file @var{filename}.  If @var{filename} is a
129 relative file name, then the current default directory is assumed.
130 @code{load-path} is not used, and suffixes are not appended.  Use this
131 command if you wish to specify precisely the file name to load.
132 @end deffn
134 @deffn Command load-library library
135 This command loads the library named @var{library}.  It is equivalent to
136 @code{load}, except in how it reads its argument interactively.
137 @end deffn
139 @defvar load-in-progress
140 This variable is non-@code{nil} if Emacs is in the process of loading a
141 file, and it is @code{nil} otherwise.
142 @end defvar
144 @defvar load-read-function
145 @anchor{Definition of load-read-function}
146 This variable specifies an alternate expression-reading function for
147 @code{load} and @code{eval-region} to use instead of @code{read}.
148 The function should accept one argument, just as @code{read} does.
150 Normally, the variable's value is @code{nil}, which means those
151 functions should use @code{read}.
153 Instead of using this variable, it is cleaner to use another, newer
154 feature: to pass the function as the @var{read-function} argument to
155 @code{eval-region}.  @xref{Definition of eval-region,, Eval}.
156 @end defvar
158   For information about how @code{load} is used in building Emacs, see
159 @ref{Building Emacs}.
161 @node Library Search
162 @section Library Search
164   When Emacs loads a Lisp library, it searches for the library
165 in a list of directories specified by the variable @code{load-path}.
167 @defopt load-path
168 @cindex @code{EMACSLOADPATH} environment variable
169 The value of this variable is a list of directories to search when
170 loading files with @code{load}.  Each element is a string (which must be
171 a directory name) or @code{nil} (which stands for the current working
172 directory).
173 @end defopt
175   The value of @code{load-path} is initialized from the environment
176 variable @code{EMACSLOADPATH}, if that exists; otherwise its default
177 value is specified in @file{emacs/src/epaths.h} when Emacs is built.
178 Then the list is expanded by adding subdirectories of the directories
179 in the list.
181   The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
182 @samp{:} (or @samp{;}, according to the operating system) separates
183 directory names, and @samp{.} is used for the current default directory.
184 Here is an example of how to set your @code{EMACSLOADPATH} variable from
185 a @code{csh} @file{.login} file:
187 @smallexample
188 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
189 @end smallexample
191   Here is how to set it using @code{sh}:
193 @smallexample
194 export EMACSLOADPATH
195 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
196 @end smallexample
198   Here is an example of code you can place in your init file (@pxref{Init
199 File}) to add several directories to the front of your default
200 @code{load-path}:
202 @smallexample
203 @group
204 (setq load-path
205       (append (list nil "/user/bil/emacs"
206                     "/usr/local/lisplib"
207                     "~/emacs")
208               load-path))
209 @end group
210 @end smallexample
212 @c Wordy to rid us of an overfull hbox.  --rjc 15mar92
213 @noindent
214 In this example, the path searches the current working directory first,
215 followed then by the @file{/user/bil/emacs} directory, the
216 @file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
217 which are then followed by the standard directories for Lisp code.
219   Dumping Emacs uses a special value of @code{load-path}.  If the value of
220 @code{load-path} at the end of dumping is unchanged (that is, still the
221 same special value), the dumped Emacs switches to the ordinary
222 @code{load-path} value when it starts up, as described above.  But if
223 @code{load-path} has any other value at the end of dumping, that value
224 is used for execution of the dumped Emacs also.
226   Therefore, if you want to change @code{load-path} temporarily for
227 loading a few libraries in @file{site-init.el} or @file{site-load.el},
228 you should bind @code{load-path} locally with @code{let} around the
229 calls to @code{load}.
231   The default value of @code{load-path}, when running an Emacs which has
232 been installed on the system, includes two special directories (and
233 their subdirectories as well):
235 @smallexample
236 "/usr/local/share/emacs/@var{version}/site-lisp"
237 @end smallexample
239 @noindent
242 @smallexample
243 "/usr/local/share/emacs/site-lisp"
244 @end smallexample
246 @noindent
247 The first one is for locally installed packages for a particular Emacs
248 version; the second is for locally installed packages meant for use with
249 all installed Emacs versions.
251   There are several reasons why a Lisp package that works well in one
252 Emacs version can cause trouble in another.  Sometimes packages need
253 updating for incompatible changes in Emacs; sometimes they depend on
254 undocumented internal Emacs data that can change without notice;
255 sometimes a newer Emacs version incorporates a version of the package,
256 and should be used only with that version.
258   Emacs finds these directories' subdirectories and adds them to
259 @code{load-path} when it starts up.  Both immediate subdirectories and
260 subdirectories multiple levels down are added to @code{load-path}.
262   Not all subdirectories are included, though.  Subdirectories whose
263 names do not start with a letter or digit are excluded.  Subdirectories
264 named @file{RCS} or @file{CVS} are excluded.  Also, a subdirectory which
265 contains a file named @file{.nosearch} is excluded.  You can use these
266 methods to prevent certain subdirectories of the @file{site-lisp}
267 directories from being searched.
269   If you run Emacs from the directory where it was built---that is, an
270 executable that has not been formally installed---then @code{load-path}
271 normally contains two additional directories.  These are the @code{lisp}
272 and @code{site-lisp} subdirectories of the main build directory.  (Both
273 are represented as absolute file names.)
275 @deffn Command locate-library library &optional nosuffix path interactive-call
276 This command finds the precise file name for library @var{library}.  It
277 searches for the library in the same way @code{load} does, and the
278 argument @var{nosuffix} has the same meaning as in @code{load}: don't
279 add suffixes @samp{.elc} or @samp{.el} to the specified name
280 @var{library}.
282 If the @var{path} is non-@code{nil}, that list of directories is used
283 instead of @code{load-path}.
285 When @code{locate-library} is called from a program, it returns the file
286 name as a string.  When the user runs @code{locate-library}
287 interactively, the argument @var{interactive-call} is @code{t}, and this
288 tells @code{locate-library} to display the file name in the echo area.
289 @end deffn
291 @defvar load-suffixes
292 This variable is a list of suffixes (strings) that @code{load} should
293 try adding to the specified file name.  The default value is
294 @code{(".elc" ".elc.gz" ".el" ".el.gz" ".gz")}.  There is no need to
295 include the null suffix.
296 @end defvar
298 @node Loading Non-ASCII
299 @section Loading Non-@acronym{ASCII} Characters
301   When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
302 characters, these can be represented within Emacs either as unibyte
303 strings or as multibyte strings (@pxref{Text Representations}).  Which
304 representation is used depends on how the file is read into Emacs.  If
305 it is read with decoding into multibyte representation, the text of the
306 Lisp program will be multibyte text, and its string constants will be
307 multibyte strings.  If a file containing Latin-1 characters (for
308 example) is read without decoding, the text of the program will be
309 unibyte text, and its string constants will be unibyte strings.
310 @xref{Coding Systems}.
312   To make the results more predictable, Emacs always performs decoding
313 into the multibyte representation when loading Lisp files, even if it
314 was started with the @samp{--unibyte} option.  This means that string
315 constants with non-@acronym{ASCII} characters translate into multibyte
316 strings.  The only exception is when a particular file specifies no
317 decoding.
319   The reason Emacs is designed this way is so that Lisp programs give
320 predictable results, regardless of how Emacs was started.  In addition,
321 this enables programs that depend on using multibyte text to work even
322 in a unibyte Emacs.  Of course, such programs should be designed to
323 notice whether the user prefers unibyte or multibyte text, by checking
324 @code{default-enable-multibyte-characters}, and convert representations
325 appropriately.
327   In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are
328 multibyte strings should not be noticeable, since inserting them in
329 unibyte buffers converts them to unibyte automatically.  However, if
330 this does make a difference, you can force a particular Lisp file to be
331 interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
332 comment on the file's first line.  With that designator, the file will
333 unconditionally be interpreted as unibyte, even in an ordinary
334 multibyte Emacs session.  This can matter when making keybindings to
335 non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
337 @node Autoload
338 @section Autoload
339 @cindex autoload
341   The @dfn{autoload} facility allows you to make a function or macro
342 known in Lisp, but put off loading the file that defines it.  The first
343 call to the function automatically reads the proper file to install the
344 real definition and other associated code, then runs the real definition
345 as if it had been loaded all along.
347   There are two ways to set up an autoloaded function: by calling
348 @code{autoload}, and by writing a special ``magic'' comment in the
349 source before the real definition.  @code{autoload} is the low-level
350 primitive for autoloading; any Lisp program can call @code{autoload} at
351 any time.  Magic comments are the most convenient way to make a function
352 autoload, for packages installed along with Emacs.  These comments do
353 nothing on their own, but they serve as a guide for the command
354 @code{update-file-autoloads}, which constructs calls to @code{autoload}
355 and arranges to execute them when Emacs is built.
357 @defun autoload function filename &optional docstring interactive type
358 This function defines the function (or macro) named @var{function} so as
359 to load automatically from @var{filename}.  The string @var{filename}
360 specifies the file to load to get the real definition of @var{function}.
362 If @var{filename} does not contain either a directory name, or the
363 suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
364 one of these suffixes, and it will not load from a file whose name is
365 just @var{filename} with no added suffix.
367 The argument @var{docstring} is the documentation string for the
368 function.  Specifying the documentation string in the call to
369 @code{autoload} makes it possible to look at the documentation without
370 loading the function's real definition.  Normally, this should be
371 identical to the documentation string in the function definition
372 itself.  If it isn't, the function definition's documentation string
373 takes effect when it is loaded.
375 If @var{interactive} is non-@code{nil}, that says @var{function} can be
376 called interactively.  This lets completion in @kbd{M-x} work without
377 loading @var{function}'s real definition.  The complete interactive
378 specification is not given here; it's not needed unless the user
379 actually calls @var{function}, and when that happens, it's time to load
380 the real definition.
382 You can autoload macros and keymaps as well as ordinary functions.
383 Specify @var{type} as @code{macro} if @var{function} is really a macro.
384 Specify @var{type} as @code{keymap} if @var{function} is really a
385 keymap.  Various parts of Emacs need to know this information without
386 loading the real definition.
388 An autoloaded keymap loads automatically during key lookup when a prefix
389 key's binding is the symbol @var{function}.  Autoloading does not occur
390 for other kinds of access to the keymap.  In particular, it does not
391 happen when a Lisp program gets the keymap from the value of a variable
392 and calls @code{define-key}; not even if the variable name is the same
393 symbol @var{function}.
395 @cindex function cell in autoload
396 If @var{function} already has a non-void function definition that is not
397 an autoload object, @code{autoload} does nothing and returns @code{nil}.
398 If the function cell of @var{function} is void, or is already an autoload
399 object, then it is defined as an autoload object like this:
401 @example
402 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
403 @end example
405 For example,
407 @example
408 @group
409 (symbol-function 'run-prolog)
410      @result{} (autoload "prolog" 169681 t nil)
411 @end group
412 @end example
414 @noindent
415 In this case, @code{"prolog"} is the name of the file to load, 169681
416 refers to the documentation string in the
417 @file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
418 @code{t} means the function is interactive, and @code{nil} that it is
419 not a macro or a keymap.
420 @end defun
422 @cindex autoload errors
423   The autoloaded file usually contains other definitions and may require
424 or provide one or more features.  If the file is not completely loaded
425 (due to an error in the evaluation of its contents), any function
426 definitions or @code{provide} calls that occurred during the load are
427 undone.  This is to ensure that the next attempt to call any function
428 autoloading from this file will try again to load the file.  If not for
429 this, then some of the functions in the file might be defined by the
430 aborted load, but fail to work properly for the lack of certain
431 subroutines not loaded successfully because they come later in the file.
433   If the autoloaded file fails to define the desired Lisp function or
434 macro, then an error is signaled with data @code{"Autoloading failed to
435 define function @var{function-name}"}.
437 @findex update-file-autoloads
438 @findex update-directory-autoloads
439 @cindex magic autoload comment
440 @cindex autoload cookie
441 @anchor{autoload cookie}
442   A magic autoload comment (often called an @dfn{autoload cookie})
443 consists of @samp{;;;###autoload}, on a line by itself,
444 just before the real definition of the function in its
445 autoloadable source file.  The command @kbd{M-x update-file-autoloads}
446 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
447 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
448 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
449 autoloads for all files in the current directory.
451   The same magic comment can copy any kind of form into
452 @file{loaddefs.el}.  If the form following the magic comment is not a
453 function-defining form or a @code{defcustom} form, it is copied
454 verbatim.  ``Function-defining forms'' include @code{define-skeleton},
455 @code{define-derived-mode}, @code{define-generic-mode} and
456 @code{define-minor-mode} as well as @code{defun} and
457 @code{defmacro}.  To save space, a @code{defcustom} form is converted to
458 a @code{defvar} in @file{loaddefs.el}, with some additional information
459 if it uses @code{:require}.
461   You can also use a magic comment to execute a form at build time
462 @emph{without} executing it when the file itself is loaded.  To do this,
463 write the form @emph{on the same line} as the magic comment.  Since it
464 is in a comment, it does nothing when you load the source file; but
465 @kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
466 it is executed while building Emacs.
468   The following example shows how @code{doctor} is prepared for
469 autoloading with a magic comment:
471 @smallexample
472 ;;;###autoload
473 (defun doctor ()
474   "Switch to *doctor* buffer and start giving psychotherapy."
475   (interactive)
476   (switch-to-buffer "*doctor*")
477   (doctor-mode))
478 @end smallexample
480 @noindent
481 Here's what that produces in @file{loaddefs.el}:
483 @smallexample
484 (autoload (quote doctor) "doctor" "\
485 Switch to *doctor* buffer and start giving psychotherapy.
487 \(fn)" t nil)
488 @end smallexample
490 @noindent
491 @cindex @code{fn} in function's documentation string
492 The backslash and newline immediately following the double-quote are a
493 convention used only in the preloaded uncompiled Lisp files such as
494 @file{loaddefs.el}; they tell @code{make-docfile} to put the
495 documentation string in the @file{etc/DOC} file.  @xref{Building Emacs}.
496 See also the commentary in @file{lib-src/make-docfile.c}.  @samp{(fn)}
497 in the usage part of the documentation string is replaced with the
498 function's name when the various help functions (@pxref{Help
499 Functions}) display it.
501   If you write a function definition with an unusual macro that is not
502 one of the known and recognized function definition methods, use of an
503 ordinary magic autoload comment would copy the whole definition into
504 @code{loaddefs.el}.  That is not desirable.  You can put the desired
505 @code{autoload} call into @code{loaddefs.el} instead by writing this:
507 @smallexample
508 ;;;###autoload (autoload 'foo "myfile")
509 (mydefunmacro foo
510   ...)
511 @end smallexample
513 @node Repeated Loading
514 @section Repeated Loading
515 @cindex repeated loading
517   You can load a given file more than once in an Emacs session.  For
518 example, after you have rewritten and reinstalled a function definition
519 by editing it in a buffer, you may wish to return to the original
520 version; you can do this by reloading the file it came from.
522   When you load or reload files, bear in mind that the @code{load} and
523 @code{load-library} functions automatically load a byte-compiled file
524 rather than a non-compiled file of similar name.  If you rewrite a file
525 that you intend to save and reinstall, you need to byte-compile the new
526 version; otherwise Emacs will load the older, byte-compiled file instead
527 of your newer, non-compiled file!  If that happens, the message
528 displayed when loading the file includes, @samp{(compiled; note, source is
529 newer)}, to remind you to recompile it.
531   When writing the forms in a Lisp library file, keep in mind that the
532 file might be loaded more than once.  For example, think about whether
533 each variable should be reinitialized when you reload the library;
534 @code{defvar} does not change the value if the variable is already
535 initialized.  (@xref{Defining Variables}.)
537   The simplest way to add an element to an alist is like this:
539 @example
540 (push '(leif-mode " Leif") minor-mode-alist)
541 @end example
543 @noindent
544 But this would add multiple elements if the library is reloaded.
545 To avoid the problem, write this:
547 @example
548 (or (assq 'leif-mode minor-mode-alist)
549     (push '(leif-mode " Leif") minor-mode-alist))
550 @end example
552 @noindent
553 or this:
555 @example
556 (add-to-list '(leif-mode " Leif") minor-mode-alist)
557 @end example
559   Occasionally you will want to test explicitly whether a library has
560 already been loaded.  Here's one way to test, in a library, whether it
561 has been loaded before:
563 @example
564 (defvar foo-was-loaded nil)
566 (unless foo-was-loaded
567   @var{execute-first-time-only}
568   (setq foo-was-loaded t))
569 @end example
571 @noindent
572 If the library uses @code{provide} to provide a named feature, you can
573 use @code{featurep} earlier in the file to test whether the
574 @code{provide} call has been executed before.
575 @ifnottex
576 @xref{Named Features}.
577 @end ifnottex
579 @node Named Features
580 @section Features
581 @cindex features
582 @cindex requiring features
583 @cindex providing features
585   @code{provide} and @code{require} are an alternative to
586 @code{autoload} for loading files automatically.  They work in terms of
587 named @dfn{features}.  Autoloading is triggered by calling a specific
588 function, but a feature is loaded the first time another program asks
589 for it by name.
591   A feature name is a symbol that stands for a collection of functions,
592 variables, etc.  The file that defines them should @dfn{provide} the
593 feature.  Another program that uses them may ensure they are defined by
594 @dfn{requiring} the feature.  This loads the file of definitions if it
595 hasn't been loaded already.
597   To require the presence of a feature, call @code{require} with the
598 feature name as argument.  @code{require} looks in the global variable
599 @code{features} to see whether the desired feature has been provided
600 already.  If not, it loads the feature from the appropriate file.  This
601 file should call @code{provide} at the top level to add the feature to
602 @code{features}; if it fails to do so, @code{require} signals an error.
603 @cindex load error with require
605   For example, in @file{emacs/lisp/prolog.el},
606 the definition for @code{run-prolog} includes the following code:
608 @smallexample
609 (defun run-prolog ()
610   "Run an inferior Prolog process, with I/O via buffer *prolog*."
611   (interactive)
612   (require 'comint)
613   (switch-to-buffer (make-comint "prolog" prolog-program-name))
614   (inferior-prolog-mode))
615 @end smallexample
617 @noindent
618 The expression @code{(require 'comint)} loads the file @file{comint.el}
619 if it has not yet been loaded.  This ensures that @code{make-comint} is
620 defined.  Features are normally named after the files that provide them,
621 so that @code{require} need not be given the file name.
623 The @file{comint.el} file contains the following top-level expression:
625 @smallexample
626 (provide 'comint)
627 @end smallexample
629 @noindent
630 This adds @code{comint} to the global @code{features} list, so that
631 @code{(require 'comint)} will henceforth know that nothing needs to be
632 done.
634 @cindex byte-compiling @code{require}
635   When @code{require} is used at top level in a file, it takes effect
636 when you byte-compile that file (@pxref{Byte Compilation}) as well as
637 when you load it.  This is in case the required package contains macros
638 that the byte compiler must know about.  It also avoids byte-compiler
639 warnings for functions and variables defined in the file loaded with
640 @code{require}.
642   Although top-level calls to @code{require} are evaluated during
643 byte compilation, @code{provide} calls are not.  Therefore, you can
644 ensure that a file of definitions is loaded before it is byte-compiled
645 by including a @code{provide} followed by a @code{require} for the same
646 feature, as in the following example.
648 @smallexample
649 @group
650 (provide 'my-feature)  ; @r{Ignored by byte compiler,}
651                        ;   @r{evaluated by @code{load}.}
652 (require 'my-feature)  ; @r{Evaluated by byte compiler.}
653 @end group
654 @end smallexample
656 @noindent
657 The compiler ignores the @code{provide}, then processes the
658 @code{require} by loading the file in question.  Loading the file does
659 execute the @code{provide} call, so the subsequent @code{require} call
660 does nothing when the file is loaded.
662 @defun provide feature &optional subfeatures
663 This function announces that @var{feature} is now loaded, or being
664 loaded, into the current Emacs session.  This means that the facilities
665 associated with @var{feature} are or will be available for other Lisp
666 programs.
668 The direct effect of calling @code{provide} is to add @var{feature} to
669 the front of the list @code{features} if it is not already in the list.
670 The argument @var{feature} must be a symbol.  @code{provide} returns
671 @var{feature}.
673 If provided, @var{subfeatures} should be a list of symbols indicating
674 a set of specific subfeatures provided by this version of @var{feature}.
675 You can test the presence of a subfeature using @code{featurep}.
677 @smallexample
678 features
679      @result{} (bar bish)
681 (provide 'foo)
682      @result{} foo
683 features
684      @result{} (foo bar bish)
685 @end smallexample
687 When a file is loaded to satisfy an autoload, and it stops due to an
688 error in the evaluation of its contents, any function definitions or
689 @code{provide} calls that occurred during the load are undone.
690 @xref{Autoload}.
691 @end defun
693 @defun require feature &optional filename noerror
694 This function checks whether @var{feature} is present in the current
695 Emacs session (using @code{(featurep @var{feature})}; see below).  The
696 argument @var{feature} must be a symbol.
698 If the feature is not present, then @code{require} loads @var{filename}
699 with @code{load}.  If @var{filename} is not supplied, then the name of
700 the symbol @var{feature} is used as the base file name to load.
701 However, in this case, @code{require} insists on finding @var{feature}
702 with an added suffix; a file whose name is just @var{feature} won't be
703 used.
705 If @var{noerror} is non-@code{nil}, that suppresses errors from actual
706 loading of the file.  In that case, @code{require} returns @code{nil}
707 if loading the file fails.  Normally, @code{require} returns
708 @var{feature}.
710 If loading the file succeeds but does not provide @var{feature},
711 @code{require} signals an error, @samp{Required feature @var{feature}
712 was not provided}.
713 @end defun
715 @defun featurep feature &optional subfeature
716 This function returns @code{t} if @var{feature} has been provided in
717 the current Emacs session (i.e.@:, if @var{feature} is a member of
718 @code{features}.)  If @var{subfeature} is non-@code{nil}, then the
719 function returns @code{t} only if that subfeature is provided as well
720 (i.e.@: if @var{subfeature} is a member of the @code{subfeature}
721 property of the @var{feature} symbol.)
722 @end defun
724 @defvar features
725 The value of this variable is a list of symbols that are the features
726 loaded in the current Emacs session.  Each symbol was put in this list
727 with a call to @code{provide}.  The order of the elements in the
728 @code{features} list is not significant.
729 @end defvar
731 @node Where Defined
732 @section Which File Defined a Certain Symbol
734 @defun symbol-file symbol &optional type
735 This function returns the name of the file that defined @var{symbol}.
736 If @var{type} is @code{nil}, then any kind of definition is
737 acceptable.  If @var{type} is @code{defun} or @code{defvar}, that
738 specifies function definition only or variable definition only.
740 The value is normally an absolute file name.  It can also be
741 @code{nil}, if the definition is not associated with any file.
742 @end defun
744   The basis for @code{symbol-file} is the data in the variable
745 @code{load-history}.
747 @defvar load-history
748 This variable's value is an alist connecting library file names with the
749 names of functions and variables they define, the features they provide,
750 and the features they require.
752 Each element is a list and describes one library.  The @sc{car} of the
753 list is the absolute file name of the library, as a string.  The rest
754 of the list elements have these forms:
756 @table @code
757 @item @var{var}
758 The symbol @var{var} was defined as a variable.
759 @item (defun . @var{fun})
760 The function @var{fun} was defined.
761 @item (t . @var{fun})
762 The function @var{fun} was previously an autoload before this library
763 redefined it as a function.  The following element is always
764 @code{(defun . @var{fun})}, which represents defining @var{fun} as a
765 function.
766 @item (autoload . @var{fun})
767 The function @var{fun} was defined as an autoload.
768 @item (require . @var{feature})
769 The feature @var{feature} was required.
770 @item (provide . @var{feature})
771 The feature @var{feature} was provided.
772 @end table
774 The value of @code{load-history} may have one element whose @sc{car} is
775 @code{nil}.  This element describes definitions made with
776 @code{eval-buffer} on a buffer that is not visiting a file.
777 @end defvar
779   The command @code{eval-region} updates @code{load-history}, but does so
780 by adding the symbols defined to the element for the file being visited,
781 rather than replacing that element.  @xref{Eval}.
783 @node Unloading
784 @section Unloading
785 @cindex unloading
787 @c Emacs 19 feature
788   You can discard the functions and variables loaded by a library to
789 reclaim memory for other Lisp objects.  To do this, use the function
790 @code{unload-feature}:
792 @deffn Command unload-feature feature &optional force
793 This command unloads the library that provided feature @var{feature}.
794 It undefines all functions, macros, and variables defined in that
795 library with @code{defun}, @code{defalias}, @code{defsubst},
796 @code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
797 It then restores any autoloads formerly associated with those symbols.
798 (Loading saves these in the @code{autoload} property of the symbol.)
800 @vindex unload-feature-special-hooks
801 Before restoring the previous definitions, @code{unload-feature} runs
802 @code{remove-hook} to remove functions in the library from certain
803 hooks.  These hooks include variables whose names end in @samp{hook}
804 or @samp{-hooks}, plus those listed in
805 @code{unload-feature-special-hooks}.  This is to prevent Emacs from
806 ceasing to function because important hooks refer to functions that
807 are no longer defined.
809 @vindex @var{feature}-unload-hook
810 If these measures are not sufficient to prevent malfunction, a library
811 can define an explicit unload hook.  If @code{@var{feature}-unload-hook}
812 is defined, it is run as a normal hook before restoring the previous
813 definitions, @emph{instead of} the usual hook-removing actions.  The
814 unload hook ought to undo all the global state changes made by the
815 library that might cease to work once the library is unloaded.
816 @code{unload-feature} can cause problems with libraries that fail to do
817 this, so it should be used with caution.
819 Ordinarily, @code{unload-feature} refuses to unload a library on which
820 other loaded libraries depend.  (A library @var{a} depends on library
821 @var{b} if @var{a} contains a @code{require} for @var{b}.)  If the
822 optional argument @var{force} is non-@code{nil}, dependencies are
823 ignored and you can unload any library.
824 @end deffn
826   The @code{unload-feature} function is written in Lisp; its actions are
827 based on the variable @code{load-history}.
829 @defvar unload-feature-special-hooks
830 This variable holds a list of hooks to be scanned before unloading a
831 library, to remove functions defined in the library.
832 @end defvar
834 @node Hooks for Loading
835 @section Hooks for Loading
836 @cindex loading hooks
837 @cindex hooks for loading
839 You can ask for code to be executed if and when a particular library is
840 loaded, by calling @code{eval-after-load}.
842 @defun eval-after-load library form
843 This function arranges to evaluate @var{form} at the end of loading the
844 library @var{library}, if and when @var{library} is loaded.  If
845 @var{library} is already loaded, it evaluates @var{form} right away.
847 If @var{library} is a string, it must exactly match the argument of
848 @code{load} used to load the library.  To get the proper results when an
849 installed library is found by searching @code{load-path}, you should not
850 include any directory names in @var{library}.
852 @var{library} can also be a feature (i.e.@: a symbol), in which case
853 @var{form} is evaluated when @code{(provide @var{library})} is called.
855 An error in @var{form} does not undo the load, but does prevent
856 execution of the rest of @var{form}.
857 @end defun
859 In general, well-designed Lisp programs should not use this feature.
860 The clean and modular ways to interact with a Lisp library are (1)
861 examine and set the library's variables (those which are meant for
862 outside use), and (2) call the library's functions.  If you wish to
863 do (1), you can do it immediately---there is no need to wait for when
864 the library is loaded.  To do (2), you must load the library (preferably
865 with @code{require}).
867 But it is OK to use @code{eval-after-load} in your personal
868 customizations if you don't feel they must meet the design standards for
869 programs meant for wider use.
871 @defvar after-load-alist
872 This variable holds an alist of expressions to evaluate if and when
873 particular libraries are loaded.  Each element looks like this:
875 @example
876 (@var{filename} @var{forms}@dots{})
877 @end example
879 The function @code{load} checks @code{after-load-alist} in order to
880 implement @code{eval-after-load}.
881 @end defvar
883 @c Emacs 19 feature
885 @ignore
886    arch-tag: df731f89-0900-4389-a436-9105241b6f7a
887 @end ignore