unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
blob 54fc16ec9f053cbc513c1b8d9db8109cefc46ed0 56043 bytes (raw)
name: doc/lispref/loading.texi 	 # note: path name is non-authoritative(*)

   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
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
 
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990--1995, 1998--1999, 2001--2022 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Loading
@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.  Such a file is also called a @dfn{Lisp library}.

  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.

  Emacs can also load compiled dynamic modules: shared libraries that
provide additional functionality for use in Emacs Lisp programs, just
like a package written in Emacs Lisp would.  When a dynamic module is
loaded, Emacs calls a specially-named initialization function which
the module needs to implement, and which exposes the additional
functions and variables to Emacs Lisp programs.

For on-demand loading of external libraries which are known in advance
to be required by certain Emacs primitives, @pxref{Dynamic Libraries}.

@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.
* Dynamic Modules::         Modules provide additional Lisp primitives.
@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, and Emacs was compiled with native-compilation support
(@pxref{Native Compilation}), @code{load} attempts to find a
corresponding @samp{.eln} file, and if found, loads it instead of
@file{@var{filename}.elc}.  Otherwise, it loads
@file{@var{filename}.elc}.  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.  If Emacs was compiled with support for
dynamic modules (@pxref{Dynamic Modules}), @code{load} next looks for
a file named @file{@var{filename}.@var{ext}}, where @var{ext} is a
system-dependent file-name extension of shared libraries.  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 file names like @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) or the shared-library extension, unless it contains an
explicit directory name.

If the option @code{load-prefer-newer} is non-@code{nil}, then when
searching suffixes, @code{load} selects whichever version of a file
(@samp{.elc}, @samp{.el}, etc.)@: has been modified most recently.
In this case, @code{load} doesn't load the @samp{.eln}
natively-compiled file even if it exists.

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

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.

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

@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.  Emacs will issue an error about
(@samp{Eager macro-expansion skipped due to cycle@dots{}})
giving details of the problem.  You have 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}.

Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
in the echo area during loading unless @var{nomessage} is
non-@code{nil}.  If a natively-compiled @samp{.eln} file is loaded,
the message says so.

@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 a
@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 for the way it reads its argument interactively.
@xref{Lisp Libraries,,,emacs, The GNU Emacs Manual}.
@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-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

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

By default, this variable's value is @code{read}.  @xref{Input
Functions}.

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.

@defopt load-prefer-newer
If this option is non-@code{nil}, then rather than stopping at the
first suffix that exists, @code{load} tests them all, and uses
whichever file is the newest.
@end defopt

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

@defvar load-path
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) or @code{nil} (which stands for the current working
directory).
@end defvar

  When Emacs starts up, it sets up the value of @code{load-path} in
several steps.  First, it looks for the directory containing its own
Lisp files, using default locations set when Emacs was compiled.  It
saves this directory in @code{lisp-directory}.  Normally, this is a
directory where the @file{*.elc} files are installed, something like

@example
"/usr/local/share/emacs/@var{version}/lisp"
@end example

@noindent
where @var{version} is the Emacs version.  (In this and the following
examples, replace @file{/usr/local} with the prefix appropriate for
your Emacs installation.)  This directory and its subdirectories
contain the standard Lisp files that come with Emacs.  If Emacs cannot
find its own Lisp files, it will not start correctly.

If you run Emacs from the directory where it was built---that is, an
executable that has not been installed yet---Emacs instead initializes
@code{lisp-directory} using the @file{lisp} subdirectory of the
directory containing the sources from which it was built.

Emacs then initializes @code{load-path} with this @code{lisp-directory}.
@c Though there should be no *.el files in builddir/lisp, so it's pointless.
If you built Emacs in a separate directory from the
sources, it also adds the @file{lisp} subdirectory of the build directory.

All of these directories are stored in the above two variables as
absolute file names.

@cindex site-lisp directories
Unless you start Emacs with the @option{--no-site-lisp} option,
it then adds two more @file{site-lisp} directories to the front of
@code{load-path}.  These are intended for locally installed Lisp files,
and are normally of the form:

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

@noindent
and

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

@noindent
The first one is for locally installed files for the current Emacs
@var{version}; the second is for locally installed files meant for use
with any installed Emacs version.  (If Emacs is running uninstalled,
it also adds @file{site-lisp} subdirectories from the source and build
directories, if they exist.  However, normally the source and build
directories do not contain @file{site-lisp} subdirectories.)

@cindex @env{EMACSLOADPATH} environment variable
If the environment variable @env{EMACSLOADPATH} is set, it modifies
the above initialization procedure.  Emacs initializes
@code{load-path} based on the value of the environment variable.

