Source

emacs / lispref / loading.texi

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 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
 41
 42
 43
 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
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
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
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
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
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
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
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
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
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
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
676
677
678
679
680
681
682
683
684
685
686
687
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
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
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
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
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
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/loading
@node Loading, Byte Compilation, Customization, Top
@chapter Loading
@cindex loading
@cindex library
@cindex Lisp library

  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.

  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.

  A file containing Lisp code is often called a @dfn{library}.  Thus,
the ``Rmail library'' is a file containing code for Rmail mode.
Similarly, a ``Lisp library directory'' is a directory of files
containing Lisp code.

@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.
* Unloading::		    How to "unload" a library that was loaded.
* Hooks for Loading::	    Providing code to be run when
			      particular libraries are loaded.
@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
@var{nosuffix}, you can prevent perverse file names such as
@file{foo.el.el} from being tried.

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}.

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}.

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
@code{load}, except in how it reads its argument interactively.
@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

@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}.

@defopt load-path
@cindex @code{EMACSLOADPATH} environment variable
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).
@end defopt

  The value of @code{load-path} is initialized from the environment
variable @code{EMACSLOADPATH}, if that exists; otherwise its default
value is specified in @file{emacs/src/epaths.h} when Emacs is built.
Then the list is expanded by adding subdirectories of the directories
in the list.

  The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
@samp{:} (or @samp{;}, according to the operating system) separates
directory names, and @samp{.} is used for the current default directory.
Here is an example of how to set your @code{EMACSLOADPATH} variable from
a @code{csh} @file{.login} file:

@smallexample
setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
@end smallexample

  Here is how to set it using @code{sh}:

@smallexample
export EMACSLOADPATH
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
@end smallexample

  Here is an example of code you can place in your init file (@pxref{Init
File}) to add several directories to the front of your default
@code{load-path}:

@smallexample
@group
(setq load-path
      (append (list nil "/user/bil/emacs"
                    "/usr/local/lisplib"
                    "~/emacs")
              load-path))
@end group
@end smallexample

@c Wordy to rid us of an overfull hbox.  --rjc 15mar92
@noindent
In this example, the path searches the current working directory first,
followed then by the @file{/user/bil/emacs} directory, the
@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
which are then followed by the standard directories for Lisp code.

  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.

  Therefore, if you want to change @code{load-path} temporarily for
loading a few libraries in @file{site-init.el} or @file{site-load.el},
you should bind @code{load-path} locally with @code{let} around the
calls to @code{load}.

  The default value of @code{load-path}, when running an Emacs which has
been installed on the system, includes two special directories (and
their subdirectories as well):

@smallexample
"/usr/local/share/emacs/@var{version}/site-lisp"
@end smallexample

@noindent
and

@smallexample
"/usr/local/share/emacs/site-lisp"
@end smallexample

@noindent
The first one is for locally installed packages for a particular Emacs
version; the second is for locally installed packages meant for use with
all installed Emacs versions.

  There are several reasons why a Lisp package that works well in one
Emacs version can cause trouble in another.  Sometimes packages need
updating for incompatible changes in Emacs; sometimes they depend on
undocumented internal Emacs data that can change without notice;
sometimes a newer Emacs version incorporates a version of the package,
and should be used only with that version.

  Emacs finds these directories' subdirectories and adds them to
@code{load-path} when it starts up.  Both immediate subdirectories and
subdirectories multiple levels down are added to @code{load-path}.

  Not all subdirectories are included, though.  Subdirectories whose
names do not start with a letter or digit are excluded.  Subdirectories
named @file{RCS} or @file{CVS} are excluded.  Also, a subdirectory which
contains a file named @file{.nosearch} is excluded.  You can use these
methods to prevent certain subdirectories of the @file{site-lisp}
directories from being searched.

  If you run Emacs from the directory where it was built---that is, an
executable that has not been formally installed---then @code{load-path}
normally contains two additional directories.  These are the @code{lisp}
and @code{site-lisp} subdirectories of the main build directory.  (Both
are represented as absolute file names.)

@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

@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}.

  To make the results more predictable, Emacs always performs decoding
into the multibyte representation when loading Lisp files, even if it
was started with the @samp{--unibyte} option.  This means that string
constants with non-@acronym{ASCII} characters translate into multibyte
strings.  The only exception is when a particular file specifies no
decoding.

  The reason Emacs is designed this way is so that Lisp programs give
predictable results, regardless of how Emacs was started.  In addition,
this enables programs that depend on using multibyte text to work even
in a unibyte Emacs.  Of course, such programs should be designed to
notice whether the user prefers unibyte or multibyte text, by checking
@code{default-enable-multibyte-characters}, and convert representations
appropriately.

  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 @samp{-*-unibyte: t;-*-} in a
comment on the file's first line.  With that designator, the file will
unconditionally be interpreted as unibyte, even in an ordinary
multibyte Emacs session.  This can matter when making keybindings to
non-@acronym{ASCII} characters written as @code{?v@var{literal}}.

@node Autoload
@section Autoload
@cindex autoload

  The @dfn{autoload} facility allows you to make a function or macro
known in Lisp, but put off loading the file that defines it.  The first
call to the function automatically reads the proper file to install the
real definition and other associated code, then runs the real definition
as if it had been loaded all along.

  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
suffix @code{.el} or @code{.elc}, then @code{autoload} 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
@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
If @var{function} already has a non-void function definition that is not
an autoload object, @code{autoload} does nothing and returns @code{nil}.
If the function cell of @var{function} is void, or is already an autoload
object, then it is defined as an autoload object like this:

@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

@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}.
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
@file{loaddefs.el}.  If the form following the magic comment is not a
function-defining form or a @code{defcustom} form, it is copied
verbatim.  ``Function-defining forms'' include @code{define-skeleton},
@code{define-derived-mode}, @code{define-generic-mode} and
@code{define-minor-mode} as well as @code{defun} and
@code{defmacro}.  To save space, a @code{defcustom} form is converted to
a @code{defvar} in @file{loaddefs.el}, with some additional information
if it uses @code{:require}.

  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:

@smallexample
;;;###autoload
(defun doctor ()
  "Switch to *doctor* buffer and start giving psychotherapy."
  (interactive)
  (switch-to-buffer "*doctor*")
  (doctor-mode))
@end smallexample

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

@smallexample
(autoload (quote doctor) "doctor" "\
Switch to *doctor* buffer and start giving psychotherapy.

\(fn)" t nil)
@end smallexample

@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:

@smallexample
;;;###autoload (autoload 'foo "myfile")
(mydefunmacro foo
  ...)
@end smallexample

@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
But this would add multiple elements if the library is reloaded.
To avoid the problem, write this:

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

@noindent
or this:

@example
(add-to-list '(leif-mode " Leif") minor-mode-alist)
@end example

  Occasionally you will want to test explicitly whether a library has
already been loaded.  Here's one way to test, in a library, whether it
has been loaded before:

@example
(defvar foo-was-loaded nil)

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

@noindent
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.
@ifnottex
@xref{Named Features}.
@end ifnottex

@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.

  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.
@cindex load error with require

  For example, in @file{emacs/lisp/prolog.el},
the definition for @code{run-prolog} includes the following code:

@smallexample
(defun run-prolog ()
  "Run an inferior Prolog process, with I/O via buffer *prolog*."
  (interactive)
  (require 'comint)
  (switch-to-buffer (make-comint "prolog" prolog-program-name))
  (inferior-prolog-mode))
@end smallexample

@noindent
The expression @code{(require 'comint)} loads the file @file{comint.el}
if it has not yet been loaded.  This ensures that @code{make-comint} is
defined.  Features are normally named after the files that provide them,
so that @code{require} need not be given the file name.

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

@smallexample
(provide 'comint)
@end smallexample

@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
that the byte compiler must know about.  It also avoids byte-compiler
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.

@smallexample
@group
(provide 'my-feature)  ; @r{Ignored by byte compiler,}
                       ;   @r{evaluated by @code{load}.}
(require 'my-feature)  ; @r{Evaluated by byte compiler.}
@end group
@end smallexample

@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.

The direct effect of calling @code{provide} is to add @var{feature} to
the front of the list @code{features} if it is not already in the list.
The argument @var{feature} must be a symbol.  @code{provide} returns
@var{feature}.

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.

@smallexample
features
     @result{} (bar bish)

(provide 'foo)
     @result{} foo
features
     @result{} (foo bar bish)
@end smallexample

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}.
If @var{type} is @code{nil}, then any kind of definition is
acceptable.  If @var{type} is @code{defun} or @code{defvar}, that
specifies function definition only or variable 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.
@end defun

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

@defvar load-history
This variable's value is an alist connecting library file names with the
names of functions and variables they define, the features they provide,
and the features they require.

Each element is a list and describes one library.  The @sc{car} of the
list is the absolute file name of the library, as a string.  The rest
of the list elements have these forms:

@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.
@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.)

@vindex unload-feature-special-hooks
Before restoring the previous definitions, @code{unload-feature} runs
@code{remove-hook} to remove functions in the library from certain
hooks.  These hooks include variables whose names end in @samp{hook}
or @samp{-hooks}, plus those listed in
@code{unload-feature-special-hooks}.  This is to prevent Emacs from
ceasing to function because important hooks refer to functions that
are no longer defined.

@vindex @var{feature}-unload-hook
If these measures are not sufficient to prevent malfunction, a library
can define an explicit unload hook.  If @code{@var{feature}-unload-hook}
is defined, it is run as a normal hook before restoring the previous
definitions, @emph{instead of} the usual hook-removing actions.  The
unload hook ought to undo all the global state changes made by the
library that might cease to work once the library is unloaded.
@code{unload-feature} can cause problems with libraries that fail to do
this, so it should be used with caution.

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

You can ask for code to be executed if and when a particular library is
loaded, by calling @code{eval-after-load}.

@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
@var{library}---normally you just give a bare file name, like this:

@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
@var{form} is evaluated when @code{(provide @var{library})} is called.

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

In general, well-designed Lisp programs should not use this feature.
The clean and modular ways to interact with a Lisp library are (1)
examine and set the library's variables (those which are meant for
outside use), and (2) call the library's functions.  If you wish to
do (1), you can do it immediately---there is no need to wait for when
the library is loaded.  To do (2), you must load the library (preferably
with @code{require}).

But it is OK to use @code{eval-after-load} in your personal
customizations if you don't feel they must meet the design standards for
programs meant for wider use.

@defvar after-load-alist
This variable, an alist built by @code{eval-after-load}, holds the
expressions to evaluate when particular libraries are loaded.  Each
element looks like this:

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

The key @var{regexp-or-feature} is either a regular expression or a
symbol, and the value is a list of forms.  The forms are evaluated when
the key matches the absolute true name of the file being
@code{load}ed or the symbol being @code{provide}d.
@end defvar

@ignore
   arch-tag: df731f89-0900-4389-a436-9105241b6f7a
@end ignore