loading.texi 43.6 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
3
@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
Glenn Morris's avatar
Glenn Morris committed
4
@c   Free Software Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
5
@c See the file elisp.texi for copying conditions.
6
@node Loading
Glenn Morris's avatar
Glenn Morris committed
7 8 9 10 11
@chapter Loading
@cindex loading
@cindex library
@cindex Lisp library

12 13 14 15
  Loading a file of Lisp code means bringing its contents into the
Lisp environment in the form of Lisp objects.  Emacs finds and opens
the file, reads the text, evaluates each form, and then closes the
file.  Such a file is also called a @dfn{Lisp library}.
Glenn Morris's avatar
Glenn Morris committed
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

  The load functions evaluate all the expressions in a file just
as the @code{eval-buffer} function evaluates all the
expressions in a buffer.  The difference is that the load functions
read and evaluate the text in the file as found on disk, not the text
in an Emacs buffer.

@cindex top-level form
  The loaded file must contain Lisp expressions, either as source code
or as byte-compiled code.  Each form in the file is called a
@dfn{top-level form}.  There is no special format for the forms in a
loadable file; any form in a file may equally well be typed directly
into a buffer and evaluated there.  (Indeed, most code is tested this
way.)  Most often, the forms are function definitions and variable
definitions.

@menu
* How Programs Do Loading:: The @code{load} function and others.
* Load Suffixes::           Details about the suffixes that @code{load} tries.
* Library Search::          Finding a library to load.
* Loading Non-ASCII::       Non-@acronym{ASCII} characters in Emacs Lisp files.
* Autoload::                Setting up a function to autoload.
* Repeated Loading::        Precautions about loading a file twice.
* Named Features::          Loading a library if it isn't already loaded.
* Where Defined::           Finding which file defined a certain symbol.
Glenn Morris's avatar
Glenn Morris committed
41 42 43
* Unloading::               How to "unload" a library that was loaded.
* Hooks for Loading::       Providing code to be run when
                              particular libraries are loaded.
Glenn Morris's avatar
Glenn Morris committed
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
@end menu

@node How Programs Do Loading
@section How Programs Do Loading

  Emacs Lisp has several interfaces for loading.  For example,
@code{autoload} creates a placeholder object for a function defined in a
file; trying to call the autoloading function loads the file to get the
function's real definition (@pxref{Autoload}).  @code{require} loads a
file if it isn't already loaded (@pxref{Named Features}).  Ultimately,
all these facilities call the @code{load} function to do the work.

@defun load filename &optional missing-ok nomessage nosuffix must-suffix
This function finds and opens a file of Lisp code, evaluates all the
forms in it, and closes the file.

To find the file, @code{load} first looks for a file named
@file{@var{filename}.elc}, that is, for a file whose name is
@var{filename} with the extension @samp{.elc} appended.  If such a
file exists, it is loaded.  If there is no file by that name, then
@code{load} looks for a file named @file{@var{filename}.el}.  If that
file exists, it is loaded.  Finally, if neither of those names is
found, @code{load} looks for a file named @var{filename} with nothing
appended, and loads it if it exists.  (The @code{load} function is not
clever about looking at @var{filename}.  In the perverse case of a
file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will
indeed find it.)

If Auto Compression mode is enabled, as it is by default, then if
@code{load} can not find a file, it searches for a compressed version
of the file before trying other file names.  It decompresses and loads
it if it exists.  It looks for compressed versions by appending each
of the suffixes in @code{jka-compr-load-suffixes} to the file name.
The value of this variable must be a list of strings. Its standard
value is @code{(".gz")}.

If the optional argument @var{nosuffix} is non-@code{nil}, then
@code{load} does not try the suffixes @samp{.elc} and @samp{.el}.  In
this case, you must specify the precise file name you want, except
that, if Auto Compression mode is enabled, @code{load} will still use
@code{jka-compr-load-suffixes} to find compressed versions.  By
specifying the precise file name and using @code{t} for
86 87
@var{nosuffix}, you can prevent file names like @file{foo.el.el} from
being tried.
Glenn Morris's avatar
Glenn Morris committed
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103

If the optional argument @var{must-suffix} is non-@code{nil}, then
@code{load} insists that the file name used must end in either
@samp{.el} or @samp{.elc} (possibly extended with a compression
suffix), unless it contains an explicit directory name.

If @var{filename} is a relative file name, such as @file{foo} or
@file{baz/foo.bar}, @code{load} searches for the file using the variable
@code{load-path}.  It appends @var{filename} to each of the directories
listed in @code{load-path}, and loads the first file it finds whose name
matches.  The current default directory is tried only if it is specified
in @code{load-path}, where @code{nil} stands for the default directory.
@code{load} tries all three possible suffixes in the first directory in
@code{load-path}, then all three suffixes in the second directory, and
so on.  @xref{Library Search}.

104 105 106 107
Whatever the name under which the file is eventually found, and the
directory where Emacs found it, Emacs sets the value of the variable
@code{load-file-name} to that file's name.

Glenn Morris's avatar
Glenn Morris committed
108 109 110 111 112 113 114 115
If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
means you should consider recompiling @file{foo.el}.  @xref{Byte
Compilation}.

When loading a source file (not compiled), @code{load} performs
character set translation just as Emacs would do when visiting the file.
@xref{Coding Systems}.