The syntax of @env{EMACSLOADPATH} is the same as used for @env{PATH};
directories are separated by @samp{:} (or @samp{;}, on some
operating systems).
@ignore
@c AFAICS, does not (yet) work right to specify non-absolute elements.
and @samp{.} stands for the current default directory.
@end ignore
Here is an example of how to set @env{EMACSLOADPATH} variable (from a
@command{sh}-style shell):

@example
export EMACSLOADPATH=/home/foo/.emacs.d/lisp:
@end example

An empty element in the value of the environment variable, whether
trailing (as in the above example, note the trailing @samp{:}),
leading, or embedded, is replaced by the default value of
@code{load-path} as determined by the standard initialization
procedure.  If there are no such empty elements, then
@env{EMACSLOADPATH} specifies the entire @code{load-path}.  You must
include either an empty element, or the explicit path to the directory
containing the standard Lisp files, else Emacs will not function.
(Another way to modify @code{load-path} is to use the @option{-L}
command-line option when starting Emacs; see below.)

  For each directory in @code{load-path}, Emacs then checks to see if
it contains a file @file{subdirs.el}, and if so, loads it.  The
@file{subdirs.el} file is created when Emacs is built/installed,
and contains code that causes Emacs to add any subdirectories of those
directories to @code{load-path}.  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 directories that you specify using the
@option{-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:

@example
(push "~/.emacs.d/lisp" load-path)
@end example

@noindent
@xref{List Variables, push}, for the description of @code{push}.

  Dumping Emacs uses a special value of @code{load-path}.  If you use
a @file{site-load.el} or @file{site-init.el} file to customize the
dumped Emacs (@pxref{Building Emacs}), any changes to @code{load-path}
that these files make will be lost after dumping.

@defvar lisp-directory
This variable holds a string naming the directory which holds
Emacs's own @file{*.el} and @file{*.elc} files.  This is usually the
place where those files are located in the Emacs installation tree,
unless Emacs is run from its build directory in which case it points
to the @file{lisp} subdirectory in the source directory from which
Emacs was built.
@end defvar

@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

@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

@example
  ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
@end example

@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

  If Emacs was compiled with support for native compilation
(@pxref{Native Compilation}), then when a @samp{.elc} byte-compiled
file is found by searching @code{load-path}, Emacs will try to look
for a corresponding @samp{.eln} file holding the corresponding
natively-compiled code.  The natively-compiled files are looked up in
the directories listed by the @code{native-comp-eln-load-path}.

@vindex comp-native-version-dir
@defvar native-comp-eln-load-path
This variable holds a list of directories where Emacs looks for
natively-compiled @samp{.eln} files.  File names in the list that are
not absolute are interpreted as relative to @code{invocation-directory}
(@pxref{System Environment}).  The last directory in the list is the
system directory, i.e.@: the directory with @samp{.eln} files
installed by the Emacs build and installation procedure.  In each of
the directories in the list, Emacs looks for @samp{.eln} files in a
subdirectory whose name is constructed from the Emacs version and an
8-character hash that depends on the current native-compilation
@acronym{ABI}; the name of this subdirectory is stored in the variable
@code{comp-native-version-dir}.
@end defvar

@node Loading Non-ASCII
@section Loading Non-@acronym{ASCII} Characters
@cindex loading, and non-ASCII characters
@cindex non-ASCII characters in loaded files

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

  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{coding: raw-text} in a local variables section.  With
that designator, the file will unconditionally be interpreted as
unibyte.  This can matter when making key bindings to
non-@acronym{ASCII} characters written as @code{?v@var{literal}}.

@node Autoload
@section Autoload
@cindex autoload

  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
order to install the real definition and other associated code, then
runs the real definition as if it had been loaded all along.
Autoloading can also be triggered by looking up the documentation of
the function or macro (@pxref{Documentation Basics}), and completion
of variable and function names (@pxref{Autoload by Prefix} below).

@menu
* Autoload by Prefix:: Autoload by Prefix.
* When to Autoload::   When to Use Autoload.
@end menu

  There are two ways to set up an autoloaded function: by calling
@code{autoload}, and by writing a ``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{loaddefs-generate}, 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}, 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
@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.

If @var{interactive} is a list, it is interpreted as a list of modes
this command is applicable for.

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{keymap-set}; 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, 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:

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

@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

@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 loaddefs-generate
@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 function @code{loaddefs-generate}
writes a corresponding @code{autoload} call into @file{loaddefs.el}.
(The string that serves as the autoload cookie and the name of the
file generated by @code{loaddefs-generate} can be changed from the
above defaults, see below.)
Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.

  The same magic comment can copy any kind of form into
@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:
@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
@file{mode-local.el}).

@item Definitions for major or minor modes:
@code{define-minor-mode}, @code{define-globalized-minor-mode},
@code{define-generic-mode}, @code{define-derived-mode},
@code{easy-mmode-define-minor-mode},
@code{easy-mmode-define-global-mode}, @code{define-compilation-mode},
and @code{define-global-minor-mode}.

