1@c -*-texinfo-*- 2@c This is part of the GNU Emacs Lisp Reference Manual. 3@c Copyright (C) 1990--1995, 1998--1999, 2001--2021 Free Software 4@c Foundation, Inc. 5@c See the file elisp.texi for copying conditions. 6@node Loading 7@chapter Loading 8@cindex loading 9@cindex library 10@cindex Lisp library 11 12 Loading a file of Lisp code means bringing its contents into the 13Lisp environment in the form of Lisp objects. Emacs finds and opens 14the file, reads the text, evaluates each form, and then closes the 15file. Such a file is also called a @dfn{Lisp library}. 16 17 The load functions evaluate all the expressions in a file just 18as the @code{eval-buffer} function evaluates all the 19expressions in a buffer. The difference is that the load functions 20read and evaluate the text in the file as found on disk, not the text 21in an Emacs buffer. 22 23@cindex top-level form 24 The loaded file must contain Lisp expressions, either as source code 25or as byte-compiled code. Each form in the file is called a 26@dfn{top-level form}. There is no special format for the forms in a 27loadable file; any form in a file may equally well be typed directly 28into a buffer and evaluated there. (Indeed, most code is tested this 29way.) Most often, the forms are function definitions and variable 30definitions. 31 32 Emacs can also load compiled dynamic modules: shared libraries that 33provide additional functionality for use in Emacs Lisp programs, just 34like a package written in Emacs Lisp would. When a dynamic module is 35loaded, Emacs calls a specially-named initialization function which 36the module needs to implement, and which exposes the additional 37functions and variables to Emacs Lisp programs. 38 39For on-demand loading of external libraries which are known in advance 40to be required by certain Emacs primitives, @pxref{Dynamic Libraries}. 41 42@menu 43* How Programs Do Loading:: The @code{load} function and others. 44* Load Suffixes:: Details about the suffixes that @code{load} tries. 45* Library Search:: Finding a library to load. 46* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. 47* Autoload:: Setting up a function to autoload. 48* Repeated Loading:: Precautions about loading a file twice. 49* Named Features:: Loading a library if it isn't already loaded. 50* Where Defined:: Finding which file defined a certain symbol. 51* Unloading:: How to unload a library that was loaded. 52* Hooks for Loading:: Providing code to be run when 53 particular libraries are loaded. 54* Dynamic Modules:: Modules provide additional Lisp primitives. 55@end menu 56 57@node How Programs Do Loading 58@section How Programs Do Loading 59 60 Emacs Lisp has several interfaces for loading. For example, 61@code{autoload} creates a placeholder object for a function defined in a 62file; trying to call the autoloading function loads the file to get the 63function's real definition (@pxref{Autoload}). @code{require} loads a 64file if it isn't already loaded (@pxref{Named Features}). Ultimately, 65all these facilities call the @code{load} function to do the work. 66 67@defun load filename &optional missing-ok nomessage nosuffix must-suffix 68This function finds and opens a file of Lisp code, evaluates all the 69forms in it, and closes the file. 70 71To find the file, @code{load} first looks for a file named 72@file{@var{filename}.elc}, that is, for a file whose name is 73@var{filename} with the extension @samp{.elc} appended. If such a 74file exists, and Emacs was compiled with native-compilation support 75(@pxref{Native Compilation}), @code{load} attempts to find a 76corresponding @samp{.eln} file, and if found, loads it instead of 77@file{@var{filename}.elc}. Otherwise, it loads 78@file{@var{filename}.elc}. If there is no file by that name, then 79@code{load} looks for a file named @file{@var{filename}.el}. If that 80file exists, it is loaded. If Emacs was compiled with support for 81dynamic modules (@pxref{Dynamic Modules}), @code{load} next looks for 82a file named @file{@var{filename}.@var{ext}}, where @var{ext} is a 83system-dependent file-name extension of shared libraries. Finally, if 84neither of those names is found, @code{load} looks for a file named 85@var{filename} with nothing appended, and loads it if it exists. (The 86@code{load} function is not clever about looking at @var{filename}. 87In the perverse case of a file named @file{foo.el.el}, evaluation of 88@code{(load "foo.el")} will indeed find it.) 89 90If Auto Compression mode is enabled, as it is by default, then if 91@code{load} can not find a file, it searches for a compressed version 92of the file before trying other file names. It decompresses and loads 93it if it exists. It looks for compressed versions by appending each 94of the suffixes in @code{jka-compr-load-suffixes} to the file name. 95The value of this variable must be a list of strings. Its standard 96value is @code{(".gz")}. 97 98If the optional argument @var{nosuffix} is non-@code{nil}, then 99@code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In 100this case, you must specify the precise file name you want, except 101that, if Auto Compression mode is enabled, @code{load} will still use 102@code{jka-compr-load-suffixes} to find compressed versions. By 103specifying the precise file name and using @code{t} for 104@var{nosuffix}, you can prevent file names like @file{foo.el.el} from 105being tried. 106 107If the optional argument @var{must-suffix} is non-@code{nil}, then 108@code{load} insists that the file name used must end in either 109@samp{.el} or @samp{.elc} (possibly extended with a compression 110suffix) or the shared-library extension, unless it contains an 111explicit directory name. 112 113If the option @code{load-prefer-newer} is non-@code{nil}, then when 114searching suffixes, @code{load} selects whichever version of a file 115(@samp{.elc}, @samp{.el}, etc.)@: has been modified most recently. 116In this case, @code{load} doesn't load the @samp{.eln} 117natively-compiled file even if it exists. 118 119If @var{filename} is a relative file name, such as @file{foo} or 120@file{baz/foo.bar}, @code{load} searches for the file using the variable 121@code{load-path}. It appends @var{filename} to each of the directories 122listed in @code{load-path}, and loads the first file it finds whose name 123matches. The current default directory is tried only if it is specified 124in @code{load-path}, where @code{nil} stands for the default directory. 125@code{load} tries all three possible suffixes in the first directory in 126@code{load-path}, then all three suffixes in the second directory, and 127so on. @xref{Library Search}. 128 129Whatever the name under which the file is eventually found, and the 130directory where Emacs found it, Emacs sets the value of the variable 131@code{load-file-name} to that file's name. 132 133If you get a warning that @file{foo.elc} is older than @file{foo.el}, it 134means you should consider recompiling @file{foo.el}. @xref{Byte 135Compilation}. 136 137When loading a source file (not compiled), @code{load} performs 138character set translation just as Emacs would do when visiting the file. 139@xref{Coding Systems}. 140 141@c This is referred to from the Macros chapter. 142@c Not sure if it should be the other way round. 143@cindex eager macro expansion 144When loading an uncompiled file, Emacs tries to expand any macros 145that the file contains (@pxref{Macros}). We refer to this as 146@dfn{eager macro expansion}. Doing this (rather than deferring 147the expansion until the relevant code runs) can significantly speed 148up the execution of uncompiled code. Sometimes, this macro expansion 149cannot be done, owing to a cyclic dependency. In the simplest 150example of this, the file you are loading refers to a macro defined 151in another file, and that file in turn requires the file you are 152loading. This is generally harmless. Emacs prints a warning 153(@samp{Eager macro-expansion skipped due to cycle@dots{}}) 154giving details of the problem, but it still loads the file, just 155leaving the macro unexpanded for now. You may wish to restructure 156your code so that this does not happen. Loading a compiled file does 157not cause macroexpansion, because this should already have happened 158during compilation. @xref{Compiling Macros}. 159 160Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear 161in the echo area during loading unless @var{nomessage} is 162non-@code{nil}. If a natively-compiled @samp{.eln} file is loaded, 163the message says so. 164 165@cindex load errors 166Any unhandled errors while loading a file terminate loading. If the 167load was done for the sake of @code{autoload}, any function definitions 168made during the loading are undone. 169 170@kindex file-error 171If @code{load} can't find the file to load, then normally it signals a 172@code{file-error} (with @samp{Cannot open load file 173@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then 174@code{load} just returns @code{nil}. 175 176You can use the variable @code{load-read-function} to specify a function 177for @code{load} to use instead of @code{read} for reading expressions. 178See below. 179 180@code{load} returns @code{t} if the file loads successfully. 181@end defun 182 183@deffn Command load-file filename 184This command loads the file @var{filename}. If @var{filename} is a 185relative file name, then the current default directory is assumed. 186This command does not use @code{load-path}, and does not append 187suffixes. However, it does look for compressed versions (if Auto 188Compression Mode is enabled). Use this command if you wish to specify 189precisely the file name to load. 190@end deffn 191 192@deffn Command load-library library 193This command loads the library named @var{library}. It is equivalent to 194@code{load}, except for the way it reads its argument interactively. 195@xref{Lisp Libraries,,,emacs, The GNU Emacs Manual}. 196@end deffn 197 198@defvar load-in-progress 199This variable is non-@code{nil} if Emacs is in the process of loading a 200file, and it is @code{nil} otherwise. 201@end defvar 202 203@defvar load-file-name 204When Emacs is in the process of loading a file, this variable's value 205is the name of that file, as Emacs found it during the search 206described earlier in this section. 207@end defvar 208 209@defvar load-read-function 210@anchor{Definition of load-read-function} 211@c do not allow page break at anchor; work around Texinfo deficiency. 212This variable specifies an alternate expression-reading function for 213@code{load} and @code{eval-region} to use instead of @code{read}. 214The function should accept one argument, just as @code{read} does. 215 216By default, this variable's value is @code{read}. @xref{Input 217Functions}. 218 219Instead of using this variable, it is cleaner to use another, newer 220feature: to pass the function as the @var{read-function} argument to 221@code{eval-region}. @xref{Definition of eval-region,, Eval}. 222@end defvar 223 224 For information about how @code{load} is used in building Emacs, see 225@ref{Building Emacs}. 226 227@node Load Suffixes 228@section Load Suffixes 229We now describe some technical details about the exact suffixes that 230@code{load} tries. 231 232@defvar load-suffixes 233This is a list of suffixes indicating (compiled or source) Emacs Lisp 234files. It should not include the empty string. @code{load} uses 235these suffixes in order when it appends Lisp suffixes to the specified 236file name. The standard value is @code{(".elc" ".el")} which produces 237the behavior described in the previous section. 238@end defvar 239 240@defvar load-file-rep-suffixes 241This is a list of suffixes that indicate representations of the same 242file. This list should normally start with the empty string. 243When @code{load} searches for a file it appends the suffixes in this 244list, in order, to the file name, before searching for another file. 245 246Enabling Auto Compression mode appends the suffixes in 247@code{jka-compr-load-suffixes} to this list and disabling Auto 248Compression mode removes them again. The standard value of 249@code{load-file-rep-suffixes} if Auto Compression mode is disabled is 250@code{("")}. Given that the standard value of 251@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value 252of @code{load-file-rep-suffixes} if Auto Compression mode is enabled 253is @code{("" ".gz")}. 254@end defvar 255 256@defun get-load-suffixes 257This function returns the list of all suffixes that @code{load} should 258try, in order, when its @var{must-suffix} argument is non-@code{nil}. 259This takes both @code{load-suffixes} and @code{load-file-rep-suffixes} 260into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes} 261and @code{load-file-rep-suffixes} all have their standard values, this 262function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto 263Compression mode is enabled and @code{(".elc" ".el")} if Auto 264Compression mode is disabled. 265@end defun 266 267To summarize, @code{load} normally first tries the suffixes in the 268value of @code{(get-load-suffixes)} and then those in 269@code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil}, 270it skips the former group, and if @var{must-suffix} is non-@code{nil}, 271it skips the latter group. 272 273@defopt load-prefer-newer 274If this option is non-@code{nil}, then rather than stopping at the 275first suffix that exists, @code{load} tests them all, and uses 276whichever file is the newest. 277@end defopt 278 279@node Library Search 280@section Library Search 281@cindex library search 282@cindex find library 283 284 When Emacs loads a Lisp library, it searches for the library 285in a list of directories specified by the variable @code{load-path}. 286 287@defvar load-path 288The value of this variable is a list of directories to search when 289loading files with @code{load}. Each element is a string (which must be 290a directory) or @code{nil} (which stands for the current working 291directory). 292@end defvar 293 294 When Emacs starts up, it sets up the value of @code{load-path} in 295several steps. First, it looks for the directory containing its own 296Lisp files, using default locations set when Emacs was compiled. It 297saves this directory in @code{lisp-directory}. Normally, this is a 298directory where the @file{*.elc} files are installed, something like 299 300@example 301"/usr/local/share/emacs/@var{version}/lisp" 302@end example 303 304@noindent 305where @var{version} is the Emacs version. (In this and the following 306examples, replace @file{/usr/local} with the prefix appropriate for 307your Emacs installation.) This directory and its subdirectories 308contain the standard Lisp files that come with Emacs. If Emacs cannot 309find its own Lisp files, it will not start correctly. 310 311If you run Emacs from the directory where it was built---that is, an 312executable that has not been installed yet---Emacs instead initializes 313@code{lisp-directory} using the @file{lisp} subdirectory of the 314directory containing the sources from which it was built. 315 316Emacs then initializes @code{load-path} with this @code{lisp-directory}. 317@c Though there should be no *.el files in builddir/lisp, so it's pointless. 318If you built Emacs in a separate directory from the 319sources, it also adds the @file{lisp} subdirectory of the build directory. 320 321All of these directories are stored in the above two variables as 322absolute file names. 323 324@cindex site-lisp directories 325Unless you start Emacs with the @option{--no-site-lisp} option, 326it then adds two more @file{site-lisp} directories to the front of 327@code{load-path}. These are intended for locally installed Lisp files, 328and are normally of the form: 329 330@example 331"/usr/local/share/emacs/@var{version}/site-lisp" 332@end example 333 334@noindent 335and 336 337@example 338"/usr/local/share/emacs/site-lisp" 339@end example 340 341@noindent 342The first one is for locally installed files for the current Emacs 343@var{version}; the second is for locally installed files meant for use 344with any installed Emacs version. (If Emacs is running uninstalled, 345it also adds @file{site-lisp} subdirectories from the source and build 346directories, if they exist. However, normally the source and build 347directories do not contain @file{site-lisp} subdirectories.) 348 349@cindex @env{EMACSLOADPATH} environment variable 350If the environment variable @env{EMACSLOADPATH} is set, it modifies 351the above initialization procedure. Emacs initializes 352@code{load-path} based on the value of the environment variable. 353 354The syntax of @env{EMACSLOADPATH} is the same as used for @env{PATH}; 355directories are separated by @samp{:} (or @samp{;}, on some 356operating systems). 357@ignore 358@c AFAICS, does not (yet) work right to specify non-absolute elements. 359and @samp{.} stands for the current default directory. 360@end ignore 361Here is an example of how to set @env{EMACSLOADPATH} variable (from a 362@command{sh}-style shell): 363 364@example 365export EMACSLOADPATH=/home/foo/.emacs.d/lisp: 366@end example 367 368An empty element in the value of the environment variable, whether 369trailing (as in the above example, note the trailing @samp{:}), 370leading, or embedded, is replaced by the default value of 371@code{load-path} as determined by the standard initialization 372procedure. If there are no such empty elements, then 373@env{EMACSLOADPATH} specifies the entire @code{load-path}. You must 374include either an empty element, or the explicit path to the directory 375containing the standard Lisp files, else Emacs will not function. 376(Another way to modify @code{load-path} is to use the @option{-L} 377command-line option when starting Emacs; see below.) 378 379 For each directory in @code{load-path}, Emacs then checks to see if 380it contains a file @file{subdirs.el}, and if so, loads it. The 381@file{subdirs.el} file is created when Emacs is built/installed, 382and contains code that causes Emacs to add any subdirectories of those 383directories to @code{load-path}. Both immediate subdirectories and 384subdirectories multiple levels down are added. But it excludes 385subdirectories whose names do not start with a letter or digit, and 386subdirectories named @file{RCS} or @file{CVS}, and subdirectories 387containing a file named @file{.nosearch}. 388 389 Next, Emacs adds any extra load directories that you specify using the 390@option{-L} command-line option (@pxref{Action Arguments,,,emacs, The 391GNU Emacs Manual}). It also adds the directories where optional 392packages are installed, if any (@pxref{Packaging Basics}). 393 394 It is common to add code to one's init file (@pxref{Init File}) to 395add one or more directories to @code{load-path}. For example: 396 397@example 398(push "~/.emacs.d/lisp" load-path) 399@end example 400 401@noindent 402@xref{List Variables, push}, for the description of @code{push}. 403 404 Dumping Emacs uses a special value of @code{load-path}. If you use 405a @file{site-load.el} or @file{site-init.el} file to customize the 406dumped Emacs (@pxref{Building Emacs}), any changes to @code{load-path} 407that these files make will be lost after dumping. 408 409@defvar lisp-directory 410This variable holds a string naming the directory which holds 411Emacs's own @file{*.el} and @file{*.elc} files. This is usually the 412place where those files are located in the Emacs installation tree, 413unless Emacs is run from its build directory in which case it points 414to the @file{lisp} subdirectory in the source directory from which 415Emacs was built. 416@end defvar 417 418@deffn Command locate-library library &optional nosuffix path interactive-call 419This command finds the precise file name for library @var{library}. It 420searches for the library in the same way @code{load} does, and the 421argument @var{nosuffix} has the same meaning as in @code{load}: don't 422add suffixes @samp{.elc} or @samp{.el} to the specified name 423@var{library}. 424 425If the @var{path} is non-@code{nil}, that list of directories is used 426instead of @code{load-path}. 427 428When @code{locate-library} is called from a program, it returns the file 429name as a string. When the user runs @code{locate-library} 430interactively, the argument @var{interactive-call} is @code{t}, and this 431tells @code{locate-library} to display the file name in the echo area. 432@end deffn 433 434@cindex shadowed Lisp files 435@deffn Command list-load-path-shadows &optional stringp 436This command shows a list of @dfn{shadowed} Emacs Lisp files. A 437shadowed file is one that will not normally be loaded, despite being 438in a directory on @code{load-path}, due to the existence of another 439similarly-named file in a directory earlier on @code{load-path}. 440 441For instance, suppose @code{load-path} is set to 442 443@example 444 ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp") 445@end example 446 447@noindent 448and that both these directories contain a file named @file{foo.el}. 449Then @code{(require 'foo)} never loads the file in the second 450directory. Such a situation might indicate a problem in the way Emacs 451was installed. 452 453When called from Lisp, this function prints a message listing the 454shadowed files, instead of displaying them in a buffer. If the 455optional argument @code{stringp} is non-@code{nil}, it instead returns 456the shadowed files as a string. 457@end deffn 458 459 If Emacs was compiled with support for native compilation 460(@pxref{Native Compilation}), then when a @samp{.elc} byte-compiled 461file is found by searching @code{load-path}, Emacs will try to look 462for a corresponding @samp{.eln} file holding the corresponding 463natively-compiled code. The natively-compiled files are looked up in 464the directories listed by the @code{native-comp-eln-load-path}. 465 466@vindex comp-native-version-dir 467@defvar native-comp-eln-load-path 468This variable holds a list of directories where Emacs looks for 469natively-compiled @samp{.eln} files. File names in the list that are 470not absolute are interpreted as relative to @code{invocation-directory} 471(@pxref{System Environment}). The last directory in the list is the 472system directory, i.e.@: the directory with @samp{.eln} files 473installed by the Emacs build and installation procedure. In each of 474the directories in the list, Emacs looks for @samp{.eln} files in a 475subdirectory whose name is constructed from the Emacs version and an 4768-character hash that depends on the current native-compilation 477@acronym{ABI}; the name of this subdirectory is stored in the variable 478@code{comp-native-version-dir}. 479@end defvar 480 481@node Loading Non-ASCII 482@section Loading Non-@acronym{ASCII} Characters 483@cindex loading, and non-ASCII characters 484@cindex non-ASCII characters in loaded files 485 486 When Emacs Lisp programs contain string constants with non-@acronym{ASCII} 487characters, these can be represented within Emacs either as unibyte 488strings or as multibyte strings (@pxref{Text Representations}). Which 489representation is used depends on how the file is read into Emacs. If 490it is read with decoding into multibyte representation, the text of the 491Lisp program will be multibyte text, and its string constants will be 492multibyte strings. If a file containing Latin-1 characters (for 493example) is read without decoding, the text of the program will be 494unibyte text, and its string constants will be unibyte strings. 495@xref{Coding Systems}. 496 497 In most Emacs Lisp programs, the fact that non-@acronym{ASCII} 498strings are multibyte strings should not be noticeable, since 499inserting them in unibyte buffers converts them to unibyte 500automatically. However, if this does make a difference, you can force 501a particular Lisp file to be interpreted as unibyte by writing 502@samp{coding: raw-text} in a local variables section. With 503that designator, the file will unconditionally be interpreted as 504unibyte. This can matter when making key bindings to 505non-@acronym{ASCII} characters written as @code{?v@var{literal}}. 506 507@node Autoload 508@section Autoload 509@cindex autoload 510 511 The @dfn{autoload} facility lets you register the existence of a 512function or macro, but put off loading the file that defines it. The 513first call to the function automatically loads the proper library, in 514order to install the real definition and other associated code, then 515runs the real definition as if it had been loaded all along. 516Autoloading can also be triggered by looking up the documentation of 517the function or macro (@pxref{Documentation Basics}), and completion 518of variable and function names (@pxref{Autoload by Prefix} below). 519 520@menu 521* Autoload by Prefix:: Autoload by Prefix. 522* When to Autoload:: When to Use Autoload. 523@end menu 524 525 There are two ways to set up an autoloaded function: by calling 526@code{autoload}, and by writing a ``magic'' comment in the 527source before the real definition. @code{autoload} is the low-level 528primitive for autoloading; any Lisp program can call @code{autoload} at 529any time. Magic comments are the most convenient way to make a function 530autoload, for packages installed along with Emacs. These comments do 531nothing on their own, but they serve as a guide for the command 532@code{update-file-autoloads}, which constructs calls to @code{autoload} 533and arranges to execute them when Emacs is built. 534 535@defun autoload function filename &optional docstring interactive type 536This function defines the function (or macro) named @var{function} so as 537to load automatically from @var{filename}. The string @var{filename} 538specifies the file to load to get the real definition of @var{function}. 539 540If @var{filename} does not contain either a directory name, or the 541suffix @code{.el} or @code{.elc}, this function insists on adding one 542of these suffixes, and it will not load from a file whose name is just 543@var{filename} with no added suffix. (The variable 544@code{load-suffixes} specifies the exact required suffixes.) 545 546The argument @var{docstring} is the documentation string for the 547function. Specifying the documentation string in the call to 548@code{autoload} makes it possible to look at the documentation without 549loading the function's real definition. Normally, this should be 550identical to the documentation string in the function definition 551itself. If it isn't, the function definition's documentation string 552takes effect when it is loaded. 553 554If @var{interactive} is non-@code{nil}, that says @var{function} can be 555called interactively. This lets completion in @kbd{M-x} work without 556loading @var{function}'s real definition. The complete interactive 557specification is not given here; it's not needed unless the user 558actually calls @var{function}, and when that happens, it's time to load 559the real definition. 560 561If @var{interactive} is a list, it is interpreted as a list of modes 562this command is applicable for. 563 564You can autoload macros and keymaps as well as ordinary functions. 565Specify @var{type} as @code{macro} if @var{function} is really a macro. 566Specify @var{type} as @code{keymap} if @var{function} is really a 567keymap. Various parts of Emacs need to know this information without 568loading the real definition. 569 570An autoloaded keymap loads automatically during key lookup when a prefix 571key's binding is the symbol @var{function}. Autoloading does not occur 572for other kinds of access to the keymap. In particular, it does not 573happen when a Lisp program gets the keymap from the value of a variable 574and calls @code{keymap-set}; not even if the variable name is the same 575symbol @var{function}. 576 577@cindex function cell in autoload 578If @var{function} already has a non-void function definition that is not 579an autoload object, this function does nothing and returns @code{nil}. 580Otherwise, it constructs an autoload object (@pxref{Autoload Type}), 581and stores it as the function definition for @var{function}. The 582autoload object has this form: 583 584@example 585(autoload @var{filename} @var{docstring} @var{interactive} @var{type}) 586@end example 587 588For example, 589 590@example 591@group 592(symbol-function 'run-prolog) 593 @result{} (autoload "prolog" 169681 t nil) 594@end group 595@end example 596 597@noindent 598In this case, @code{"prolog"} is the name of the file to load, 169681 599refers to the documentation string in the 600@file{emacs/etc/DOC} file (@pxref{Documentation Basics}), 601@code{t} means the function is interactive, and @code{nil} that it is 602not a macro or a keymap. 603@end defun 604 605@defun autoloadp object 606This function returns non-@code{nil} if @var{object} is an autoload 607object. For example, to check if @code{run-prolog} is defined as an 608autoloaded function, evaluate 609 610@smallexample 611(autoloadp (symbol-function 'run-prolog)) 612@end smallexample 613@end defun 614 615@cindex autoload errors 616 The autoloaded file usually contains other definitions and may require 617or provide one or more features. If the file is not completely loaded 618(due to an error in the evaluation of its contents), any function 619definitions or @code{provide} calls that occurred during the load are 620undone. This is to ensure that the next attempt to call any function 621autoloading from this file will try again to load the file. If not for 622this, then some of the functions in the file might be defined by the 623aborted load, but fail to work properly for the lack of certain 624subroutines not loaded successfully because they come later in the file. 625 626 If the autoloaded file fails to define the desired Lisp function or 627macro, then an error is signaled with data @code{"Autoloading failed to 628define function @var{function-name}"}. 629 630@findex update-file-autoloads 631@findex make-directory-autoloads 632@cindex magic autoload comment 633@cindex autoload cookie 634@anchor{autoload cookie} 635 A magic autoload comment (often called an @dfn{autoload cookie}) 636consists of @samp{;;;###autoload}, on a line by itself, 637just before the real definition of the function in its 638autoloadable source file. The command @kbd{M-x update-file-autoloads} 639writes a corresponding @code{autoload} call into @file{loaddefs.el}. 640(The string that serves as the autoload cookie and the name of the 641file generated by @code{update-file-autoloads} can be changed from the 642above defaults, see below.) 643Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}. 644@kbd{M-x make-directory-autoloads} is even more powerful; it updates 645autoloads for all files in the current directory. 646 647 The same magic comment can copy any kind of form into 648@file{loaddefs.el}. The form following the magic comment is copied 649verbatim, @emph{except} if it is one of the forms which the autoload 650facility handles specially (e.g., by conversion into an 651@code{autoload} call). The forms which are not copied verbatim are 652the following: 653 654@table @asis 655@item Definitions for function or function-like objects: 656@code{defun} and @code{defmacro}; also @code{cl-defun} and 657@code{cl-defmacro} (@pxref{Argument Lists,,,cl,Common Lisp Extensions}), 658and @code{define-overloadable-function} (see the commentary in 659@file{mode-local.el}). 660 661@item Definitions for major or minor modes: 662@code{define-minor-mode}, @code{define-globalized-minor-mode}, 663@code{define-generic-mode}, @code{define-derived-mode}, 664@code{easy-mmode-define-minor-mode}, 665@code{easy-mmode-define-global-mode}, @code{define-compilation-mode}, 666and @code{define-global-minor-mode}. 667 668@item Other definition types: 669@code{defcustom}, @code{defgroup}, @code{defclass} 670(@pxref{Top,EIEIO,,eieio,EIEIO}), and @code{define-skeleton} 671(@pxref{Top,Autotyping,,autotype,Autotyping}). 672@end table 673 674 You can also use a magic comment to execute a form at build time 675@emph{without} executing it when the file itself is loaded. To do this, 676write the form @emph{on the same line} as the magic comment. Since it 677is in a comment, it does nothing when you load the source file; but 678@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where 679it is executed while building Emacs. 680 681 The following example shows how @code{doctor} is prepared for 682autoloading with a magic comment: 683 684@example 685;;;###autoload 686(defun doctor () 687 "Switch to *doctor* buffer and start giving psychotherapy." 688 (interactive) 689 (switch-to-buffer "*doctor*") 690 (doctor-mode)) 691@end example 692 693@noindent 694Here's what that produces in @file{loaddefs.el}: 695 696@example 697(autoload 'doctor "doctor" "\ 698Switch to *doctor* buffer and start giving psychotherapy. 699 700\(fn)" t nil) 701@end example 702 703@noindent 704@cindex @code{fn} in function's documentation string 705The backslash and newline immediately following the double-quote are a 706convention used only in the preloaded uncompiled Lisp files such as 707@file{loaddefs.el}; they tell @code{make-docfile} to put the 708documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. 709See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)} 710in the usage part of the documentation string is replaced with the 711function's name when the various help functions (@pxref{Help 712Functions}) display it. 713 714 If you write a function definition with an unusual macro that is not 715one of the known and recognized function definition methods, use of an 716ordinary magic autoload comment would copy the whole definition into 717@code{loaddefs.el}. That is not desirable. You can put the desired 718@code{autoload} call into @code{loaddefs.el} instead by writing this: 719 720@example 721;;;###autoload (autoload 'foo "myfile") 722(mydefunmacro foo 723 ...) 724@end example 725 726 You can use a non-default string as the autoload cookie and have the 727corresponding autoload calls written into a file whose name is 728different from the default @file{loaddefs.el}. Emacs provides two 729variables to control this: 730 731@defvar generate-autoload-cookie 732The value of this variable should be a string whose syntax is a Lisp 733comment. @kbd{M-x update-file-autoloads} copies the Lisp form that 734follows the cookie into the autoload file it generates. The default 735value of this variable is @code{";;;###autoload"}. 736@end defvar 737 738@defvar generated-autoload-file 739The value of this variable names an Emacs Lisp file where the autoload 740calls should go. The default value is @file{loaddefs.el}, but you can 741override that, e.g., in the local variables section of a 742@file{.el} file (@pxref{File Local Variables}). The autoload file is 743assumed to contain a trailer starting with a formfeed character. 744@end defvar 745 746 The following function may be used to explicitly load the library 747specified by an autoload object: 748 749@defun autoload-do-load autoload &optional name macro-only 750This function performs the loading specified by @var{autoload}, which 751should be an autoload object. The optional argument @var{name}, if 752non-@code{nil}, should be a symbol whose function value is 753@var{autoload}; in that case, the return value of this function is the 754symbol's new function value. If the value of the optional argument 755@var{macro-only} is @code{macro}, this function avoids loading a 756function, only a macro. 757@end defun 758 759@node Autoload by Prefix 760@subsection Autoload by Prefix 761@cindex autoload by prefix 762 763@vindex definition-prefixes 764@findex register-definition-prefixes 765@vindex autoload-compute-prefixes 766During completion for the commands @code{describe-variable} and 767@code{describe-function}, Emacs will try to load files which may 768contain definitions matching the prefix being completed. The variable 769@code{definition-prefixes} holds a hashtable which maps a prefix to 770the corresponding list of files to load for it. Entries to this 771mapping are added by calls to @code{register-definition-prefixes} 772which are generated by @code{update-file-autoloads} 773(@pxref{Autoload}). Files which don't contain any definitions worth 774loading (test files, for examples), should set 775@code{autoload-compute-prefixes} to @code{nil} as a file-local 776variable. 777 778@node When to Autoload 779@subsection When to Use Autoload 780@cindex autoload, when to use 781 782Do not add an autoload comment unless it is really necessary. 783Autoloading code means it is always globally visible. Once an item is 784autoloaded, there is no compatible way to transition back to it not 785being autoloaded (after people become accustomed to being able to use it 786without an explicit load). 787 788@itemize 789@item 790The most common items to autoload are the interactive entry points to a 791library. For example, if @file{python.el} is a library defining a 792major-mode for editing Python code, autoload the definition of the 793@code{python-mode} function, so that people can simply use @kbd{M-x 794python-mode} to load the library. 795 796@item 797Variables usually don't need to be autoloaded. An exception is if the 798variable on its own is generally useful without the whole defining 799library being loaded. (An example of this might be something like 800@code{find-exec-terminator}.) 801 802@item 803Don't autoload a user option just so that a user can set it. 804 805@item 806Never add an autoload @emph{comment} to silence a compiler warning in 807another file. In the file that produces the warning, use 808@code{(defvar foo)} to silence an undefined variable warning, and 809@code{declare-function} (@pxref{Declaring Functions}) to silence an 810undefined function warning; or require the relevant library; or use an 811explicit autoload @emph{statement}. 812@end itemize 813 814@node Repeated Loading 815@section Repeated Loading 816@cindex repeated loading 817 818 You can load a given file more than once in an Emacs session. For 819example, after you have rewritten and reinstalled a function definition 820by editing it in a buffer, you may wish to return to the original 821version; you can do this by reloading the file it came from. 822 823 When you load or reload files, bear in mind that the @code{load} and 824@code{load-library} functions automatically load a byte-compiled file 825rather than a non-compiled file of similar name. If you rewrite a file 826that you intend to save and reinstall, you need to byte-compile the new 827version; otherwise Emacs will load the older, byte-compiled file instead 828of your newer, non-compiled file! If that happens, the message 829displayed when loading the file includes, @samp{(compiled; note, source is 830newer)}, to remind you to recompile it. 831 832 When writing the forms in a Lisp library file, keep in mind that the 833file might be loaded more than once. For example, think about whether 834each variable should be reinitialized when you reload the library; 835@code{defvar} does not change the value if the variable is already 836initialized. (@xref{Defining Variables}.) 837 838 The simplest way to add an element to an alist is like this: 839 840@example 841(push '(leif-mode " Leif") minor-mode-alist) 842@end example 843 844@noindent 845But this would add multiple elements if the library is reloaded. To 846avoid the problem, use @code{add-to-list} (@pxref{List Variables}): 847 848@example 849(add-to-list 'minor-mode-alist '(leif-mode " Leif")) 850@end example 851 852 Occasionally you will want to test explicitly whether a library has 853already been loaded. If the library uses @code{provide} to provide a 854named feature, you can use @code{featurep} earlier in the file to test 855whether the @code{provide} call has been executed before (@pxref{Named 856Features}). Alternatively, you could use something like this: 857 858@example 859(defvar foo-was-loaded nil) 860 861(unless foo-was-loaded 862 @var{execute-first-time-only} 863 (setq foo-was-loaded t)) 864@end example 865 866@noindent 867 868@node Named Features 869@section Features 870@cindex features 871@cindex requiring features 872@cindex providing features 873 874 @code{provide} and @code{require} are an alternative to 875@code{autoload} for loading files automatically. They work in terms of 876named @dfn{features}. Autoloading is triggered by calling a specific 877function, but a feature is loaded the first time another program asks 878for it by name. 879 880 A feature name is a symbol that stands for a collection of functions, 881variables, etc. The file that defines them should @dfn{provide} the 882feature. Another program that uses them may ensure they are defined by 883@dfn{requiring} the feature. This loads the file of definitions if it 884hasn't been loaded already. 885 886@cindex load error with require 887 To require the presence of a feature, call @code{require} with the 888feature name as argument. @code{require} looks in the global variable 889@code{features} to see whether the desired feature has been provided 890already. If not, it loads the feature from the appropriate file. This 891file should call @code{provide} at the top level to add the feature to 892@code{features}; if it fails to do so, @code{require} signals an error. 893 894 For example, in @file{idlwave.el}, the definition for 895@code{idlwave-complete-filename} includes the following code: 896 897@example 898(defun idlwave-complete-filename () 899 "Use the comint stuff to complete a file name." 900 (require 'comint) 901 (let* ((comint-file-name-chars "~/A-Za-z0-9+@@:_.$#%=@{@}\\-") 902 (comint-completion-addsuffix nil) 903 ...) 904 (comint-dynamic-complete-filename))) 905@end example 906 907@noindent 908The expression @code{(require 'comint)} loads the file @file{comint.el} 909if it has not yet been loaded, ensuring that 910@code{comint-dynamic-complete-filename} is defined. Features are 911normally named after the files that provide them, so that 912@code{require} need not be given the file name. (Note that it is 913important that the @code{require} statement be outside the body of the 914@code{let}. Loading a library while its variables are let-bound can 915have unintended consequences, namely the variables becoming unbound 916after the let exits.) 917 918The @file{comint.el} file contains the following top-level expression: 919 920@example 921(provide 'comint) 922@end example 923 924@noindent 925This adds @code{comint} to the global @code{features} list, so that 926@code{(require 'comint)} will henceforth know that nothing needs to be 927done. 928 929@cindex byte-compiling @code{require} 930 When @code{require} is used at top level in a file, it takes effect 931when you byte-compile that file (@pxref{Byte Compilation}) as well as 932when you load it. This is in case the required package contains macros 933that the byte compiler must know about. It also avoids byte compiler 934warnings for functions and variables defined in the file loaded with 935@code{require}. 936 937 Although top-level calls to @code{require} are evaluated during 938byte compilation, @code{provide} calls are not. Therefore, you can 939ensure that a file of definitions is loaded before it is byte-compiled 940by including a @code{provide} followed by a @code{require} for the same 941feature, as in the following example. 942 943@example 944@group 945(provide 'my-feature) ; @r{Ignored by byte compiler,} 946 ; @r{evaluated by @code{load}.} 947(require 'my-feature) ; @r{Evaluated by byte compiler.} 948@end group 949@end example 950 951@noindent 952The compiler ignores the @code{provide}, then processes the 953@code{require} by loading the file in question. Loading the file does 954execute the @code{provide} call, so the subsequent @code{require} call 955does nothing when the file is loaded. 956 957@defun provide feature &optional subfeatures 958This function announces that @var{feature} is now loaded, or being 959loaded, into the current Emacs session. This means that the facilities 960associated with @var{feature} are or will be available for other Lisp 961programs. 962 963The direct effect of calling @code{provide} is to add @var{feature} to 964the front of @code{features} if it is not already in that list and 965call any @code{eval-after-load} code waiting for it (@pxref{Hooks for 966Loading}). The argument @var{feature} must be a symbol. 967@code{provide} returns @var{feature}. 968 969If provided, @var{subfeatures} should be a list of symbols indicating 970a set of specific subfeatures provided by this version of 971@var{feature}. You can test the presence of a subfeature using 972@code{featurep}. The idea of subfeatures is that you use them when a 973package (which is one @var{feature}) is complex enough to make it 974useful to give names to various parts or functionalities of the 975package, which might or might not be loaded, or might or might not be 976present in a given version. @xref{Network Feature Testing}, for 977an example. 978 979@example 980features 981 @result{} (bar bish) 982 983(provide 'foo) 984 @result{} foo 985features 986 @result{} (foo bar bish) 987@end example 988 989When a file is loaded to satisfy an autoload, and it stops due to an 990error in the evaluation of its contents, any function definitions or 991@code{provide} calls that occurred during the load are undone. 992@xref{Autoload}. 993@end defun 994 995@defun require feature &optional filename noerror 996This function checks whether @var{feature} is present in the current 997Emacs session (using @code{(featurep @var{feature})}; see below). The 998argument @var{feature} must be a symbol. 999 1000If the feature is not present, then @code{require} loads @var{filename} 1001with @code{load}. If @var{filename} is not supplied, then the name of 1002the symbol @var{feature} is used as the base file name to load. 1003However, in this case, @code{require} insists on finding @var{feature} 1004with an added @samp{.el} or @samp{.elc} suffix (possibly extended with 1005a compression suffix); a file whose name is just @var{feature} won't 1006be used. (The variable @code{load-suffixes} specifies the exact 1007required Lisp suffixes.) 1008 1009If @var{noerror} is non-@code{nil}, that suppresses errors from actual 1010loading of the file. In that case, @code{require} returns @code{nil} 1011if loading the file fails. Normally, @code{require} returns 1012@var{feature}. 1013 1014If loading the file succeeds but does not provide @var{feature}, 1015@code{require} signals an error about the missing feature. 1016@end defun 1017 1018@defun featurep feature &optional subfeature 1019This function returns @code{t} if @var{feature} has been provided in 1020the current Emacs session (i.e., if @var{feature} is a member of 1021@code{features}.) If @var{subfeature} is non-@code{nil}, then the 1022function returns @code{t} only if that subfeature is provided as well 1023(i.e., if @var{subfeature} is a member of the @code{subfeature} 1024property of the @var{feature} symbol.) 1025@end defun 1026 1027@defvar features 1028The value of this variable is a list of symbols that are the features 1029loaded in the current Emacs session. Each symbol was put in this list 1030with a call to @code{provide}. The order of the elements in the 1031@code{features} list is not significant. 1032@end defvar 1033 1034@node Where Defined 1035@section Which File Defined a Certain Symbol 1036@cindex symbol, where defined 1037@cindex where was a symbol defined 1038 1039@defun symbol-file symbol &optional type 1040This function returns the name of the file that defined @var{symbol}. 1041If @var{type} is @code{nil}, then any kind of definition is acceptable. 1042If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that 1043specifies function definition, variable definition, or face definition 1044only. 1045 1046The value is normally an absolute file name. It can also be @code{nil}, 1047if the definition is not associated with any file. If @var{symbol} 1048specifies an autoloaded function, the value can be a relative file name 1049without extension. 1050@end defun 1051 1052 The basis for @code{symbol-file} is the data in the variable 1053@code{load-history}. 1054 1055@defvar load-history 1056The value of this variable is an alist that associates the names of 1057loaded library files with the names of the functions and variables 1058they defined, as well as the features they provided or required. 1059 1060Each element in this alist describes one loaded library (including 1061libraries that are preloaded at startup). It is a list whose @sc{car} 1062is the absolute file name of the library (a string). The rest of the 1063list elements have these forms: 1064 1065@table @code 1066@item @var{var} 1067The symbol @var{var} was defined as a variable. 1068@item (defun . @var{fun}) 1069The function @var{fun} was defined. 1070@item (t . @var{fun}) 1071The function @var{fun} was previously an autoload before this library 1072redefined it as a function. The following element is always 1073@code{(defun . @var{fun})}, which represents defining @var{fun} as a 1074function. 1075@item (autoload . @var{fun}) 1076The function @var{fun} was defined as an autoload. 1077@item (defface . @var{face}) 1078The face @var{face} was defined. 1079@item (require . @var{feature}) 1080The feature @var{feature} was required. 1081@item (provide . @var{feature}) 1082The feature @var{feature} was provided. 1083@item (cl-defmethod @var{method} @var{specializers}) 1084The named @var{method} was defined by using @code{cl-defmethod}, with 1085@var{specializers} as its specializers. 1086@item (define-type . @var{type}) 1087The type @var{type} was defined. 1088@end table 1089 1090The value of @code{load-history} may have one element whose @sc{car} is 1091@code{nil}. This element describes definitions made with 1092@code{eval-buffer} on a buffer that is not visiting a file. 1093@end defvar 1094 1095 The command @code{eval-region} updates @code{load-history}, but does so 1096by adding the symbols defined to the element for the file being visited, 1097rather than replacing that element. @xref{Eval}. 1098 1099@node Unloading 1100@section Unloading 1101@cindex unloading packages 1102 1103 You can discard the functions and variables loaded by a library to 1104reclaim memory for other Lisp objects. To do this, use the function 1105@code{unload-feature}: 1106 1107@deffn Command unload-feature feature &optional force 1108This command unloads the library that provided feature @var{feature}. 1109It undefines all functions, macros, and variables defined in that 1110library with @code{defun}, @code{defalias}, @code{defsubst}, 1111@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}. 1112It then restores any autoloads formerly associated with those symbols. 1113(Loading saves these in the @code{autoload} property of the symbol.) 1114 1115Before restoring the previous definitions, @code{unload-feature} runs 1116@code{remove-hook} to remove functions defined by the library from certain 1117hooks. These hooks include variables whose names end in @samp{-hook} 1118(or the deprecated suffix @samp{-hooks}), plus those listed in 1119@code{unload-feature-special-hooks}, as well as 1120@code{auto-mode-alist}. This is to prevent Emacs from ceasing to 1121function because important hooks refer to functions that are no longer 1122defined. 1123 1124Standard unloading activities also undo ELP profiling of functions 1125in that library, unprovides any features provided by the library, and 1126cancels timers held in variables defined by the library. 1127 1128@vindex @var{feature}-unload-function 1129If these measures are not sufficient to prevent malfunction, a library 1130can define an explicit unloader named @code{@var{feature}-unload-function}. 1131If that symbol is defined as a function, @code{unload-feature} calls 1132it with no arguments before doing anything else. It can do whatever 1133is appropriate to unload the library. If it returns @code{nil}, 1134@code{unload-feature} proceeds to take the normal unload actions. 1135Otherwise it considers the job to be done. 1136 1137Ordinarily, @code{unload-feature} refuses to unload a library on which 1138other loaded libraries depend. (A library @var{a} depends on library 1139@var{b} if @var{a} contains a @code{require} for @var{b}.) If the 1140optional argument @var{force} is non-@code{nil}, dependencies are 1141ignored and you can unload any library. 1142@end deffn 1143 1144 The @code{unload-feature} function is written in Lisp; its actions are 1145based on the variable @code{load-history}. 1146 1147@defvar unload-feature-special-hooks 1148This variable holds a list of hooks to be scanned before unloading a 1149library, to remove functions defined in the library. 1150@end defvar 1151 1152@node Hooks for Loading 1153@section Hooks for Loading 1154@cindex loading hooks 1155@cindex hooks for loading 1156 1157You can ask for code to be executed each time Emacs loads a library, 1158by using the variable @code{after-load-functions}: 1159 1160@defvar after-load-functions 1161This abnormal hook is run after loading a file. Each function in the 1162hook is called with a single argument, the absolute filename of the 1163file that was just loaded. 1164@end defvar 1165 1166If you want code to be executed when a @emph{particular} library is 1167loaded, use the macro @code{with-eval-after-load}: 1168 1169@defmac with-eval-after-load library body@dots{} 1170This macro arranges to evaluate @var{body} at the end of loading 1171the file @var{library}, each time @var{library} is loaded. If 1172@var{library} is already loaded, it evaluates @var{body} right away. 1173 1174You don't need to give a directory or extension in the file name 1175@var{library}. Normally, you just give a bare file name, like this: 1176 1177@example 1178(with-eval-after-load "js" (keymap-set js-mode-map "C-c C-c" 'js-eval)) 1179@end example 1180 1181To restrict which files can trigger the evaluation, include a 1182directory or an extension or both in @var{library}. Only a file whose 1183absolute true name (i.e., the name with all symbolic links chased out) 1184matches all the given name components will match. In the following 1185example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory 1186@code{..../foo/bar} will trigger the evaluation, but not 1187@file{my_inst.el}: 1188 1189@example 1190(with-eval-after-load "foo/bar/my_inst.elc" @dots{}) 1191@end example 1192 1193@var{library} can also be a feature (i.e., a symbol), in which case 1194@var{body} is evaluated at the end of any file where 1195@code{(provide @var{library})} is called. 1196 1197An error in @var{body} does not undo the load, but does prevent 1198execution of the rest of @var{body}. 1199@end defmac 1200 1201Normally, well-designed Lisp programs should not use 1202@code{with-eval-after-load}. If you need to examine and set the 1203variables defined in another library (those meant for outside use), 1204you can do it immediately---there is no need to wait until the library 1205is loaded. If you need to call functions defined by that library, you 1206should load the library, preferably with @code{require} (@pxref{Named 1207Features}). 1208 1209@node Dynamic Modules 1210@section Emacs Dynamic Modules 1211@cindex dynamic modules 1212 1213 A @dfn{dynamic Emacs module} is a shared library that provides 1214additional functionality for use in Emacs Lisp programs, just like a 1215package written in Emacs Lisp would. 1216 1217 Functions that load Emacs Lisp packages can also load dynamic 1218modules. They recognize dynamic modules by looking at their file-name 1219extension, a.k.a.@: ``suffix''. This suffix is platform-dependent. 1220 1221@defvar module-file-suffix 1222This variable holds the system-dependent value of the file-name 1223extension of the module files. Its value is @file{.so} on POSIX 1224hosts, @file{.dylib} on macOS, and @file{.dll} on MS-Windows. 1225@end defvar 1226 1227 On macOS, dynamic modules can also have the suffix @file{.so} in 1228addition to @file{.dylib}. 1229 1230@findex emacs_module_init 1231@vindex plugin_is_GPL_compatible 1232Every dynamic module should export a C-callable function named 1233@code{emacs_module_init}, which Emacs will call as part of the call to 1234@code{load} or @code{require} which loads the module. It should also 1235export a symbol named @code{plugin_is_GPL_compatible} to indicate that 1236its code is released under the GPL or compatible license; Emacs will 1237signal an error if your program tries to load modules that don't 1238export such a symbol. 1239 1240If a module needs to call Emacs functions, it should do so through the 1241@acronym{API} (Application Programming Interface) defined and 1242documented in the header file @file{emacs-module.h} that is part of 1243the Emacs distribution. @xref{Writing Dynamic Modules}, for details 1244of using that API when writing your own modules. 1245 1246@cindex user-ptr object 1247@cindex user pointer object 1248Modules can create @code{user-ptr} Lisp objects that embed pointers to 1249C struct's defined by the module. This is useful for keeping around 1250complex data structures created by a module, to be passed back to the 1251module's functions. User-ptr objects can also have associated 1252@dfn{finalizers} -- functions to be run when the object is GC'ed; this 1253is useful for freeing any resources allocated for the underlying data 1254structure, such as memory, open file descriptors, etc. @xref{Module 1255Values}. 1256 1257@defun user-ptrp object 1258This function returns @code{t} if its argument is a @code{user-ptr} 1259object. 1260@end defun 1261 1262@defun module-load file 1263Emacs calls this low-level primitive to load a module from the 1264specified @var{file} and perform the necessary initialization of the 1265module. This is the primitive which makes sure the module exports the 1266@code{plugin_is_GPL_compatible} symbol, calls the module's 1267@code{emacs_module_init} function, and signals an error if that 1268function returns an error indication, or if the use typed @kbd{C-g} 1269during the initialization. If the initialization succeeds, 1270@code{module-load} returns @code{t}. Note that @var{file} must 1271already have the proper file-name extension, as this function doesn't 1272try looking for files with known extensions, unlike @code{load}. 1273 1274Unlike @code{load}, @code{module-load} doesn't record the module in 1275@code{load-history}, doesn't print any messages, and doesn't protect 1276against recursive loads. Most users should therefore use @code{load}, 1277@code{load-file}, @code{load-library}, or @code{require} instead of 1278@code{module-load}. 1279@end defun 1280 1281Loadable modules in Emacs are enabled by using the 1282@kbd{--with-modules} option at configure time. 1283