@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999@c Free Software Foundation, Inc.@c See the file elisp.texi for copying conditions.@setfilename ../info/loading@node Loading, Byte Compilation, Customization, Top@chapter Loading@cindex loading@cindex library@cindex Lisp library Loading a file of Lisp code means bringing its contents into the 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.* 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.* Unloading:: How to ``unload'' a library that was loaded.* Hooks for Loading:: Providing code to be run when particular libraries are loaded.@end menu@node How Programs Do Loading@section How Programs Do Loading Emacs Lisp has several interfaces for loading. For example,@code{autoload} creates a placeholder object for a function defined in afile; 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{Named Features}). Ultimately,all these facilities call the @code{load} function to do the work.@defun load filename &optional missing-ok nomessage nosuffix must-suffixThis 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. By specifying the precisefile name and using @code{t} for @var{nosuffix}, you can preventperverse file names such as @file{foo.el.el} from being tried.If the optional argument @var{must-suffix} is non-@code{nil}, then@code{load} insists that the file name used must end in either@samp{.el} or @samp{.elc}, unless it contains an explicit directoryname. If @var{filename} does not contain an explicit directory name,and does not end in a suffix, then @code{load} insists on adding one.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. @xref{Library Search}.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}.When loading a source file (not compiled), @code{load} performscharacter set translation just as Emacs would do when visiting the file.@xref{Coding Systems}.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}.You can use the variable @code{load-read-function} to specify a functionfor @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 filenameThis command loads the file @var{filename}. If @var{filename} is arelative file name, then the current default directory is assumed.@code{load-path} is not used, and suffixes are not appended. Use thiscommand if you wish to specify precisely the file name to load.@end deffn@deffn Command load-library libraryThis command loads the library named @var{library}. It is equivalent to@code{load}, except in how it reads its argument interactively.@end deffn@defvar load-in-progressThis variable is non-@code{nil} if Emacs is in the process of loading afile, and it is @code{nil} otherwise.@end defvar@defvar load-read-functionThis variable specifies an alternate expression-reading function for@code{load} and @code{eval-region} to use instead of @code{read}.The function should accept one argument, just as @code{read} does.Normally, the variable's value is @code{nil}, which means thosefunctions should use @code{read}.Instead of using this variable, it is cleaner to use another, newerfeature: to pass the function as the @var{read-function} argument to@code{eval-region}. @xref{Eval}.@end defvar For information about how @code{load} is used in building Emacs, see@ref{Building Emacs}.@node Library Search@section Library Search When Emacs loads a Lisp library, it searches for the libraryin a list of directories specified by the variable @code{load-path}.@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).@end defopt The value of @code{load-path} is initialized from the environmentvariable @code{EMACSLOADPATH}, if that exists; otherwise its defaultvalue is specified in @file{emacs/src/paths.h} when Emacs is built.Then the list is expanded by adding subdirectories of the directoriesin the list. The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};@samp{:} (or @samp{;}, according to the operating system) separatesdirectory names, and @samp{.} is used for the current default directory.Here is an example of how to set your @code{EMACSLOADPATH} variable froma @code{csh} @file{.login} file:@smallexamplesetenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp@end smallexample Here is how to set it using @code{sh}:@smallexampleexport EMACSLOADPATHEMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp@end smallexample Here is an example of code you can place in your init file (@pxref{InitFile}) to add several directories to the front of your default@code{load-path}:@smallexample@group(setq load-path (append (list nil "/user/bil/emacs" "/usr/local/lisplib" "~/emacs") load-path))@end group@end smallexample@c Wordy to rid us of an overfull hbox. --rjc 15mar92@noindentIn this example, the path searches the current working directory first,followed then by the @file{/user/bil/emacs} directory, the@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,which are then followed by the standard directories for Lisp code. Dumping Emacs uses a special value of @code{load-path}. If the value of@code{load-path} at the end of dumping is unchanged (that is, still thesame special value), the dumped Emacs switches to the ordinary@code{load-path} value when it starts up, as described above. But if@code{load-path} has any other value at the end of dumping, that 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}. The default value of @code{load-path}, when running an Emacs which hasbeen installed on the system, includes two special directories (andtheir subdirectories as well):@smallexample"/usr/local/share/emacs/@var{version}/site-lisp"@end smallexample@noindentand@smallexample"/usr/local/share/emacs/site-lisp"@end smallexample@noindentThe first one is for locally installed packages for a particular Emacsversion; the second is for locally installed packages meant for use withall installed Emacs versions. There are several reasons why a Lisp package that works well in oneEmacs version can cause trouble in another. Sometimes packages needupdating for incompatible changes in Emacs; sometimes they depend onundocumented internal Emacs data that can change without notice;sometimes a newer Emacs version incorporates a version of the package,and should be used only with that version. Emacs finds these directories' subdirectories and adds them to@code{load-path} when it starts up. Both immediate subdirectories andsubdirectories multiple levels down are added to @code{load-path}. Not all subdirectories are included, though. Subdirectories whosenames do not start with a letter or digit are excluded. Subdirectoriesnamed @file{RCS} or @file{CVS} are excluded. Also, a subdirectory whichcontains a file named @file{.nosearch} is excluded. You can use thesemethods to prevent certain subdirectories of the @file{site-lisp}directories from being searched. If you run Emacs from the directory where it was built---that is, anexecutable that has not been formally installed---then @code{load-path}normally contains two additional directories. These are the @code{lisp}and @code{site-lisp} subdirectories of the main build directory. (Bothare represented as absolute file names.)@deffn Command locate-library library &optional nosuffix path interactive-callThis command finds the precise file name for library @var{library}. Itsearches for the library in the same way @code{load} does, and theargument @var{nosuffix} has the same meaning as in @code{load}: don'tadd 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 usedinstead of @code{load-path}.When @code{locate-library} is called from a program, it returns the filename as a string. When the user runs @code{locate-library}interactively, the argument @var{interactive-call} is @code{t}, and thistells @code{locate-library} to display the file name in the echo area.@end deffn@defvar load-suffixesThis variable is a list of suffixes (strings) that @code{load} shouldtry adding to the specified file name. The default value is@code{(".elc" ".el")}. There is no need to include the null suffix.@end defvar@node Loading Non-ASCII@section Loading Non-@acronym{ASCII} Characters When Emacs Lisp programs contain string constants with non-@acronym{ASCII}characters, these can be represented within Emacs either as unibytestrings or as multibyte strings (@pxref{Text Representations}). Whichrepresentation is used depends on how the file is read into Emacs. Ifit is read with decoding into multibyte representation, the text of theLisp program will be multibyte text, and its string constants will bemultibyte strings. If a file containing Latin-1 characters (forexample) is read without decoding, the text of the program will beunibyte text, and its string constants will be unibyte strings.@xref{Coding Systems}. To make the results more predictable, Emacs always performs decodinginto the multibyte representation when loading Lisp files, even if itwas started with the @samp{--unibyte} option. This means that stringconstants with non-@acronym{ASCII} characters translate into multibytestrings. The only exception is when a particular file specifies nodecoding. The reason Emacs is designed this way is so that Lisp programs givepredictable results, regardless of how Emacs was started. In addition,this enables programs that depend on using multibyte text to work evenin a unibyte Emacs. Of course, such programs should be designed tonotice whether the user prefers unibyte or multibyte text, by checking@code{default-enable-multibyte-characters}, and convert representationsappropriately. In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings aremultibyte strings should not be noticeable, since inserting them inunibyte buffers converts them to unibyte automatically. However, ifthis does make a difference, you can force a particular Lisp file to beinterpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in acomment on the file's first line. With that designator, the file willunconditionally be interpreted as unibyte, even in an ordinarymultibyte Emacs session. This can matter when making keybindings tonon-@acronym{ASCII} characters written as @code{?v@var{literal}}.@node Autoload@section Autoload@cindex autoload The @dfn{autoload} facility allows you to make a function or macroknown in Lisp, but put off loading the file that defines it. The firstcall to the function automatically reads the proper file to install thereal definition 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 are the most convenient way to make a functionautoload, for packages installed along with Emacs. These comments donothing on their own, but they serve as a guide for the command@code{update-file-autoloads}, which constructs calls to @code{autoload}and arranges to execute them when Emacs is built.@defun autoload function filename &optional docstring interactive 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}.If @var{filename} does not contain either a directory name, or thesuffix @code{.el} or @code{.elc}, then @code{autoload} insists on addingone of these suffixes, and it will not load from a file whose name isjust @var{filename} with no added suffix.The argument @var{docstring} is the documentation string for thefunction. Normally, this should be 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}, that says @var{function} can becalled interactively. This lets completion in @kbd{M-x} work withoutloading @var{function}'s real definition. The complete interactivespecification is not given here; it's not needed unless the useractually calls @var{function}, and when that happens, it's time to loadthe real definition.You can autoload macros and keymaps as well as ordinary functions.Specify @var{type} as @code{macro} if @var{function} is really a macro.Specify @var{type} as @code{keymap} if @var{function} is really akeymap. Various parts of Emacs need to know this information withoutloading the real definition.An autoloaded keymap loads automatically during key lookup when a prefixkey's binding is the symbol @var{function}. Autoloading does not occurfor other kinds of access to the keymap. In particular, it does nothappen when a Lisp program gets the keymap from the value of a variableand calls @code{define-key}; not even if the variable name is the samesymbol @var{function}.@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@group(symbol-function 'run-prolog) @result{} (autoload "prolog" 169681 t nil)@end group@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-@var{version}} file (@pxref{Documentation Basics}),@code{t} means the function is interactive, and @code{nil} that it isnot 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 be defined by theaborted load, but fail to work properly for the lack of certainsubroutines not loaded successfully because they come later in the file. 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 consists of @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-defining form or a @code{defcustom} form, it is copiedverbatim. ``Function-defining forms'' include @code{define-skeleton},@code{define-derived-mode}, @code{define-generic-mode} and@code{define-minor-mode} as well as @code{defun} and@code{defmacro}. To save space, a @code{defcustom} form is converted toa @code{defvar} in @file{loaddefs.el}, with some additional informationif it uses @code{:require}. You can also use a magic comment to execute a form at build time@emph{without} executing it when the file itself is loaded. To do this,write the form @emph{on the same line} as the magic comment. Since itis in a comment, it does nothing when you load the source file; but@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, whereit 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 uncompiled 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}.See also the commentary in @file{lib-src/make-docfile.c}. If you write a function definition with an unusual macro that is notone of the known and recognized function definition methods, use of anordinary magic autoload comment would copy the whole definition into@code{loaddefs.el}. That is not desirable. You can put the desired@code{autoload} call into @code{loaddefs.el} instead by writing this:@smallexample;;;###autoload (autoload 'foo "myfile")(mydefunmacro foo ...)@end smallexample@node Repeated Loading@section Repeated Loading@cindex repeated loading You can load a given file more than once in an Emacs session. 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, you need to byte-compile the newversion; otherwise Emacs will load the older, byte-compiled file insteadof your newer, non-compiled file! If that happens, the messagedisplayed when loading the file includes, @samp{(compiled; note, source isnewer)}, to remind you to recompile it. When writing the forms in a Lisp library file, keep in mind that thefile might be loaded more than once. For example, think about whethereach variable should be reinitialized when you reload the library;@code{defvar} does not change the value if the variable is alreadyinitialized. (@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 To add an element to a list just once, you can also use @code{add-to-list}(@pxref{Setting Variables}). 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(defvar foo-was-loaded nil)(unless 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} earlier in the file to test whether the@code{provide} call has been executed before.@ifnottex@xref{Named Features}.@end ifnottex@node Named Features@section Features@cindex features@cindex requiring features@cindex providing features @code{provide} and @code{require} are an alternative to@code{autoload} for loading files automatically. They work in terms 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 For example, in @file{emacs/lisp/prolog.el},the definition for @code{run-prolog} includes the following code:@smallexample(defun run-prolog () "Run an inferior Prolog process, with I/O via buffer *prolog*." (interactive) (require 'comint) (switch-to-buffer (make-comint "prolog" prolog-program-name)) (inferior-prolog-mode))@end smallexample@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. Features are normally named after the files that provide them,so that @code{require} need not be given the file name.The @file{comint.el} file contains the following top-level expression:@smallexample(provide 'comint)@end smallexample@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. It also avoids byte-compilerwarnings for functions and variables defined in the file loaded with@code{require}. 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 when the file is loaded.@defun provide feature &optional subfeaturesThis 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}.If provided, @var{subfeatures} should be a list of symbols indicatinga set of specific subfeatures provided by this version of @var{feature}.You can test the presence of a subfeature using @code{featurep}.@smallexamplefeatures @result{} (bar bish)(provide 'foo) @result{} foofeatures @result{} (foo bar bish)@end smallexampleWhen a file is loaded to satisfy an autoload, and it stops due to anerror 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 noerrorThis function checks whether @var{feature} is present in the currentEmacs session (using @code{(featurep @var{feature})}; see below). Theargument @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 ofthe 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 suffix; a file whose name is just @var{feature} won't beused.If loading the file fails to provide @var{feature}, @code{require}signals an error, @samp{Required feature @var{feature} was notprovided}, unless @var{noerror} is non-@code{nil}.@end defun@defun featurep feature &optional subfeatureThis function returns @code{t} if @var{feature} has been provided inthe current Emacs session (i.e.@:, if @var{feature} is a member of@code{features}.) If @var{subfeature} is non-@code{nil}, then thefunction 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 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{defun}, @code{defalias}, @code{defsubst},@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.It then restores any autoloads formerly associated with those symbols.(Loading saves these in the @code{autoload} property of the symbol.)@vindex unload-feature-special-hooksBefore restoring the previous definitions, @code{unload-feature} runs@code{remove-hook} to remove functions in the library from certainhooks. These hooks include variables whose names end in @samp{hook}or @samp{-hooks}, plus those listed in@code{unload-feature-special-hooks}. This is to prevent Emacs fromceasing to function because important hooks refer to functions thatare no longer defined.@vindex @var{feature}-unload-hookIf these measures are not sufficient to prevent malfunction, a librarycan define an explicit unload hook. If @code{@var{feature}-unload-hook}is defined, it is run as a normal hook before restoring the previousdefinitions, @emph{instead of} the usual hook-removing actions. Theunload hook ought to undo all the global state changes made by thelibrary that might cease to work once the library is unloaded.@code{unload-feature} can cause problems with libraries that fail to dothis, so it should be used with caution.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 listelements have these forms:@table @code@item @var{fun}The function @var{fun} was defined by this library.@item (t . @var{fun})The function @var{fun} was previously an autoload before this libraryredefined it as a function. The following element is always thesymbol @var{fun}, which signifies that the library defined @var{fun}as a function.@item (autoload . @var{fun})The function @var{fun} was defined as an autoload.@item (defvar . @var{var})The symbol @var{var} was defined as a variable.@item (require . @var{feature})The feature @var{feature} was required.@item (provide . @var{feature})The feature @var{feature} was provided.@end tableThe 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. @xref{Eval}. Preloaded libraries don't contribute initially to @code{load-history}.Instead, preloading writes information about preloaded libraries into afile, which can be loaded later on to add information to@code{load-history} describing the preloaded files. This file isinstalled in @code{exec-directory} and has a name of the form@file{fns-@var{emacsversion}.el}.@findex symbol-file See the source for the function @code{symbol-file}, for an example ofcode that loads this file to find functions in preloaded libraries.@defvar loadhist-special-hooksThis variable holds a list of hooks to be scanned before unloading alibrary, to remove functions defined in the library.@end defvar@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.If @var{library} is a string, it must exactly match the argument of@code{load} used to load the library. To get the proper results when aninstalled library is found by searching @code{load-path}, you should notinclude any directory names in @var{library}.@var{library} can also be a feature (i.e.@: a symbol), in which case@var{form} is evaluated when @code{(provide @var{library})} is called.An error in @var{form} does not undo the load, but does 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 (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 OK to use @code{eval-after-load} in your personalcustomizations if you don't feel they must meet the design standards forprograms meant for wider use.@defvar after-load-alistThis variable holds an alist of expressions to evaluate if and whenparticular libraries are loaded. 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@ignore arch-tag: df731f89-0900-4389-a436-9105241b6f7a@end ignore