Glenn Morris's avatar
Glenn Morris committed
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
@c This is referred to from the Macros chapter.
@c Not sure if it should be the other way round.
@cindex eager macro expansion
When loading an uncompiled file, Emacs tries to expand any macros
that the file contains (@pxref{Macros}).  We refer to this as
@dfn{eager macro expansion}.  Doing this (rather than deferring
the expansion until the relevant code runs) can significantly speed
up the execution of uncompiled code.  Sometimes, this macro expansion
cannot be done, owing to a cyclic dependency.  In the simplest
example of this, the file you are loading refers to a macro defined
in another file, and that file in turn requires the file you are
loading.  This is generally harmless.  Emacs prints a warning
(@samp{Eager macro-expansion skipped due to cycle@dots{}})
giving details of the problem, but it still loads the file, just
leaving the macro unexpanded for now.  You may wish to restructure
your code so that this does not happen.  Loading a compiled file does
not cause macroexpansion, because this should already have happened
during compilation.  @xref{Compiling Macros}.

Glenn Morris's avatar
Glenn Morris committed
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
in the echo area during loading unless @var{nomessage} is
non-@code{nil}.

@cindex load errors
Any unhandled errors while loading a file terminate loading.  If the
load was done for the sake of @code{autoload}, any function definitions
made during the loading are undone.

@kindex file-error
If @code{load} can't find the file to load, then normally it signals the
error @code{file-error} (with @samp{Cannot open load file
@var{filename}}).  But if @var{missing-ok} is non-@code{nil}, then
@code{load} just returns @code{nil}.

You can use the variable @code{load-read-function} to specify a function
for @code{load} to use instead of @code{read} for reading expressions.
See below.

@code{load} returns @code{t} if the file loads successfully.
@end defun

@deffn Command load-file filename
This command loads the file @var{filename}.  If @var{filename} is a
relative file name, then the current default directory is assumed.
This command does not use @code{load-path}, and does not append
suffixes.  However, it does look for compressed versions (if Auto
Compression Mode is enabled).  Use this command if you wish to specify
precisely the file name to load.
@end deffn

@deffn Command load-library library
This command loads the library named @var{library}.  It is equivalent to
168 169
@code{load}, except for the way it reads its argument interactively.
@xref{Lisp Libraries,,,emacs, The GNU Emacs Manual}.
Glenn Morris's avatar
Glenn Morris committed
170 171 172 173 174 175 176
@end deffn

@defvar load-in-progress
This variable is non-@code{nil} if Emacs is in the process of loading a
file, and it is @code{nil} otherwise.
@end defvar

177 178 179 180 181 182
@defvar load-file-name
When Emacs is in the process of loading a file, this variable's value
is the name of that file, as Emacs found it during the search
described earlier in this section.
@end defvar

Glenn Morris's avatar
Glenn Morris committed
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254
@defvar load-read-function
@anchor{Definition of load-read-function}
@c do not allow page break at anchor; work around Texinfo deficiency.
This variable specifies an alternate expression-reading function for
@code{load} and @code{eval-region} to use instead of @code{read}.
The function should accept one argument, just as @code{read} does.

Normally, the variable's value is @code{nil}, which means those
functions should use @code{read}.

Instead of using this variable, it is cleaner to use another, newer
feature: to pass the function as the @var{read-function} argument to
@code{eval-region}.  @xref{Definition of eval-region,, Eval}.
@end defvar

  For information about how @code{load} is used in building Emacs, see
@ref{Building Emacs}.

@node Load Suffixes
@section Load Suffixes
We now describe some technical details about the exact suffixes that
@code{load} tries.

@defvar load-suffixes
This is a list of suffixes indicating (compiled or source) Emacs Lisp
files.  It should not include the empty string.  @code{load} uses
these suffixes in order when it appends Lisp suffixes to the specified
file name.  The standard value is @code{(".elc" ".el")} which produces
the behavior described in the previous section.
@end defvar

@defvar load-file-rep-suffixes
This is a list of suffixes that indicate representations of the same
file.  This list should normally start with the empty string.
When @code{load} searches for a file it appends the suffixes in this
list, in order, to the file name, before searching for another file.

Enabling Auto Compression mode appends the suffixes in
@code{jka-compr-load-suffixes} to this list and disabling Auto
Compression mode removes them again.  The standard value of
@code{load-file-rep-suffixes} if Auto Compression mode is disabled is
@code{("")}.  Given that the standard value of
@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value
of @code{load-file-rep-suffixes} if Auto Compression mode is enabled
is @code{("" ".gz")}.
@end defvar

@defun get-load-suffixes
This function returns the list of all suffixes that @code{load} should
try, in order, when its @var{must-suffix} argument is non-@code{nil}.
This takes both @code{load-suffixes} and @code{load-file-rep-suffixes}
into account.  If @code{load-suffixes}, @code{jka-compr-load-suffixes}
and @code{load-file-rep-suffixes} all have their standard values, this
function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto
Compression mode is enabled and @code{(".elc" ".el")} if Auto
Compression mode is disabled.
@end defun

To summarize, @code{load} normally first tries the suffixes in the
value of @code{(get-load-suffixes)} and then those in
@code{load-file-rep-suffixes}.  If @var{nosuffix} is non-@code{nil},
it skips the former group, and if @var{must-suffix} is non-@code{nil},
it skips the latter group.

@node Library Search
@section Library Search
@cindex library search
@cindex find library

  When Emacs loads a Lisp library, it searches for the library
in a list of directories specified by the variable @code{load-path}.

255
@defvar load-path
256
@cindex @env{EMACSLOADPATH} environment variable
Glenn Morris's avatar
Glenn Morris committed
257 258 259 260
The value of this variable is a list of directories to search when
loading files with @code{load}.  Each element is a string (which must be
a directory name) or @code{nil} (which stands for the current working
directory).
261
@end defvar
Glenn Morris's avatar
Glenn Morris committed
262