@item Other definition types:
@code{defcustom}, @code{defgroup}, @code{defclass}
(@pxref{Top,EIEIO,,eieio,EIEIO}), and @code{define-skeleton}
(@pxref{Top,Autotyping,,autotype,Autotyping}).
@end table

  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
@code{loaddefs-generate} 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:

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

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

@example
(autoload 'doctor "doctor" "\
Switch to *doctor* buffer and start giving psychotherapy.

\(fn)" t nil)
@end example

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

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

  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 lisp-mode-autoload-regexp
The value of this constant is a regexp that matches autoload cookies.
@code{loaddefs-generate} copies the Lisp form that follows the
cookie into the autoload file it generates.  This will match comments
like @samp{;;;###autoload} and @samp{;;;###calc-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

  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
should be an autoload object.  The optional argument @var{name}, if
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

@node Autoload by Prefix
@subsection Autoload by Prefix
@cindex autoload by prefix

@vindex definition-prefixes
@findex register-definition-prefixes
@vindex autoload-compute-prefixes
During completion for the commands @code{describe-variable} and
@code{describe-function}, Emacs will try to load files which may
contain definitions matching the prefix being completed.  The variable
@code{definition-prefixes} holds a hashtable which maps a prefix to
the corresponding list of files to load for it.  Entries to this
mapping are added by calls to @code{register-definition-prefixes}
which are generated by @code{loaddefs-generate}
(@pxref{Autoload}).  Files which don't contain any definitions worth
loading (test files, for examples), should set
@code{autoload-compute-prefixes} to @code{nil} as a file-local
variable.

@node When to Autoload
@subsection When to Use Autoload
@cindex autoload, when to use

Do not add an autoload comment unless it is really necessary.
Autoloading code means it is always globally visible.  Once an item is
autoloaded, there is no compatible way to transition back to it not
being autoloaded (after people become accustomed to being able to use it
without an explicit load).

@itemize
@item
The most common items to autoload are the interactive entry points to a
library.  For example, if @file{python.el} is a library defining a
major-mode for editing Python code, autoload the definition of the
@code{python-mode} function, so that people can simply use @kbd{M-x
python-mode} to load the library.

@item
Variables usually don't need to be autoloaded.  An exception is if the
variable on its own is generally useful without the whole defining
library being loaded.  (An example of this might be something like
@code{find-exec-terminator}.)

@item
Don't autoload a user option just so that a user can set it.

@item
Never add an autoload @emph{comment} to silence a compiler warning in
another file.  In the file that produces the warning, use
@code{(defvar foo)} to silence an undefined variable warning, and
@code{declare-function} (@pxref{Declaring Functions}) to silence an
undefined function warning; or require the relevant library; or use an
explicit autoload @emph{statement}.
@end itemize

@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, use @code{add-to-list} (@pxref{List Variables}):

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

  Occasionally you will want to test explicitly whether a library has
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:

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

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

  For example, in @file{idlwave.el}, the definition for
@code{idlwave-complete-filename} includes the following code:

@example
(defun idlwave-complete-filename ()
  "Use the comint stuff to complete a file name."
   (require 'comint)
   (let* ((comint-file-name-chars "~/A-Za-z0-9+@@:_.$#%=@{@}\\-")
          (comint-completion-addsuffix nil)
          ...)
       (comint-dynamic-complete-filename)))
@end example

@noindent
The expression @code{(require 'comint)} loads the file @file{comint.el}
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.)

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

@example
(provide 'comint)
@end example

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

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

@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 @code{features} if it is not already in 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}.

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.

@example
features
     @result{} (bar bish)

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

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 about the missing feature.
@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
@cindex symbol, where defined
@cindex where was a symbol defined

@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}, @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.
@end defun

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

@defvar load-history
The value of this variable is an alist that associates the names of
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:

@table @code
@item @var{var}
The symbol @var{var} was defined as a variable.
@item (defun . @var{fun})
The function @var{fun} was defined.
@code{(defun . @var{fun})}, which represents defining @var{fun} as a
function.
@item (defface . @var{face})
The face @var{face} was defined.
@item (require . @var{feature})
The feature @var{feature} was required.
@item (provide . @var{feature})
The feature @var{feature} was provided.
@item (cl-defmethod @var{method} @var{specializers})
The named @var{method} was defined by using @code{cl-defmethod}, with
@var{specializers} as its specializers.
@item (define-type . @var{type})
The type @var{type} was defined.
@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}.

@kindex function-history @r{(function symbol property)}
In addition to @code{load-history}, every function keeps track of its
own history in the symbol property @code{function-history}.
The reason why functions are treated specially in this respect is that
it is common for functions to be defined in two steps in two different
files (typically, one of them is an autoload), so in order to be
able to properly @emph{unload} a file, we need to know more precisely
what that file did to the function definition.

The symbol property @code{function-history} holds a list of the form
@w{@code{(@var{file1} @var{def2} @var{file2} @var{def3} ...)}}, where
@var{file1} is the last file that changed the definition and
@var{def2} was the definition before @var{file1}, set by @var{file2},
etc.  Logically this list should end with the name of the first file
that defined this function, but to save space this last element
is usually omitted.

@node Unloading
@section Unloading
@cindex unloading packages

  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{function-history} property of the symbol.)

Before restoring the previous definitions, @code{unload-feature} runs
@code{remove-hook} to remove functions defined by the library from certain
hooks.  These hooks include variables whose names end in @samp{-hook}
(or the deprecated suffix @samp{-hooks}), plus those listed in
@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.

Standard unloading activities also undo 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
If these measures are not sufficient to prevent malfunction, a library
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.

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 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 macro @code{with-eval-after-load}:

@defmac with-eval-after-load library body@dots{}
This macro arranges to evaluate @var{body} at the end of loading
the file @var{library}, each time @var{library} is loaded.  If
@var{library} is already loaded, it evaluates @var{body} right away.

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
(with-eval-after-load "js" (keymap-set js-mode-map "C-c C-c" 'js-eval))
@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
(with-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{body} is evaluated at the end of any file where
@code{(provide @var{library})} is called.

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

Normally, well-designed Lisp programs should not use
@code{with-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}).

@node Dynamic Modules
@section Emacs Dynamic Modules
@cindex dynamic modules

  A @dfn{dynamic Emacs module} is a shared library that provides
additional functionality for use in Emacs Lisp programs, just like a
package written in Emacs Lisp would.

  Functions that load Emacs Lisp packages can also load dynamic
modules.  They recognize dynamic modules by looking at their file-name
extension, a.k.a.@: ``suffix''.  This suffix is platform-dependent.

@defvar module-file-suffix
This variable holds the system-dependent value of the file-name
extension of the module files.  Its value is @file{.so} on POSIX
hosts, @file{.dylib} on macOS, and @file{.dll} on MS-Windows.
@end defvar

  On macOS, dynamic modules can also have the suffix @file{.so} in
addition to @file{.dylib}.

@findex emacs_module_init
@vindex plugin_is_GPL_compatible
Every dynamic module should export a C-callable function named
@code{emacs_module_init}, which Emacs will call as part of the call to
@code{load} or @code{require} which loads the module.  It should also
export a symbol named @code{plugin_is_GPL_compatible} to indicate that
its code is released under the GPL or compatible license; Emacs will
signal an error if your program tries to load modules that don't
export such a symbol.

If a module needs to call Emacs functions, it should do so through the
@acronym{API} (Application Programming Interface) defined and
documented in the header file @file{emacs-module.h} that is part of
the Emacs distribution.  @xref{Writing Dynamic Modules}, for details
of using that API when writing your own modules.

@cindex user-ptr object
@cindex user pointer object
Modules can create @code{user-ptr} Lisp objects that embed pointers to
C struct's defined by the module.  This is useful for keeping around
complex data structures created by a module, to be passed back to the
module's functions.  User-ptr objects can also have associated
@dfn{finalizers} -- functions to be run when the object is GC'ed; this
is useful for freeing any resources allocated for the underlying data
structure, such as memory, open file descriptors, etc.  @xref{Module
Values}.

@defun user-ptrp object
This function returns @code{t} if its argument is a @code{user-ptr}
object.
@end defun

@defun module-load file
Emacs calls this low-level primitive to load a module from the
specified @var{file} and perform the necessary initialization of the
module.  This is the primitive which makes sure the module exports the
@code{plugin_is_GPL_compatible} symbol, calls the module's
@code{emacs_module_init} function, and signals an error if that
function returns an error indication, or if the use typed @kbd{C-g}
during the initialization.  If the initialization succeeds,
@code{module-load} returns @code{t}.  Note that @var{file} must
already have the proper file-name extension, as this function doesn't
try looking for files with known extensions, unlike @code{load}.

Unlike @code{load}, @code{module-load} doesn't record the module in
@code{load-history}, doesn't print any messages, and doesn't protect
against recursive loads.  Most users should therefore use @code{load},
@code{load-file}, @code{load-library}, or @code{require} instead of
@code{module-load}.
@end defun

Loadable modules in Emacs are enabled by using the
@kbd{--with-modules} option at configure time.

debug log:

solving 54fc16ec9f ...
found 54fc16ec9f in https://git.savannah.gnu.org/cgit/emacs.git

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).