(posn-set-point): Fix typos: parameter is `position', not `posn'.
[emacs.git] / lispref / loading.texi
blob893b41d2e51a5e78e573fd23919952b64fd4b313
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
4 @c   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 * Unloading::                   How to ``unload'' a library that was loaded.
45 * Hooks for Loading::           Providing code to be run when
46                                   particular libraries are loaded.
47 @end menu
49 @node How Programs Do Loading
50 @section How Programs Do Loading
52   Emacs Lisp has several interfaces for loading.  For example,
53 @code{autoload} creates a placeholder object for a function defined in a
54 file; trying to call the autoloading function loads the file to get the
55 function's real definition (@pxref{Autoload}).  @code{require} loads a
56 file if it isn't already loaded (@pxref{Named Features}).  Ultimately,
57 all these facilities call the @code{load} function to do the work.
59 @defun load filename &optional missing-ok nomessage nosuffix must-suffix
60 This function finds and opens a file of Lisp code, evaluates all the
61 forms in it, and closes the file.
63 To find the file, @code{load} first looks for a file named
64 @file{@var{filename}.elc}, that is, for a file whose name is
65 @var{filename} with @samp{.elc} appended.  If such a file exists, it is
66 loaded.  If there is no file by that name, then @code{load} looks for a
67 file named @file{@var{filename}.el}.  If that file exists, it is loaded.
68 Finally, if neither of those names is found, @code{load} looks for a
69 file named @var{filename} with nothing appended, and loads it if it
70 exists.  (The @code{load} function is not clever about looking at
71 @var{filename}.  In the perverse case of a file named @file{foo.el.el},
72 evaluation of @code{(load "foo.el")} will indeed find it.)
74 If the optional argument @var{nosuffix} is non-@code{nil}, then the
75 suffixes @samp{.elc} and @samp{.el} are not tried.  In this case, you
76 must specify the precise file name you want.  By specifying the precise
77 file name and using @code{t} for @var{nosuffix}, you can prevent
78 perverse file names such as @file{foo.el.el} from being tried.
80 If the optional argument @var{must-suffix} is non-@code{nil}, then
81 @code{load} insists that the file name used must end in either
82 @samp{.el} or @samp{.elc}, unless it contains an explicit directory
83 name.  If @var{filename} does not contain an explicit directory name,
84 and does not end in a suffix, then @code{load} insists on adding one.
86 If @var{filename} is a relative file name, such as @file{foo} or
87 @file{baz/foo.bar}, @code{load} searches for the file using the variable
88 @code{load-path}.  It appends @var{filename} to each of the directories
89 listed in @code{load-path}, and loads the first file it finds whose name
90 matches.  The current default directory is tried only if it is specified
91 in @code{load-path}, where @code{nil} stands for the default directory.
92 @code{load} tries all three possible suffixes in the first directory in
93 @code{load-path}, then all three suffixes in the second directory, and
94 so on.  @xref{Library Search}.
96 If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
97 means you should consider recompiling @file{foo.el}.  @xref{Byte
98 Compilation}.
100 When loading a source file (not compiled), @code{load} performs
101 character set translation just as Emacs would do when visiting the file.
102 @xref{Coding Systems}.
104 Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
105 in the echo area during loading unless @var{nomessage} is
106 non-@code{nil}.
108 @cindex load errors
109 Any unhandled errors while loading a file terminate loading.  If the
110 load was done for the sake of @code{autoload}, any function definitions
111 made during the loading are undone.
113 @kindex file-error
114 If @code{load} can't find the file to load, then normally it signals the
115 error @code{file-error} (with @samp{Cannot open load file
116 @var{filename}}).  But if @var{missing-ok} is non-@code{nil}, then
117 @code{load} just returns @code{nil}.
119 You can use the variable @code{load-read-function} to specify a function
120 for @code{load} to use instead of @code{read} for reading expressions.
121 See below.
123 @code{load} returns @code{t} if the file loads successfully.
124 @end defun
126 @deffn Command load-file filename
127 This command loads the file @var{filename}.  If @var{filename} is a
128 relative file name, then the current default directory is assumed.
129 @code{load-path} is not used, and suffixes are not appended.  Use this
130 command if you wish to specify precisely the file name to load.
131 @end deffn
133 @deffn Command load-library library
134 This command loads the library named @var{library}.  It is equivalent to
135 @code{load}, except in how it reads its argument interactively.
136 @end deffn
138 @defvar load-in-progress
139 This variable is non-@code{nil} if Emacs is in the process of loading a
140 file, and it is @code{nil} otherwise.
141 @end defvar
143 @anchor{Definition of load-read-function}
144 @defvar load-read-function
145 This variable specifies an alternate expression-reading function for
146 @code{load} and @code{eval-region} to use instead of @code{read}.
147 The function should accept one argument, just as @code{read} does.
149 Normally, the variable's value is @code{nil}, which means those
150 functions should use @code{read}.
152 Instead of using this variable, it is cleaner to use another, newer
153 feature: to pass the function as the @var{read-function} argument to
154 @code{eval-region}.  @xref{Definition of eval-region,, Eval}.
155 @end defvar
157   For information about how @code{load} is used in building Emacs, see
158 @ref{Building Emacs}.
160 @node Library Search
161 @section Library Search
163   When Emacs loads a Lisp library, it searches for the library
164 in a list of directories specified by the variable @code{load-path}.
166 @defopt load-path
167 @cindex @code{EMACSLOADPATH} environment variable
168 The value of this variable is a list of directories to search when
169 loading files with @code{load}.  Each element is a string (which must be
170 a directory name) or @code{nil} (which stands for the current working
171 directory).
172 @end defopt
174   The value of @code{load-path} is initialized from the environment
175 variable @code{EMACSLOADPATH}, if that exists; otherwise its default
176 value is specified in @file{emacs/src/epaths.h} when Emacs is built.
177 Then the list is expanded by adding subdirectories of the directories
178 in the list.
180   The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
181 @samp{:} (or @samp{;}, according to the operating system) separates
182 directory names, and @samp{.} is used for the current default directory.
183 Here is an example of how to set your @code{EMACSLOADPATH} variable from
184 a @code{csh} @file{.login} file:
186 @smallexample
187 setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
188 @end smallexample
190   Here is how to set it using @code{sh}:
192 @smallexample
193 export EMACSLOADPATH
194 EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
195 @end smallexample
197   Here is an example of code you can place in your init file (@pxref{Init
198 File}) to add several directories to the front of your default
199 @code{load-path}:
201 @smallexample
202 @group
203 (setq load-path
204       (append (list nil "/user/bil/emacs"
205                     "/usr/local/lisplib"
206                     "~/emacs")
207               load-path))
208 @end group
209 @end smallexample
211 @c Wordy to rid us of an overfull hbox.  --rjc 15mar92
212 @noindent
213 In this example, the path searches the current working directory first,
214 followed then by the @file{/user/bil/emacs} directory, the
215 @file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
216 which are then followed by the standard directories for Lisp code.
218   Dumping Emacs uses a special value of @code{load-path}.  If the value of
219 @code{load-path} at the end of dumping is unchanged (that is, still the
220 same special value), the dumped Emacs switches to the ordinary
221 @code{load-path} value when it starts up, as described above.  But if
222 @code{load-path} has any other value at the end of dumping, that value
223 is used for execution of the dumped Emacs also.
225   Therefore, if you want to change @code{load-path} temporarily for
226 loading a few libraries in @file{site-init.el} or @file{site-load.el},
227 you should bind @code{load-path} locally with @code{let} around the
228 calls to @code{load}.
230   The default value of @code{load-path}, when running an Emacs which has
231 been installed on the system, includes two special directories (and
232 their subdirectories as well):
234 @smallexample
235 "/usr/local/share/emacs/@var{version}/site-lisp"
236 @end smallexample
238 @noindent
241 @smallexample
242 "/usr/local/share/emacs/site-lisp"
243 @end smallexample
245 @noindent
246 The first one is for locally installed packages for a particular Emacs
247 version; the second is for locally installed packages meant for use with
248 all installed Emacs versions.
250   There are several reasons why a Lisp package that works well in one
251 Emacs version can cause trouble in another.  Sometimes packages need
252 updating for incompatible changes in Emacs; sometimes they depend on
253 undocumented internal Emacs data that can change without notice;
254 sometimes a newer Emacs version incorporates a version of the package,
255 and should be used only with that version.
257   Emacs finds these directories' subdirectories and adds them to
258 @code{load-path} when it starts up.  Both immediate subdirectories and
259 subdirectories multiple levels down are added to @code{load-path}.
261   Not all subdirectories are included, though.  Subdirectories whose
262 names do not start with a letter or digit are excluded.  Subdirectories
263 named @file{RCS} or @file{CVS} are excluded.  Also, a subdirectory which
264 contains a file named @file{.nosearch} is excluded.  You can use these
265 methods to prevent certain subdirectories of the @file{site-lisp}
266 directories from being searched.
268   If you run Emacs from the directory where it was built---that is, an
269 executable that has not been formally installed---then @code{load-path}
270 normally contains two additional directories.  These are the @code{lisp}
271 and @code{site-lisp} subdirectories of the main build directory.  (Both
272 are represented as absolute file names.)
274 @deffn Command locate-library library &optional nosuffix path interactive-call
275 This command finds the precise file name for library @var{library}.  It
276 searches for the library in the same way @code{load} does, and the
277 argument @var{nosuffix} has the same meaning as in @code{load}: don't
278 add suffixes @samp{.elc} or @samp{.el} to the specified name
279 @var{library}.
281 If the @var{path} is non-@code{nil}, that list of directories is used
282 instead of @code{load-path}.
284 When @code{locate-library} is called from a program, it returns the file
285 name as a string.  When the user runs @code{locate-library}
286 interactively, the argument @var{interactive-call} is @code{t}, and this
287 tells @code{locate-library} to display the file name in the echo area.
288 @end deffn
290 @defvar load-suffixes
291 This variable is a list of suffixes (strings) that @code{load} should
292 try adding to the specified file name.  The default value is
293 @code{(".elc" ".el")}.  There is no need to include the null suffix.
294 @end defvar
296 @node Loading Non-ASCII
297 @section Loading Non-@acronym{ASCII} Characters
299   When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
300 characters, these can be represented within Emacs either as unibyte
301 strings or as multibyte strings (@pxref{Text Representations}).  Which
302 representation is used depends on how the file is read into Emacs.  If
303 it is read with decoding into multibyte representation, the text of the
304 Lisp program will be multibyte text, and its string constants will be
305 multibyte strings.  If a file containing Latin-1 characters (for
306 example) is read without decoding, the text of the program will be
307 unibyte text, and its string constants will be unibyte strings.
308 @xref{Coding Systems}.
310   To make the results more predictable, Emacs always performs decoding
311 into the multibyte representation when loading Lisp files, even if it
312 was started with the @samp{--unibyte} option.  This means that string
313 constants with non-@acronym{ASCII} characters translate into multibyte
314 strings.  The only exception is when a particular file specifies no
315 decoding.
317   The reason Emacs is designed this way is so that Lisp programs give
318 predictable results, regardless of how Emacs was started.  In addition,
319 this enables programs that depend on using multibyte text to work even
320 in a unibyte Emacs.  Of course, such programs should be designed to
321 notice whether the user prefers unibyte or multibyte text, by checking
322 @code{default-enable-multibyte-characters}, and convert representations
323 appropriately.
325   In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are
326 multibyte strings should not be noticeable, since inserting them in
327 unibyte buffers converts them to unibyte automatically.  However, if
328 this does make a difference, you can force a particular Lisp file to be
329 interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
330 comment on the file's first line.  With that designator, the file will
331 unconditionally be interpreted as unibyte, even in an ordinary
332 multibyte Emacs session.  This can matter when making keybindings to
333 non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
335 @node Autoload
336 @section Autoload
337 @cindex autoload
339   The @dfn{autoload} facility allows you to make a function or macro
340 known in Lisp, but put off loading the file that defines it.  The first
341 call to the function automatically reads the proper file to install the
342 real definition and other associated code, then runs the real definition
343 as if it had been loaded all along.
345   There are two ways to set up an autoloaded function: by calling
346 @code{autoload}, and by writing a special ``magic'' comment in the
347 source before the real definition.  @code{autoload} is the low-level
348 primitive for autoloading; any Lisp program can call @code{autoload} at
349 any time.  Magic comments are the most convenient way to make a function
350 autoload, for packages installed along with Emacs.  These comments do
351 nothing on their own, but they serve as a guide for the command
352 @code{update-file-autoloads}, which constructs calls to @code{autoload}
353 and arranges to execute them when Emacs is built.
355 @defun autoload function filename &optional docstring interactive type
356 This function defines the function (or macro) named @var{function} so as
357 to load automatically from @var{filename}.  The string @var{filename}
358 specifies the file to load to get the real definition of @var{function}.
360 If @var{filename} does not contain either a directory name, or the
361 suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
362 one of these suffixes, and it will not load from a file whose name is
363 just @var{filename} with no added suffix.
365 The argument @var{docstring} is the documentation string for the
366 function.  Normally, this should be identical to the documentation string
367 in the function definition itself.  Specifying the documentation string
368 in the call to @code{autoload} makes it possible to look at the
369 documentation without loading the function's real definition.
371 If @var{interactive} is non-@code{nil}, that says @var{function} can be
372 called interactively.  This lets completion in @kbd{M-x} work without
373 loading @var{function}'s real definition.  The complete interactive
374 specification is not given here; it's not needed unless the user
375 actually calls @var{function}, and when that happens, it's time to load
376 the real definition.
378 You can autoload macros and keymaps as well as ordinary functions.
379 Specify @var{type} as @code{macro} if @var{function} is really a macro.
380 Specify @var{type} as @code{keymap} if @var{function} is really a
381 keymap.  Various parts of Emacs need to know this information without
382 loading the real definition.
384 An autoloaded keymap loads automatically during key lookup when a prefix
385 key's binding is the symbol @var{function}.  Autoloading does not occur
386 for other kinds of access to the keymap.  In particular, it does not
387 happen when a Lisp program gets the keymap from the value of a variable
388 and calls @code{define-key}; not even if the variable name is the same
389 symbol @var{function}.
391 @cindex function cell in autoload
392 If @var{function} already has a non-void function definition that is not
393 an autoload object, @code{autoload} does nothing and returns @code{nil}.
394 If the function cell of @var{function} is void, or is already an autoload
395 object, then it is defined as an autoload object like this:
397 @example
398 (autoload @var{filename} @var{docstring} @var{interactive} @var{type})
399 @end example
401 For example,
403 @example
404 @group
405 (symbol-function 'run-prolog)
406      @result{} (autoload "prolog" 169681 t nil)
407 @end group
408 @end example
410 @noindent
411 In this case, @code{"prolog"} is the name of the file to load, 169681
412 refers to the documentation string in the
413 @file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
414 @code{t} means the function is interactive, and @code{nil} that it is
415 not a macro or a keymap.
416 @end defun
418 @cindex autoload errors
419   The autoloaded file usually contains other definitions and may require
420 or provide one or more features.  If the file is not completely loaded
421 (due to an error in the evaluation of its contents), any function
422 definitions or @code{provide} calls that occurred during the load are
423 undone.  This is to ensure that the next attempt to call any function
424 autoloading from this file will try again to load the file.  If not for
425 this, then some of the functions in the file might be defined by the
426 aborted load, but fail to work properly for the lack of certain
427 subroutines not loaded successfully because they come later in the file.
429   If the autoloaded file fails to define the desired Lisp function or
430 macro, then an error is signaled with data @code{"Autoloading failed to
431 define function @var{function-name}"}.
433 @findex update-file-autoloads
434 @findex update-directory-autoloads
435   A magic autoload comment consists of @samp{;;;###autoload}, on a line
436 by itself, just before the real definition of the function in its
437 autoloadable source file.  The command @kbd{M-x update-file-autoloads}
438 writes a corresponding @code{autoload} call into @file{loaddefs.el}.
439 Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
440 @kbd{M-x update-directory-autoloads} is even more powerful; it updates
441 autoloads for all files in the current directory.
443   The same magic comment can copy any kind of form into
444 @file{loaddefs.el}.  If the form following the magic comment is not a
445 function-defining form or a @code{defcustom} form, it is copied
446 verbatim.  ``Function-defining forms'' include @code{define-skeleton},
447 @code{define-derived-mode}, @code{define-generic-mode} and
448 @code{define-minor-mode} as well as @code{defun} and
449 @code{defmacro}.  To save space, a @code{defcustom} form is converted to
450 a @code{defvar} in @file{loaddefs.el}, with some additional information
451 if it uses @code{:require}.
453   You can also use a magic comment to execute a form at build time
454 @emph{without} executing it when the file itself is loaded.  To do this,
455 write the form @emph{on the same line} as the magic comment.  Since it
456 is in a comment, it does nothing when you load the source file; but
457 @kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
458 it is executed while building Emacs.
460   The following example shows how @code{doctor} is prepared for
461 autoloading with a magic comment:
463 @smallexample
464 ;;;###autoload
465 (defun doctor ()
466   "Switch to *doctor* buffer and start giving psychotherapy."
467   (interactive)
468   (switch-to-buffer "*doctor*")
469   (doctor-mode))
470 @end smallexample
472 @noindent
473 Here's what that produces in @file{loaddefs.el}:
475 @smallexample
476 (autoload 'doctor "doctor" "\
477 Switch to *doctor* buffer and start giving psychotherapy."
478   t)
479 @end smallexample
481 @noindent
482 The backslash and newline immediately following the double-quote are a
483 convention used only in the preloaded uncompiled Lisp files such as
484 @file{loaddefs.el}; they tell @code{make-docfile} to put the
485 documentation string in the @file{etc/DOC} file.  @xref{Building Emacs}.
486 See also the commentary in @file{lib-src/make-docfile.c}.
488   If you write a function definition with an unusual macro that is not
489 one of the known and recognized function definition methods, use of an
490 ordinary magic autoload comment would copy the whole definition into
491 @code{loaddefs.el}.  That is not desirable.  You can put the desired
492 @code{autoload} call into @code{loaddefs.el} instead by writing this:
494 @smallexample
495 ;;;###autoload (autoload 'foo "myfile")
496 (mydefunmacro foo
497   ...)
498 @end smallexample
500 @node Repeated Loading
501 @section Repeated Loading
502 @cindex repeated loading
504   You can load a given file more than once in an Emacs session.  For
505 example, after you have rewritten and reinstalled a function definition
506 by editing it in a buffer, you may wish to return to the original
507 version; you can do this by reloading the file it came from.
509   When you load or reload files, bear in mind that the @code{load} and
510 @code{load-library} functions automatically load a byte-compiled file
511 rather than a non-compiled file of similar name.  If you rewrite a file
512 that you intend to save and reinstall, you need to byte-compile the new
513 version; otherwise Emacs will load the older, byte-compiled file instead
514 of your newer, non-compiled file!  If that happens, the message
515 displayed when loading the file includes, @samp{(compiled; note, source is
516 newer)}, to remind you to recompile it.
518   When writing the forms in a Lisp library file, keep in mind that the
519 file might be loaded more than once.  For example, think about whether
520 each variable should be reinitialized when you reload the library;
521 @code{defvar} does not change the value if the variable is already
522 initialized.  (@xref{Defining Variables}.)
524   The simplest way to add an element to an alist is like this:
526 @example
527 (setq minor-mode-alist
528       (cons '(leif-mode " Leif") minor-mode-alist))
529 @end example
531 @noindent
532 But this would add multiple elements if the library is reloaded.
533 To avoid the problem, write this:
535 @example
536 (or (assq 'leif-mode minor-mode-alist)
537     (setq minor-mode-alist
538           (cons '(leif-mode " Leif") minor-mode-alist)))
539 @end example
541   To add an element to a list just once, you can also use @code{add-to-list}
542 (@pxref{Setting Variables}).
544   Occasionally you will want to test explicitly whether a library has
545 already been loaded.  Here's one way to test, in a library, whether it
546 has been loaded before:
548 @example
549 (defvar foo-was-loaded nil)
551 (unless foo-was-loaded
552   @var{execute-first-time-only}
553   (setq foo-was-loaded t))
554 @end example
556 @noindent
557 If the library uses @code{provide} to provide a named feature, you can
558 use @code{featurep} earlier in the file to test whether the
559 @code{provide} call has been executed before.
560 @ifnottex
561 @xref{Named Features}.
562 @end ifnottex
564 @node Named Features
565 @section Features
566 @cindex features
567 @cindex requiring features
568 @cindex providing features
570   @code{provide} and @code{require} are an alternative to
571 @code{autoload} for loading files automatically.  They work in terms of
572 named @dfn{features}.  Autoloading is triggered by calling a specific
573 function, but a feature is loaded the first time another program asks
574 for it by name.
576   A feature name is a symbol that stands for a collection of functions,
577 variables, etc.  The file that defines them should @dfn{provide} the
578 feature.  Another program that uses them may ensure they are defined by
579 @dfn{requiring} the feature.  This loads the file of definitions if it
580 hasn't been loaded already.
582   To require the presence of a feature, call @code{require} with the
583 feature name as argument.  @code{require} looks in the global variable
584 @code{features} to see whether the desired feature has been provided
585 already.  If not, it loads the feature from the appropriate file.  This
586 file should call @code{provide} at the top level to add the feature to
587 @code{features}; if it fails to do so, @code{require} signals an error.
588 @cindex load error with require
590   For example, in @file{emacs/lisp/prolog.el},
591 the definition for @code{run-prolog} includes the following code:
593 @smallexample
594 (defun run-prolog ()
595   "Run an inferior Prolog process, with I/O via buffer *prolog*."
596   (interactive)
597   (require 'comint)
598   (switch-to-buffer (make-comint "prolog" prolog-program-name))
599   (inferior-prolog-mode))
600 @end smallexample
602 @noindent
603 The expression @code{(require 'comint)} loads the file @file{comint.el}
604 if it has not yet been loaded.  This ensures that @code{make-comint} is
605 defined.  Features are normally named after the files that provide them,
606 so that @code{require} need not be given the file name.
608 The @file{comint.el} file contains the following top-level expression:
610 @smallexample
611 (provide 'comint)
612 @end smallexample
614 @noindent
615 This adds @code{comint} to the global @code{features} list, so that
616 @code{(require 'comint)} will henceforth know that nothing needs to be
617 done.
619 @cindex byte-compiling @code{require}
620   When @code{require} is used at top level in a file, it takes effect
621 when you byte-compile that file (@pxref{Byte Compilation}) as well as
622 when you load it.  This is in case the required package contains macros
623 that the byte compiler must know about.  It also avoids byte-compiler
624 warnings for functions and variables defined in the file loaded with
625 @code{require}.
627   Although top-level calls to @code{require} are evaluated during
628 byte compilation, @code{provide} calls are not.  Therefore, you can
629 ensure that a file of definitions is loaded before it is byte-compiled
630 by including a @code{provide} followed by a @code{require} for the same
631 feature, as in the following example.
633 @smallexample
634 @group
635 (provide 'my-feature)  ; @r{Ignored by byte compiler,}
636                        ;   @r{evaluated by @code{load}.}
637 (require 'my-feature)  ; @r{Evaluated by byte compiler.}
638 @end group
639 @end smallexample
641 @noindent
642 The compiler ignores the @code{provide}, then processes the
643 @code{require} by loading the file in question.  Loading the file does
644 execute the @code{provide} call, so the subsequent @code{require} call
645 does nothing when the file is loaded.
647 @defun provide feature &optional subfeatures
648 This function announces that @var{feature} is now loaded, or being
649 loaded, into the current Emacs session.  This means that the facilities
650 associated with @var{feature} are or will be available for other Lisp
651 programs.
653 The direct effect of calling @code{provide} is to add @var{feature} to
654 the front of the list @code{features} if it is not already in the list.
655 The argument @var{feature} must be a symbol.  @code{provide} returns
656 @var{feature}.
658 If provided, @var{subfeatures} should be a list of symbols indicating
659 a set of specific subfeatures provided by this version of @var{feature}.
660 You can test the presence of a subfeature using @code{featurep}.
662 @smallexample
663 features
664      @result{} (bar bish)
666 (provide 'foo)
667      @result{} foo
668 features
669      @result{} (foo bar bish)
670 @end smallexample
672 When a file is loaded to satisfy an autoload, and it stops due to an
673 error in the evaluation of its contents, any function definitions or
674 @code{provide} calls that occurred during the load are undone.
675 @xref{Autoload}.
676 @end defun
678 @defun require feature &optional filename noerror
679 This function checks whether @var{feature} is present in the current
680 Emacs session (using @code{(featurep @var{feature})}; see below).  The
681 argument @var{feature} must be a symbol.
683 If the feature is not present, then @code{require} loads @var{filename}
684 with @code{load}.  If @var{filename} is not supplied, then the name of
685 the symbol @var{feature} is used as the base file name to load.
686 However, in this case, @code{require} insists on finding @var{feature}
687 with an added suffix; a file whose name is just @var{feature} won't be
688 used.
690 If loading the file fails to provide @var{feature}, @code{require}
691 signals an error, @samp{Required feature @var{feature} was not
692 provided}, unless @var{noerror} is non-@code{nil}.
693 @end defun
695 @defun featurep feature &optional subfeature
696 This function returns @code{t} if @var{feature} has been provided in
697 the current Emacs session (i.e.@:, if @var{feature} is a member of
698 @code{features}.)  If @var{subfeature} is non-@code{nil}, then the
699 function returns @code{t} only if that subfeature is provided as well
700 (i.e.@: if @var{subfeature} is a member of the @code{subfeature}
701 property of the @var{feature} symbol.)
702 @end defun
704 @defvar features
705 The value of this variable is a list of symbols that are the features
706 loaded in the current Emacs session.  Each symbol was put in this list
707 with a call to @code{provide}.  The order of the elements in the
708 @code{features} list is not significant.
709 @end defvar
711 @node Unloading
712 @section Unloading
713 @cindex unloading
715 @c Emacs 19 feature
716   You can discard the functions and variables loaded by a library to
717 reclaim memory for other Lisp objects.  To do this, use the function
718 @code{unload-feature}:
720 @deffn Command unload-feature feature &optional force
721 This command unloads the library that provided feature @var{feature}.
722 It undefines all functions, macros, and variables defined in that
723 library with @code{defun}, @code{defalias}, @code{defsubst},
724 @code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
725 It then restores any autoloads formerly associated with those symbols.
726 (Loading saves these in the @code{autoload} property of the symbol.)
728 @vindex unload-feature-special-hooks
729 Before restoring the previous definitions, @code{unload-feature} runs
730 @code{remove-hook} to remove functions in the library from certain
731 hooks.  These hooks include variables whose names end in @samp{hook}
732 or @samp{-hooks}, plus those listed in
733 @code{unload-feature-special-hooks}.  This is to prevent Emacs from
734 ceasing to function because important hooks refer to functions that
735 are no longer defined.
737 @vindex @var{feature}-unload-hook
738 If these measures are not sufficient to prevent malfunction, a library
739 can define an explicit unload hook.  If @code{@var{feature}-unload-hook}
740 is defined, it is run as a normal hook before restoring the previous
741 definitions, @emph{instead of} the usual hook-removing actions.  The
742 unload hook ought to undo all the global state changes made by the
743 library that might cease to work once the library is unloaded.
744 @code{unload-feature} can cause problems with libraries that fail to do
745 this, so it should be used with caution.
747 Ordinarily, @code{unload-feature} refuses to unload a library on which
748 other loaded libraries depend.  (A library @var{a} depends on library
749 @var{b} if @var{a} contains a @code{require} for @var{b}.)  If the
750 optional argument @var{force} is non-@code{nil}, dependencies are
751 ignored and you can unload any library.
752 @end deffn
754   The @code{unload-feature} function is written in Lisp; its actions are
755 based on the variable @code{load-history}.
757 @defvar load-history
758 This variable's value is an alist connecting library names with the
759 names of functions and variables they define, the features they provide,
760 and the features they require.
762 Each element is a list and describes one library.  The @sc{car} of the
763 list is the name of the library, as a string.  The rest of the list
764 elements have these forms:
766 @table @code
767 @item @var{fun}
768 The function @var{fun} was defined by this library.
769 @item (t . @var{fun})
770 The function @var{fun} was previously an autoload before this library
771 redefined it as a function.  The following element is always the
772 symbol @var{fun}, which signifies that the library defined @var{fun}
773 as a function.
774 @item (autoload . @var{fun})
775 The function @var{fun} was defined as an autoload.
776 @item (defvar . @var{var})
777 The symbol @var{var} was defined as a variable.
778 @item (require . @var{feature})
779 The feature @var{feature} was required.
780 @item (provide . @var{feature})
781 The feature @var{feature} was provided.
782 @end table
784 The value of @code{load-history} may have one element whose @sc{car} is
785 @code{nil}.  This element describes definitions made with
786 @code{eval-buffer} on a buffer that is not visiting a file.
787 @end defvar
789   The command @code{eval-region} updates @code{load-history}, but does so
790 by adding the symbols defined to the element for the file being visited,
791 rather than replacing that element.  @xref{Eval}.
793 @defvar unload-feature-special-hooks
794 This variable holds a list of hooks to be scanned before unloading a
795 library, to remove functions defined in the library.
796 @end defvar
798 @node Hooks for Loading
799 @section Hooks for Loading
800 @cindex loading hooks
801 @cindex hooks for loading
803 You can ask for code to be executed if and when a particular library is
804 loaded, by calling @code{eval-after-load}.
806 @defun eval-after-load library form
807 This function arranges to evaluate @var{form} at the end of loading the
808 library @var{library}, if and when @var{library} is loaded.  If
809 @var{library} is already loaded, it evaluates @var{form} right away.
811 If @var{library} is a string, it must exactly match the argument of
812 @code{load} used to load the library.  To get the proper results when an
813 installed library is found by searching @code{load-path}, you should not
814 include any directory names in @var{library}.
816 @var{library} can also be a feature (i.e.@: a symbol), in which case
817 @var{form} is evaluated when @code{(provide @var{library})} is called.
819 An error in @var{form} does not undo the load, but does prevent
820 execution of the rest of @var{form}.
821 @end defun
823 In general, well-designed Lisp programs should not use this feature.
824 The clean and modular ways to interact with a Lisp library are (1)
825 examine and set the library's variables (those which are meant for
826 outside use), and (2) call the library's functions.  If you wish to
827 do (1), you can do it immediately---there is no need to wait for when
828 the library is loaded.  To do (2), you must load the library (preferably
829 with @code{require}).
831 But it is OK to use @code{eval-after-load} in your personal
832 customizations if you don't feel they must meet the design standards for
833 programs meant for wider use.
835 @defvar after-load-alist
836 This variable holds an alist of expressions to evaluate if and when
837 particular libraries are loaded.  Each element looks like this:
839 @example
840 (@var{filename} @var{forms}@dots{})
841 @end example
843 The function @code{load} checks @code{after-load-alist} in order to
844 implement @code{eval-after-load}.
845 @end defvar
847 @c Emacs 19 feature
849 @ignore
850    arch-tag: df731f89-0900-4389-a436-9105241b6f7a
851 @end ignore