263 264 265 266 267 268 269 270
  Each time Emacs starts up, it sets up the value of @code{load-path}
in several steps.  First, it initializes @code{load-path} to the
directories specified by the environment variable @env{EMACSLOADPATH},
if that exists.  The syntax of @env{EMACSLOADPATH} is the same as used
for @code{PATH}; directory names are separated by @samp{:} (or
@samp{;}, on some operating systems), and @samp{.} stands for the
current default directory.  Here is an example of how to set
@env{EMACSLOADPATH} variable from @command{sh}:
Glenn Morris's avatar
Glenn Morris committed
271

272
@example
Glenn Morris's avatar
Glenn Morris committed
273
export EMACSLOADPATH
274
EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
275
@end example
Glenn Morris's avatar
Glenn Morris committed
276

277 278
@noindent
Here is how to set it from @code{csh}:
Glenn Morris's avatar
Glenn Morris committed
279

280
@example
281
setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
282
@end example
Glenn Morris's avatar
Glenn Morris committed
283

284
@cindex site-lisp directories
285 286
  If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs
initializes @code{load-path} with the following two directories:
Glenn Morris's avatar
Glenn Morris committed
287

288
@example
Glenn Morris's avatar
Glenn Morris committed
289
"/usr/local/share/emacs/@var{version}/site-lisp"
290
@end example
Glenn Morris's avatar
Glenn Morris committed
291 292 293 294

@noindent
and

295
@example
Glenn Morris's avatar
Glenn Morris committed
296
"/usr/local/share/emacs/site-lisp"
297
@end example
Glenn Morris's avatar
Glenn Morris committed
298 299 300

@noindent
The first one is for locally installed packages for a particular Emacs
301 302
version; the second is for locally installed packages meant for use
with all installed Emacs versions.
Glenn Morris's avatar
Glenn Morris committed
303 304

  If you run Emacs from the directory where it was built---that is, an
305 306 307
executable that has not been formally installed---Emacs puts two more
directories in @code{load-path}.  These are the @code{lisp} and
@code{site-lisp} subdirectories of the main build directory.  (Both
Glenn Morris's avatar
Glenn Morris committed
308 309
are represented as absolute file names.)

310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325
  Next, Emacs ``expands'' the initial list of directories in
@code{load-path} by adding the subdirectories of those directories.
Both immediate subdirectories and subdirectories multiple levels down
are added.  But it excludes subdirectories whose names do not start
with a letter or digit, and subdirectories named @file{RCS} or
@file{CVS}, and subdirectories containing a file named
@file{.nosearch}.

  Next, Emacs adds any extra load directory that you specify using the
@samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The
GNU Emacs Manual}).  It also adds the directories where optional
packages are installed, if any (@pxref{Packaging Basics}).

  It is common to add code to one's init file (@pxref{Init File}) to
add one or more directories to @code{load-path}.  For example:

326
@example
327
(push "~/.emacs.d/lisp" load-path)
328
@end example
329 330 331 332 333 334 335 336

  Dumping Emacs uses a special value of @code{load-path}.  If the
value of @code{load-path} at the end of dumping is unchanged (that is,
still the same special value), the dumped Emacs switches to the
ordinary @code{load-path} value when it starts up, as described above.
But if @code{load-path} has any other value at the end of dumping,
that value is used for execution of the dumped Emacs also.

Glenn Morris's avatar
Glenn Morris committed
337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352
@deffn Command locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library @var{library}.  It
searches for the library in the same way @code{load} does, and the
argument @var{nosuffix} has the same meaning as in @code{load}: don't
add suffixes @samp{.elc} or @samp{.el} to the specified name
@var{library}.

If the @var{path} is non-@code{nil}, that list of directories is used
instead of @code{load-path}.

When @code{locate-library} is called from a program, it returns the file
name as a string.  When the user runs @code{locate-library}
interactively, the argument @var{interactive-call} is @code{t}, and this
tells @code{locate-library} to display the file name in the echo area.
@end deffn

353 354 355 356 357 358 359 360 361
@cindex shadowed Lisp files
@deffn Command list-load-path-shadows &optional stringp
This command shows a list of @dfn{shadowed} Emacs Lisp files.  A
shadowed file is one that will not normally be loaded, despite being
in a directory on @code{load-path}, due to the existence of another
similarly-named file in a directory earlier on @code{load-path}.

For instance, suppose @code{load-path} is set to

362
@example
363
  ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
364
@end example
365 366 367 368 369 370 371 372 373 374 375 376 377

