@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions.@setfilename ../info/loading@node Loading, Byte Compilation, Macros, Top@chapter Loading@cindex loading@cindex library@cindex Lisp library Loading a file of Lisp code means bringing its contents into the Lispenvironment in the form of Lisp objects. Emacs finds and opens thefile, reads the text, evaluates each form, and then closes the file. The load functions evaluate all the expressions in a file justas the @code{eval-current-buffer} function evaluates all theexpressions in a buffer. The difference is that the load functionsread and evaluate the text in the file as found on disk, not the textin an Emacs buffer.@cindex top-level form The loaded file must contain Lisp expressions, either as source codeor 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 aloadable file; any form in a file may equally well be typed directlyinto a buffer and evaluated there. (Indeed, most code is tested thisway.) Most often, the forms are function definitions and variabledefinitions. A file containing Lisp code is often called a @dfn{library}. Thus,the ``Rmail library'' is a file containing code for Rmail mode.Similarly, a ``Lisp library directory'' is a directory of filescontaining Lisp code.@menu* How Programs Do Loading:: The @code{load} function and others.* Autoload:: Setting up a function to autoload.* Repeated Loading:: Precautions about loading a file twice.* Features:: Loading a library if it isn't already loaded.* Unloading:: How to ``unload'' a library that was loaded.* Hooks for Loading:: Providing code to be run when particular libraries are loaded.@end menu@node How Programs Do Loading@section How Programs Do Loading Emacs Lisp has several interfaces for loading. For example,@code{autoload} creates a placeholder object for a function in a file;trying to call the autoloading function loads the file to get thefunction's real definition (@pxref{Autoload}). @code{require} loads afile if it isn't already loaded (@pxref{Features}). Ultimately, allthese facilities call the @code{load} function to do the work.@defun load filename &optional missing-ok nomessage nosuffixThis function finds and opens a file of Lisp code, evaluates all theforms 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 @samp{.elc} appended. If such a file exists, it isloaded. If there is no file by that name, then @code{load} looks for afile named @file{@var{filename}.el}. If that file exists, it is loaded.Finally, if neither of those names is found, @code{load} looks for afile named @var{filename} with nothing appended, and loads it if itexists. (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 the optional argument @var{nosuffix} is non-@code{nil}, then thesuffixes @samp{.elc} and @samp{.el} are not tried. In this case, youmust specify the precise file name you want.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 directorieslisted in @code{load-path}, and loads the first file it finds whose namematches. The current default directory is tried only if it is specifiedin @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, andso on.If you get a warning that @file{foo.elc} is older than @file{foo.el}, itmeans you should consider recompiling @file{foo.el}. @xref{ByteCompilation}.Messages like @samp{Loading foo...} and @samp{Loading foo...done} appearin the echo area during loading unless @var{nomessage} isnon-@code{nil}.@cindex load errorsAny unhandled errors while loading a file terminate loading. If theload was done for the sake of @code{autoload}, any function definitionsmade during the loading are undone.@kindex file-errorIf @code{load} can't find the file to load, then normally it signals theerror @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}.@code{load} returns @code{t} if the file loads successfully.@end defun@ignore@deffn Command load-file filenameThis function loads the file @var{filename}. If @var{filename} is anabsolute file name, then it is loaded. If it is relative, then thecurrent default directory is assumed. @code{load-path} is not used, andsuffixes are not appended. Use this function if you wish to specifythe file to be loaded exactly.@end deffn@deffn Command load-library libraryThis function loads the library named @var{library}. A library isnothing more than a file that may be loaded as described earlier. Thisfunction is identical to @code{load}, save that it reads a file nameinteractively with completion.@end deffn@end ignore@defopt load-path@cindex @code{EMACSLOADPATH} environment variableThe value of this variable is a list of directories to search whenloading files with @code{load}. Each element is a string (which must bea directory name) or @code{nil} (which stands for the current workingdirectory). The value of @code{load-path} is initialized from theenvironment variable @code{EMACSLOADPATH}, if that exists; otherwise itsdefault value is specified in @file{emacs/src/paths.h} when Emacs isbuilt.The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};@samp{:} separates directory names, and @samp{.} is used for the currentdefault directory. Here is an example of how to set your@code{EMACSLOADPATH} variable from a @code{csh} @file{.login} file:@c This overfull hbox is OK. --rjc 16mar92@smallexamplesetenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp@end smallexampleHere is how to set it using @code{sh}:@smallexampleexport EMACSLOADPATHEMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp@end smallexampleHere is an example of code you can place in a @file{.emacs} file to addseveral directories to the front of your default @code{load-path}:@smallexample(setq load-path (append (list nil "/user/bil/emacs" "/usr/local/lisplib" (expand-file-name "~/emacs")) load-path))@end smallexample@c Wordy to rid us of an overfull hbox. --rjc 15mar92@noindentIn this example, the path searches the current working directory first,followed then by the @file{/user/bil/emacs} directory and then bythe @file{/usr/local/lisplib} directory,which are then followed by the standard directories for Lisp code.The command line options @samp{-l} or @samp{-load} specify a Lisplibrary to load as part of Emacs startup. Since this file might be inthe current directory, Emacs 18 temporarily adds the current directoryto the front of @code{load-path} so the file can be found there. NewerEmacs versions also find such files in the current directory, butwithout altering @code{load-path}.Dumping Emacs uses a special value of @code{load-path}. If the value of@code{load-path} at the end of dumping is unchanged (that is, still thesame special value), the dumped Emacs switches to the ordinary@code{load-path} value when it starts up, as decribed above. But if@code{load-path} has any other value at the end of dumping, that valueis used for execution of the dumped Emacs also.Therefore, if you want to change @code{load-path} temporarily forloading a few libraries in @file{site-init.el} or @file{site-load.el},you should bind @code{load-path} locally with @code{let} around thecalls to @code{load}.@end defopt@defvar load-in-progressThis variable is non-@code{nil} if Emacs is in the process of loading afile, and it is @code{nil} otherwise. This is how @code{defun} and@code{provide} determine whether a load is in progress, so that theireffect can be undone if the load fails.@end defvar To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}.@node Autoload@section Autoload@cindex autoload The @dfn{autoload} facility allows you to make a function or macroavailable but put off loading its actual definition. The first call tothe function automatically reads the proper file to install the realdefinition and other associated code, then runs the real definitionas if it had been loaded all along. There are two ways to set up an autoloaded function: by calling@code{autoload}, and by writing a special ``magic'' comment in thesource before the real definition. @code{autoload} is the low-levelprimitive for autoloading; any Lisp program can call @code{autoload} atany time. Magic comments do nothing on their own; they serve as a guidefor the command @code{update-file-autoloads}, which constructs calls to@code{autoload} and arranges to execute them when Emacs is built. Magiccomments are the most convenient way to make a function autoload, butonly for packages installed along with Emacs.@defun autoload function filename &optional docstring interactive typeThis function defines the function (or macro) named @var{function} so asto load automatically from @var{filename}. The string @var{filename}specifies the file to load to get the real definition of @var{function}.The argument @var{docstring} is the documentation string for thefunction. Normally, this is the identical to the documentation stringin the function definition itself. Specifying the documentation stringin the call to @code{autoload} makes it possible to look at thedocumentation without loading the function's real definition.If @var{interactive} is non-@code{nil}, then the function can be calledinteractively. This lets completion in @kbd{M-x} work without loadingthe function's real definition. The complete interactive specificationneed not be given here; it's not needed unless the user actually calls@var{function}, and when that happens, it's time to load the realdefinition.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 akeymap. Various parts of Emacs need to know this information withoutloading the real definition.@cindex function cell in autoloadIf @var{function} already has a non-void function definition that is notan autoload object, @code{autoload} does nothing and returns @code{nil}.If the function cell of @var{function} is void, or is already an autoloadobject, then it is defined as an autoload object like this:@example(autoload @var{filename} @var{docstring} @var{interactive} @var{type})@end exampleFor example, @example(symbol-function 'run-prolog) @result{} (autoload "prolog" 169681 t nil)@end example@noindentIn this case, @code{"prolog"} is the name of the file to load, 169681refers to the documentation string in the @file{emacs/etc/DOC} file(@pxref{Documentation Basics}), @code{t} means the function isinteractive, and @code{nil} that it is not a macro or a keymap.@end defun@cindex autoload errors The autoloaded file usually contains other definitions and may requireor provide one or more features. If the file is not completely loaded(due to an error in the evaluation of its contents), any functiondefinitions or @code{provide} calls that occurred during the load areundone. This is to ensure that the next attempt to call any functionautoloading from this file will try again to load the file. If not forthis, then some of the functions in the file might appear defined, butthey might fail to work properly for the lack of certain subroutinesdefined later in the file and not loaded successfully. If the autoloaded file fails to define the desired Lisp function ormacro, then an error is signaled with data @code{"Autoloading failed todefine function @var{function-name}"}.@findex update-file-autoloads@findex update-directory-autoloads A magic autoload comment looks like @samp{;;;###autoload}, on a lineby itself, just before the real definition of the function in itsautoloadable source file. The command @kbd{M-x update-file-autoloads}writes a corresponding @code{autoload} call into @file{loaddefs.el}.Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.@kbd{M-x update-directory-autoloads} is even more powerful; it updatesautoloads for all files in the current directory. The same magic comment can copy any kind of form into@file{loaddefs.el}. If the form following the magic comment is not afunction definition, it is copied verbatim. You can also use a magiccomment to execute a form at build time @emph{without} executing it whenthe file itself is loaded. To do this, write the form @dfn{on the sameline} as the magic comment. Since it is in a comment, it does nothingwhen you load the source file; but @code{update-file-autoloads} copiesit to @file{loaddefs.el}, where it is executed while building Emacs. The following example shows how @code{doctor} is prepared forautoloading with a magic comment:@smallexample;;;###autoload(defun doctor () "Switch to *doctor* buffer and start giving psychotherapy." (interactive) (switch-to-buffer "*doctor*") (doctor-mode))@end smallexample@noindentHere's what that produces in @file{loaddefs.el}:@smallexample(autoload 'doctor "doctor" "\Switch to *doctor* buffer and start giving psychotherapy." t)@end smallexample@noindentThe backslash and newline immediately following the double-quote are aconvention used only in the preloaded Lisp files such as@file{loaddefs.el}; they tell @code{make-docfile} to put thedocumentation string in the @file{etc/DOC} file. @xref{Building Emacs}.@node Repeated Loading@comment node-name, next, previous, up@section Repeated Loading@cindex repeated loading You may load one file more than once in an Emacs session. Forexample, after you have rewritten and reinstalled a function definitionby editing it in a buffer, you may wish to return to the originalversion; 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 filerather than a non-compiled file of similar name. If you rewrite a filethat you intend to save and reinstall, remember to byte-compile it ifnecessary; otherwise you may find yourself inadvertently reloading theolder, byte-compiled file instead of your newer, non-compiled file! When writing the forms in a Lisp library file, keep in mind that thefile might be loaded more than once. For example, the choice of@code{defvar} vs.@: @code{defconst} for defining a variable depends onwhether it is desirable to reinitialize the variable if the library isreloaded: @code{defconst} does so, and @code{defvar} does not.(@xref{Defining Variables}.) The simplest way to add an element to an alist is like this:@example(setq minor-mode-alist (cons '(leif-mode " Leif") minor-mode-alist))@end example@noindentBut this would add multiple elements if the library is reloaded.To avoid the problem, write this:@example(or (assq 'leif-mode minor-mode-alist) (setq minor-mode-alist (cons '(leif-mode " Leif") minor-mode-alist)))@end example Occasionally you will want to test explicitly whether a library hasalready been loaded. Here's one way to test, in a library, whether ithas been loaded before:@example(if (not (boundp 'foo-was-loaded)) @var{execute-first-time-only})(setq foo-was-loaded t)@end example@noindentIf the library uses @code{provide} to provide a named feature, you canuse @code{featurep} to test whether the library has been loaded.@ifinfo@xref{Features}.@end ifinfo@node 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 ofnamed @dfn{features}. Autoloading is triggered by calling a specificfunction, but a feature is loaded the first time another program asksfor 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} thefeature. Another program that uses them may ensure they are defined by@dfn{requiring} the feature. This loads the file of definitions if ithasn't been loaded already. To require the presence of a feature, call @code{require} with thefeature name as argument. @code{require} looks in the global variable@code{features} to see whether the desired feature has been providedalready. If not, it loads the feature from the appropriate file. Thisfile should call @code{provide} at the top level to add the feature to@code{features}; if it fails to do so, @code{require} signals an error.@cindex load error with require Features are normally named after the files that provide them, so that@code{require} need not be given the file name. For example, in @file{emacs/lisp/prolog.el}, the definition for @code{run-prolog} includes the following code:@smallexample(defun run-prolog () "Run an inferior Prolog process, input and output via buffer *prolog*." (interactive) (require 'comint) (switch-to-buffer (make-comint "prolog" prolog-program-name)) (inferior-prolog-mode))@end smallexample@noindentThe expression @code{(require 'comint)} loads the file @file{comint.el}if it has not yet been loaded. This ensures that @code{make-comint} isdefined.The @file{comint.el} file contains the following top-level expression:@smallexample(provide 'comint)@end smallexample@noindentThis adds @code{comint} to the global @code{features} list, so that@code{(require 'comint)} will henceforth know that nothing needs to bedone.@cindex byte-compiling @code{require} When @code{require} is used at top level in a file, it takes effectwhen you byte-compile that file (@pxref{Byte Compilation}) as well aswhen you load it. This is in case the required package contains macrosthat the byte compiler must know about. Although top-level calls to @code{require} are evaluated duringbyte compilation, @code{provide} calls are not. Therefore, you canensure that a file of definitions is loaded before it is byte-compiledby including a @code{provide} followed by a @code{require} for the samefeature, as in the following example.@smallexample@group(provide 'my-feature) ; @r{Ignored by byte compiler,} ; @r{evaluated by @code{load}.}(require 'my-feature) ; @r{Evaluated by byte compiler.}@end group@end smallexample@noindentThe compiler ignores the @code{provide}, then processes the@code{require} by loading the file in question. Loading the file doesexecute the @code{provide} call, so the subsequent @code{require} calldoes nothing while loading.@defun provide featureThis function announces that @var{feature} is now loaded, or beingloaded, into the current Emacs session. This means that the facilitiesassociated with @var{feature} are or will be available for other Lispprograms.The direct effect of calling @code{provide} is to add @var{feature} tothe front of the list @code{features} if it is not already in the list.The argument @var{feature} must be a symbol. @code{provide} returns@var{feature}.@smallexamplefeatures @result{} (bar bish)(provide 'foo) @result{} foofeatures @result{} (foo bar bish)@end smallexampleIf the file isn't completely loaded, due to an error in the evaluatingits contents, any function definitions or @code{provide} calls thatoccurred during the load are undone. @xref{Autoload}.@end defun@defun require feature &optional filenameThis function checks whether @var{feature} is present in the currentEmacs session (using @code{(featurep @var{feature})}; see below). If itis not, 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 file name to load.If loading the file fails to provide @var{feature}, @code{require}signals an error, @samp{Required feature @var{feature} was notprovided}.@end defun@defun featurep featureThis function returns @code{t} if @var{feature} has been provided in thecurrent Emacs session (i.e., @var{feature} is a member of@code{features}.)@end defun@defvar featuresThe value of this variable is a list of symbols that are the featuresloaded in the current Emacs session. Each symbol was put in this listwith a call to @code{provide}. The order of the elements in the@code{features} list is not significant.@end defvar@node Unloading@section Unloading@cindex unloading@c Emacs 19 feature You can discard the functions and variables loaded by a library toreclaim memory for other Lisp objects. To do this, use the function@code{unload-feature}:@deffn Command unload-feature feature &optional forceThis command unloads the library that provided feature @var{feature}.It undefines all functions, macros, and variables defined in thatlibrary with @code{defconst}, @code{defvar}, @code{defun},@code{defmacro}, @code{defsubst} and @code{defalias}. It then restoresany autoloads formerly associated with those symbols.Ordinarily, @code{unload-feature} refuses to unload a library on whichother loaded libraries depend. (A library @var{a} depends on library@var{b} if @var{a} contains a @code{require} for @var{b}.) If theoptional argument @var{force} is non-@code{nil}, dependencies areignored and you can unload any library.@end deffn The @code{unload-feature} function is written in Lisp; its actions arebased on the variable @code{load-history}.@defvar load-historyThis variable's value is an alist connecting library names with thenames of functions and variables they define, the features they provide,and the features they require.Each element is a list and describes one library. The @sc{car} of thelist is the name of the library, as a string. The rest of the list iscomposed of these kinds of objects:@itemize @bullet@itemSymbols that were defined by this library.@itemLists of the form @code{(require . @var{feature})} indicatingfeatures that were required.@itemLists of the form @code{(provide . @var{feature})} indicatingfeatures that were provided.@end itemizeThe 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 soby adding the symbols defined to the element for the file being visited,rather than replacing that element.@node Hooks for Loading@section Hooks for Loading@cindex loading hooks@cindex hooks for loadingYou can ask for code to be executed if and when a particular library isloaded, by calling @code{eval-after-load}.@defun eval-after-load library formThis function arranges to evaluate @var{form} at the end of loading thelibrary @var{library}, if and when @var{library} is loaded. If@var{library} is already loaded, it evaluates @var{form} right away.The library name @var{library} must exactly match the argument of@code{load}. To get the proper results when an installed library isfound by searching @code{load-path}, you should not include anydirectory names in @var{library}.An error in @var{form} does not undo the load, but does preventexecution of the rest of @var{form}.@end defunIn general, well-designed Lisp programs should not use this feature.The clean and modular ways to interact with a Lisp library are (1)examine and set the library's variables (those which are meant foroutside use), and and (2) call the library's functions. If you wish todo (1), you can do it immediately---there is no need to wait for whenthe library is loaded. To do (2), you must load the library (preferablywith @code{require}).But it is to use @code{eval-after-load} in your personal customizationsif you don't feel they must meet the design standards of programs to bereleased.@defvar after-load-alistAn alist of expressions to evaluate if and when particular libraries areloaded. Each element looks like this:@example(@var{filename} @var{forms}@dots{})@end exampleThe function @code{load} checks @code{after-load-alist} in order toimplement @code{eval-after-load}.@end defvar@c Emacs 19 feature