@noindent
and that both these directories contain a file named @file{foo.el}.
Then @code{(require 'foo)} never loads the file in the second
directory.  Such a situation might indicate a problem in the way Emacs
was installed.

When called from Lisp, this function prints a message listing the
shadowed files, instead of displaying them in a buffer.  If the
optional argument @code{stringp} is non-@code{nil}, it instead returns
the shadowed files as a string.
@end deffn

Glenn Morris's avatar
Glenn Morris committed
378 379 380 381 382 383 384 385 386 387 388 389 390 391
@node Loading Non-ASCII
@section Loading Non-@acronym{ASCII} Characters

  When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
characters, these can be represented within Emacs either as unibyte
strings or as multibyte strings (@pxref{Text Representations}).  Which
representation is used depends on how the file is read into Emacs.  If
it is read with decoding into multibyte representation, the text of the
Lisp program will be multibyte text, and its string constants will be
multibyte strings.  If a file containing Latin-1 characters (for
example) is read without decoding, the text of the program will be
unibyte text, and its string constants will be unibyte strings.
@xref{Coding Systems}.

392 393 394 395 396
  In most Emacs Lisp programs, the fact that non-@acronym{ASCII}
strings are multibyte strings should not be noticeable, since
inserting them in unibyte buffers converts them to unibyte
automatically.  However, if this does make a difference, you can force
a particular Lisp file to be interpreted as unibyte by writing
397
@samp{coding: raw-text} in a local variables section.  With
398
that designator, the file will unconditionally be interpreted as
399 400
unibyte.  This can matter when making keybindings to
non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
Glenn Morris's avatar
Glenn Morris committed
401 402 403 404 405

@node Autoload
@section Autoload
@cindex autoload

406 407 408
  The @dfn{autoload} facility lets you register the existence of a
function or macro, but put off loading the file that defines it.  The
first call to the function automatically loads the proper library, in
409 410
order to install the real definition and other associated code, then
runs the real definition as if it had been loaded all along.
411 412
Autoloading can also be triggered by looking up the documentation of
the function or macro (@pxref{Documentation Basics}).
Glenn Morris's avatar
Glenn Morris committed
413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429

  There are two ways to set up an autoloaded function: by calling
@code{autoload}, and by writing a special ``magic'' comment in the
source before the real definition.  @code{autoload} is the low-level
primitive for autoloading; any Lisp program can call @code{autoload} at
any time.  Magic comments are the most convenient way to make a function
autoload, for packages installed along with Emacs.  These comments do
nothing on their own, but they serve as a guide for the command
@code{update-file-autoloads}, which constructs calls to @code{autoload}
and arranges to execute them when Emacs is built.

@defun autoload function filename &optional docstring interactive type
This function defines the function (or macro) named @var{function} so as
to load automatically from @var{filename}.  The string @var{filename}
specifies the file to load to get the real definition of @var{function}.

If @var{filename} does not contain either a directory name, or the
430 431 432
suffix @code{.el} or @code{.elc}, this function insists on adding one
of these suffixes, and it will not load from a file whose name is just
@var{filename} with no added suffix.  (The variable
Glenn Morris's avatar
Glenn Morris committed
433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463
@code{load-suffixes} specifies the exact required suffixes.)

The argument @var{docstring} is the documentation string for the
function.  Specifying the documentation string in the call to
@code{autoload} makes it possible to look at the documentation without
loading the function's real definition.  Normally, this should be
identical to the documentation string in the function definition
itself.  If it isn't, the function definition's documentation string
takes effect when it is loaded.

If @var{interactive} is non-@code{nil}, that says @var{function} can be
called interactively.  This lets completion in @kbd{M-x} work without
loading @var{function}'s real definition.  The complete interactive
specification is not given here; it's not needed unless the user
actually calls @var{function}, and when that happens, it's time to load
the real definition.

You can autoload macros and keymaps as well as ordinary functions.
Specify @var{type} as @code{macro} if @var{function} is really a macro.
Specify @var{type} as @code{keymap} if @var{function} is really a
keymap.  Various parts of Emacs need to know this information without
loading the real definition.

An autoloaded keymap loads automatically during key lookup when a prefix
key's binding is the symbol @var{function}.  Autoloading does not occur
for other kinds of access to the keymap.  In particular, it does not
happen when a Lisp program gets the keymap from the value of a variable
and calls @code{define-key}; not even if the variable name is the same
symbol @var{function}.

@cindex function cell in autoload
464 465 466 467 468
if @var{function} already has non-void function definition that is not
an autoload object, this function does nothing and returns @code{nil}.
Otherwise, it constructs an autoload object (@pxref{Autoload Type}),
and stores it as the function definition for @var{function}.  The
autoload object has this form:
Glenn Morris's avatar
Glenn Morris committed
469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490

@example
(autoload @var{filename} @var{docstring} @var{interactive} @var{type})
@end example

For example,

@example
@group
(symbol-function 'run-prolog)
     @result{} (autoload "prolog" 169681 t nil)
@end group
@end example

@noindent
In this case, @code{"prolog"} is the name of the file to load, 169681
refers to the documentation string in the
@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
@code{t} means the function is interactive, and @code{nil} that it is
not a macro or a keymap.
@end defun

491 492 493 494 495 496 497 498 499 500
@defun autoloadp object
This function returns non-@code{nil} if @var{object} is an autoload
object.  For example, to check if @code{run-prolog} is defined as an
autoloaded function, evaluate

@smallexample
(autoloadp (symbol-function 'run-prolog))
@end smallexample
@end defun

Glenn Morris's avatar
Glenn Morris committed
501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525
@cindex autoload errors
  The autoloaded file usually contains other definitions and may require
or provide one or more features.  If the file is not completely loaded
(due to an error in the evaluation of its contents), any function
definitions or @code{provide} calls that occurred during the load are
undone.  This is to ensure that the next attempt to call any function
autoloading from this file will try again to load the file.  If not for
this, then some of the functions in the file might be defined by the
aborted load, but fail to work properly for the lack of certain
subroutines not loaded successfully because they come later in the file.

  If the autoloaded file fails to define the desired Lisp function or
macro, then an error is signaled with data @code{"Autoloading failed to
define function @var{function-name}"}.

@findex update-file-autoloads
@findex update-directory-autoloads
@cindex magic autoload comment
@cindex autoload cookie
@anchor{autoload cookie}
  A magic autoload comment (often called an @dfn{autoload cookie})
consists of @samp{;;;###autoload}, on a line by itself,
just before the real definition of the function in its
autoloadable source file.  The command @kbd{M-x update-file-autoloads}
writes a corresponding @code{autoload} call into @file{loaddefs.el}.
526 527 528
(The string that serves as the autoload cookie and the name of the
file generated by @code{update-file-autoloads} can be changed from the
above defaults, see below.)
Glenn Morris's avatar
Glenn Morris committed
529 530 531 532 533
Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
@kbd{M-x update-directory-autoloads} is even more powerful; it updates
autoloads for all files in the current directory.

  The same magic comment can copy any kind of form into
534 535 536 537 538 539 540 541
@file{loaddefs.el}.  The form following the magic comment is copied
verbatim, @emph{except} if it is one of the forms which the autoload
facility handles specially (e.g.@: by conversion into an
@code{autoload} call).  The forms which are not copied verbatim are
the following:

@table @asis
@item Definitions for function or function-like objects:
542 543 544
@code{defun} and @code{defmacro}; also @code{cl-defun} and
@code{cl-defmacro} (@pxref{Argument Lists,,,cl,Common Lisp Extensions}),
and @code{define-overloadable-function} (see the commentary in
545 546 547
@file{mode-local.el}).

@item Definitions for major or minor modes:
548
@code{define-minor-mode}, @code{define-globalized-minor-mode},
549 550
@code{define-generic-mode}, @code{define-derived-mode},
@code{easy-mmode-define-minor-mode},
551
@code{easy-mmode-define-global-mode}, @code{define-compilation-mode},
552
and @code{define-global-minor-mode}.
553 554 555 556 557 558

@item Other definition types:
@code{defcustom}, @code{defgroup}, @code{defclass}
(@pxref{Top,EIEIO,,eieio,EIEIO}), and @code{define-skeleton} (see the
commentary in @file{skeleton.el}).
@end table
Glenn Morris's avatar
Glenn Morris committed
559 560 561 562 563 564 565 566 567 568 569

  You can also use a magic comment to execute a form at build time
@emph{without} executing it when the file itself is loaded.  To do this,
write the form @emph{on the same line} as the magic comment.  Since it
is in a comment, it does nothing when you load the source file; but
@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
it is executed while building Emacs.

  The following example shows how @code{doctor} is prepared for
autoloading with a magic comment:

570
@example
Glenn Morris's avatar
Glenn Morris committed
571 572 573 574 575 576
;;;###autoload
(defun doctor ()
  "Switch to *doctor* buffer and start giving psychotherapy."
  (interactive)
  (switch-to-buffer "*doctor*")
  (doctor-mode))
577
@end example
Glenn Morris's avatar
Glenn Morris committed
578 579 580 581

@noindent
Here's what that produces in @file{loaddefs.el}:

582
@example
Glenn Morris's avatar
Glenn Morris committed
583 584 585 586
(autoload (quote doctor) "doctor" "\
Switch to *doctor* buffer and start giving psychotherapy.

\(fn)" t nil)
587
@end example
Glenn Morris's avatar
Glenn Morris committed
588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605

@noindent
@cindex @code{fn} in function's documentation string
The backslash and newline immediately following the double-quote are a
convention used only in the preloaded uncompiled Lisp files such as
@file{loaddefs.el}; they tell @code{make-docfile} to put the
documentation string in the @file{etc/DOC} file.  @xref{Building Emacs}.
See also the commentary in @file{lib-src/make-docfile.c}.  @samp{(fn)}
in the usage part of the documentation string is replaced with the
function's name when the various help functions (@pxref{Help
Functions}) display it.

  If you write a function definition with an unusual macro that is not
one of the known and recognized function definition methods, use of an
ordinary magic autoload comment would copy the whole definition into
@code{loaddefs.el}.  That is not desirable.  You can put the desired
@code{autoload} call into @code{loaddefs.el} instead by writing this:

606
@example
Glenn Morris's avatar
Glenn Morris committed
607 608 609
;;;###autoload (autoload 'foo "myfile")
(mydefunmacro foo
  ...)
610
@end example
Glenn Morris's avatar
Glenn Morris committed
611

612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631
  You can use a non-default string as the autoload cookie and have the
corresponding autoload calls written into a file whose name is
different from the default @file{loaddefs.el}.  Emacs provides two
variables to control this:

@defvar generate-autoload-cookie
The value of this variable should be a string whose syntax is a Lisp
comment.  @kbd{M-x update-file-autoloads} copies the Lisp form that
follows the cookie into the autoload file it generates.  The default
value of this variable is @code{";;;###autoload"}.
@end defvar

@defvar generated-autoload-file
The value of this variable names an Emacs Lisp file where the autoload
calls should go.  The default value is @file{loaddefs.el}, but you can
override that, e.g., in the ``Local Variables'' section of a
@file{.el} file (@pxref{File Local Variables}).  The autoload file is
assumed to contain a trailer starting with a formfeed character.
@end defvar

632 633 634 635 636
  The following function may be used to explicitly load the library
specified by an autoload object:

@defun autoload-do-load autoload &optional name macro-only
This function performs the loading specified by @var{autoload}, which
Paul Eggert's avatar
Paul Eggert committed
637
should be an autoload object.  The optional argument @var{name}, if
638 639 640 641 642 643 644
non-@code{nil}, should be a symbol whose function value is
@var{autoload}; in that case, the return value of this function is the
symbol's new function value.  If the value of the optional argument
@var{macro-only} is @code{macro}, this function avoids loading a
function, only a macro.
@end defun

Glenn Morris's avatar
Glenn Morris committed
645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675
@node Repeated Loading
@section Repeated Loading
@cindex repeated loading

  You can load a given file more than once in an Emacs session.  For
example, after you have rewritten and reinstalled a function definition
by editing it in a buffer, you may wish to return to the original
version; you can do this by reloading the file it came from.

  When you load or reload files, bear in mind that the @code{load} and
@code{load-library} functions automatically load a byte-compiled file
rather than a non-compiled file of similar name.  If you rewrite a file
that you intend to save and reinstall, you need to byte-compile the new
version; otherwise Emacs will load the older, byte-compiled file instead
of your newer, non-compiled file!  If that happens, the message
displayed when loading the file includes, @samp{(compiled; note, source is
newer)}, to remind you to recompile it.

  When writing the forms in a Lisp library file, keep in mind that the
file might be loaded more than once.  For example, think about whether
each variable should be reinitialized when you reload the library;
@code{defvar} does not change the value if the variable is already
initialized.  (@xref{Defining Variables}.)

  The simplest way to add an element to an alist is like this:

@example
(push '(leif-mode " Leif") minor-mode-alist)
@end example

@noindent
676 677
But this would add multiple elements if the library is reloaded.  To
avoid the problem, use @code{add-to-list} (@pxref{List Variables}):
Glenn Morris's avatar
Glenn Morris committed
678 679

@example
Glenn Morris's avatar
Glenn Morris committed
680
(add-to-list 'minor-mode-alist '(leif-mode " Leif"))
Glenn Morris's avatar
Glenn Morris committed
681 682 683
@end example

  Occasionally you will want to test explicitly whether a library has
684 685 686 687
already been loaded.  If the library uses @code{provide} to provide a
named feature, you can use @code{featurep} earlier in the file to test
whether the @code{provide} call has been executed before (@pxref{Named
Features}).  Alternatively, you could use something like this:
Glenn Morris's avatar
Glenn Morris committed
688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716

@example
(defvar foo-was-loaded nil)

(unless foo-was-loaded
  @var{execute-first-time-only}
  (setq foo-was-loaded t))
@end example

@noindent

@node Named Features
@section Features
@cindex features
@cindex requiring features
@cindex providing features

  @code{provide} and @code{require} are an alternative to
@code{autoload} for loading files automatically.  They work in terms of
named @dfn{features}.  Autoloading is triggered by calling a specific
function, but a feature is loaded the first time another program asks
for it by name.

  A feature name is a symbol that stands for a collection of functions,
variables, etc.  The file that defines them should @dfn{provide} the
feature.  Another program that uses them may ensure they are defined by
@dfn{requiring} the feature.  This loads the file of definitions if it
hasn't been loaded already.

717
@cindex load error with require
Glenn Morris's avatar
Glenn Morris committed
718 719 720 721 722 723 724
  To require the presence of a feature, call @code{require} with the
feature name as argument.  @code{require} looks in the global variable
@code{features} to see whether the desired feature has been provided
already.  If not, it loads the feature from the appropriate file.  This
file should call @code{provide} at the top level to add the feature to
@code{features}; if it fails to do so, @code{require} signals an error.

725 726
  For example, in @file{idlwave.el}, the definition for
@code{idlwave-complete-filename} includes the following code:
Glenn Morris's avatar
Glenn Morris committed
727

728
@example
729 730 731
(defun idlwave-complete-filename ()
  "Use the comint stuff to complete a file name."
   (require 'comint)
732
   (let* ((comint-file-name-chars "~/A-Za-z0-9+@@:_.$#%=@{@}\\-")
733 734 735
          (comint-completion-addsuffix nil)
          ...)
       (comint-dynamic-complete-filename)))
736
@end example
Glenn Morris's avatar
Glenn Morris committed
737 738 739

@noindent
The expression @code{(require 'comint)} loads the file @file{comint.el}
740 741 742 743 744 745 746 747
if it has not yet been loaded, ensuring that
@code{comint-dynamic-complete-filename} is defined.  Features are
normally named after the files that provide them, so that
@code{require} need not be given the file name.  (Note that it is
important that the @code{require} statement be outside the body of the
@code{let}.  Loading a library while its variables are let-bound can
have unintended consequences, namely the variables becoming unbound
after the let exits.)
Glenn Morris's avatar
Glenn Morris committed
748 749 750

The @file{comint.el} file contains the following top-level expression:

751
@example
Glenn Morris's avatar
Glenn Morris committed
752
(provide 'comint)
753
@end example
Glenn Morris's avatar
Glenn Morris committed
754 755 756 757 758 759 760 761 762 763

@noindent
This adds @code{comint} to the global @code{features} list, so that
@code{(require 'comint)} will henceforth know that nothing needs to be
done.

@cindex byte-compiling @code{require}
  When @code{require} is used at top level in a file, it takes effect
when you byte-compile that file (@pxref{Byte Compilation}) as well as
when you load it.  This is in case the required package contains macros
764
that the byte compiler must know about.  It also avoids byte compiler
Glenn Morris's avatar
Glenn Morris committed
765 766 767 768 769 770 771 772 773
warnings for functions and variables defined in the file loaded with
@code{require}.

  Although top-level calls to @code{require} are evaluated during
byte compilation, @code{provide} calls are not.  Therefore, you can
ensure that a file of definitions is loaded before it is byte-compiled
by including a @code{provide} followed by a @code{require} for the same
feature, as in the following example.

774
@example
Glenn Morris's avatar
Glenn Morris committed
775 776 777 778 779
@group
(provide 'my-feature)  ; @r{Ignored by byte compiler,}
                       ;   @r{evaluated by @code{load}.}
(require 'my-feature)  ; @r{Evaluated by byte compiler.}
@end group
780
@end example
Glenn Morris's avatar
Glenn Morris committed
781 782 783 784 785 786 787 788 789 790 791 792 793

@noindent
The compiler ignores the @code{provide}, then processes the
@code{require} by loading the file in question.  Loading the file does
execute the @code{provide} call, so the subsequent @code{require} call
does nothing when the file is loaded.

@defun provide feature &optional subfeatures
This function announces that @var{feature} is now loaded, or being
loaded, into the current Emacs session.  This means that the facilities
associated with @var{feature} are or will be available for other Lisp
programs.

794 795 796 797 798
The direct effect of calling @code{provide} is if not already in
@var{features} then to add @var{feature} to the front of that list and
call any @code{eval-after-load} code waiting for it (@pxref{Hooks for
Loading}).  The argument @var{feature} must be a symbol.
@code{provide} returns @var{feature}.
Glenn Morris's avatar
Glenn Morris committed
799 800 801 802 803 804 805 806 807 808 809

If provided, @var{subfeatures} should be a list of symbols indicating
a set of specific subfeatures provided by this version of
@var{feature}.  You can test the presence of a subfeature using
@code{featurep}.  The idea of subfeatures is that you use them when a
package (which is one @var{feature}) is complex enough to make it
useful to give names to various parts or functionalities of the
package, which might or might not be loaded, or might or might not be
present in a given version.  @xref{Network Feature Testing}, for
an example.

810
@example
Glenn Morris's avatar
Glenn Morris committed
811 812 813 814 815 816 817
features
     @result{} (bar bish)

(provide 'foo)
     @result{} foo
features
     @result{} (foo bar bish)
818
@end example
Glenn Morris's avatar
Glenn Morris committed
819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870

When a file is loaded to satisfy an autoload, and it stops due to an
error in the evaluation of its contents, any function definitions or
@code{provide} calls that occurred during the load are undone.
@xref{Autoload}.
@end defun

@defun require feature &optional filename noerror
This function checks whether @var{feature} is present in the current
Emacs session (using @code{(featurep @var{feature})}; see below).  The
argument @var{feature} must be a symbol.

If the feature is not present, then @code{require} loads @var{filename}
with @code{load}.  If @var{filename} is not supplied, then the name of
the symbol @var{feature} is used as the base file name to load.
However, in this case, @code{require} insists on finding @var{feature}
with an added @samp{.el} or @samp{.elc} suffix (possibly extended with
a compression suffix); a file whose name is just @var{feature} won't
be used.  (The variable @code{load-suffixes} specifies the exact
required Lisp suffixes.)

If @var{noerror} is non-@code{nil}, that suppresses errors from actual
loading of the file.  In that case, @code{require} returns @code{nil}
if loading the file fails.  Normally, @code{require} returns
@var{feature}.

If loading the file succeeds but does not provide @var{feature},
@code{require} signals an error, @samp{Required feature @var{feature}
was not provided}.
@end defun

@defun featurep feature &optional subfeature
This function returns @code{t} if @var{feature} has been provided in
the current Emacs session (i.e.@:, if @var{feature} is a member of
@code{features}.)  If @var{subfeature} is non-@code{nil}, then the
function returns @code{t} only if that subfeature is provided as well
(i.e.@: if @var{subfeature} is a member of the @code{subfeature}
property of the @var{feature} symbol.)
@end defun

@defvar features
The value of this variable is a list of symbols that are the features
loaded in the current Emacs session.  Each symbol was put in this list
with a call to @code{provide}.  The order of the elements in the
@code{features} list is not significant.
@end defvar

@node Where Defined
@section Which File Defined a Certain Symbol

@defun symbol-file symbol &optional type
This function returns the name of the file that defined @var{symbol}.
871 872 873 874 875 876 877 878 879
If @var{type} is @code{nil}, then any kind of definition is acceptable.
If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that
specifies function definition, variable definition, or face definition
only.

The value is normally an absolute file name.  It can also be @code{nil},
if the definition is not associated with any file.  If @var{symbol}
specifies an autoloaded function, the value can be a relative file name
without extension.
Glenn Morris's avatar
Glenn Morris committed
880 881 882 883 884 885
@end defun

  The basis for @code{symbol-file} is the data in the variable
@code{load-history}.

@defvar load-history
886
The value of this variable is an alist that associates the names of
887 888 889 890 891 892 893
loaded library files with the names of the functions and variables
they defined, as well as the features they provided or required.

Each element in this alist describes one loaded library (including
libraries that are preloaded at startup).  It is a list whose @sc{car}
is the absolute file name of the library (a string).  The rest of the
list elements have these forms:
Glenn Morris's avatar
Glenn Morris committed
894 895 896 897 898 899 900 901 902 903 904 905 906

@table @code
@item @var{var}
The symbol @var{var} was defined as a variable.
@item (defun . @var{fun})
The function @var{fun} was defined.
@item (t . @var{fun})
The function @var{fun} was previously an autoload before this library
redefined it as a function.  The following element is always
@code{(defun . @var{fun})}, which represents defining @var{fun} as a
function.
@item (autoload . @var{fun})
The function @var{fun} was defined as an autoload.
907 908
@item (defface . @var{face})
The face @var{face} was defined.
Glenn Morris's avatar
Glenn Morris committed
909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942
@item (require . @var{feature})
The feature @var{feature} was required.
@item (provide . @var{feature})
The feature @var{feature} was provided.
@end table

The value of @code{load-history} may have one element whose @sc{car} is
@code{nil}.  This element describes definitions made with
@code{eval-buffer} on a buffer that is not visiting a file.
@end defvar

  The command @code{eval-region} updates @code{load-history}, but does so
by adding the symbols defined to the element for the file being visited,
rather than replacing that element.  @xref{Eval}.

@node Unloading
@section Unloading
@cindex unloading packages

@c Emacs 19 feature
  You can discard the functions and variables loaded by a library to
reclaim memory for other Lisp objects.  To do this, use the function
@code{unload-feature}:

@deffn Command unload-feature feature &optional force
This command unloads the library that provided feature @var{feature}.
It undefines all functions, macros, and variables defined in that
library with @code{defun}, @code{defalias}, @code{defsubst},
@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
It then restores any autoloads formerly associated with those symbols.
(Loading saves these in the @code{autoload} property of the symbol.)

Before restoring the previous definitions, @code{unload-feature} runs
@code{remove-hook} to remove functions in the library from certain
Stefan Monnier's avatar
Stefan Monnier committed
943 944
hooks.  These hooks include variables whose names end in @samp{-hook}
(or the deprecated suffix @samp{-hooks}), plus those listed in
945 946 947 948
@code{unload-feature-special-hooks}, as well as
@code{auto-mode-alist}.  This is to prevent Emacs from ceasing to
function because important hooks refer to functions that are no longer
defined.
Glenn Morris's avatar
Glenn Morris committed
949

950 951 952 953 954
Standard unloading activities also undoes ELP profiling of functions
in that library, unprovides any features provided by the library, and
cancels timers held in variables defined by the library.

@vindex @var{feature}-unload-function
Glenn Morris's avatar
Glenn Morris committed
955
If these measures are not sufficient to prevent malfunction, a library
956 957 958 959 960 961
can define an explicit unloader named @code{@var{feature}-unload-function}.
If that symbol is defined as a function, @code{unload-feature} calls
it with no arguments before doing anything else.  It can do whatever
is appropriate to unload the library.  If it returns @code{nil},
@code{unload-feature} proceeds to take the normal unload actions.
Otherwise it considers the job to be done.
Glenn Morris's avatar
Glenn Morris committed
962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982

Ordinarily, @code{unload-feature} refuses to unload a library on which
other loaded libraries depend.  (A library @var{a} depends on library
@var{b} if @var{a} contains a @code{require} for @var{b}.)  If the
optional argument @var{force} is non-@code{nil}, dependencies are
ignored and you can unload any library.
@end deffn

  The @code{unload-feature} function is written in Lisp; its actions are
based on the variable @code{load-history}.

@defvar unload-feature-special-hooks
This variable holds a list of hooks to be scanned before unloading a
library, to remove functions defined in the library.
@end defvar

@node Hooks for Loading
@section Hooks for Loading
@cindex loading hooks
@cindex hooks for loading

983 984 985 986 987 988 989 990 991 992 993
You can ask for code to be executed each time Emacs loads a library,
by using the variable @code{after-load-functions}:

@defvar after-load-functions
This abnormal hook is run after loading a file.  Each function in the
hook is called with a single argument, the absolute filename of the
file that was just loaded.
@end defvar

If you want code to be executed when a @emph{particular} library is
loaded, use the function @code{eval-after-load}:
Glenn Morris's avatar
Glenn Morris committed
994 995 996 997 998 999 1000 1001

@defun eval-after-load library form
This function arranges to evaluate @var{form} at the end of loading
the file @var{library}, each time @var{library} is loaded.  If
@var{library} is already loaded, it evaluates @var{form} right away.
Don't forget to quote @var{form}!

You don't need to give a directory or extension in the file name
1002
@var{library}.  Normally, you just give a bare file name, like this:
Glenn Morris's avatar
Glenn Morris committed
1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020

@example
(eval-after-load "edebug" '(def-edebug-spec c-point t))
@end example

To restrict which files can trigger the evaluation, include a
directory or an extension or both in @var{library}.  Only a file whose
absolute true name (i.e., the name with all symbolic links chased out)
matches all the given name components will match.  In the following
example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory
@code{..../foo/bar} will trigger the evaluation, but not
@file{my_inst.el}:

@example
(eval-after-load "foo/bar/my_inst.elc" @dots{})
@end example

@var{library} can also be a feature (i.e.@: a symbol), in which case
1021 1022
@var{form} is evaluated at the end of any file where
@code{(provide @var{library})} is called.
Glenn Morris's avatar
Glenn Morris committed
1023 1024 1025 1026 1027

An error in @var{form} does not undo the load, but does prevent
execution of the rest of @var{form}.
@end defun

1028 1029 1030 1031 1032 1033
Normally, well-designed Lisp programs should not use
@code{eval-after-load}.  If you need to examine and set the variables
defined in another library (those meant for outside use), you can do
it immediately---there is no need to wait until the library is loaded.
If you need to call functions defined by that library, you should load
the library, preferably with @code{require} (@pxref{Named Features}).
Glenn Morris's avatar
Glenn Morris committed
1034 1035

@defvar after-load-alist
1036 1037 1038
This variable stores an alist built by @code{eval-after-load},
containing the expressions to evaluate when certain libraries are
loaded.  Each element looks like this:
Glenn Morris's avatar
Glenn Morris committed
1039 1040 1041 1042 1043 1044

@example
(@var{regexp-or-feature} @var{forms}@dots{})
@end example

The key @var{regexp-or-feature} is either a regular expression or a
1045 1046 1047
symbol, and the value is a list of forms.  The forms are evaluated
when the key matches the absolute true name or feature name of the
library being loaded.
Glenn Morris's avatar
Glenn Morris committed
1048
@end defvar