@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.@c See the file elisp.texi for copying conditions.@setfilename ../info/loading@node Loading, Byte Compilation, Customization, Top@chapter Loading@cindex loading@cindex library@cindex Lisp library Loading a file of Lisp code means bringing its contents into the 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-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.* Load Suffixes:: Details about the suffixes that @code{load} tries.* Library Search:: Finding a library to load.* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files.* Autoload:: Setting up a function to autoload.* Repeated Loading:: Precautions about loading a file twice.* Named Features:: Loading a library if it isn't already loaded.* Where Defined:: Finding which file defined a certain symbol.* Unloading:: How to "unload" a library that was loaded.* Hooks for Loading:: Providing code to be run when particular libraries are loaded.@end menu@node How Programs Do Loading@section How Programs Do Loading Emacs Lisp has several interfaces for loading. For example,@code{autoload} creates a placeholder object for a function defined in 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 the extension @samp{.elc} appended. If such afile exists, it is loaded. If there is no file by that name, then@code{load} looks for a file named @file{@var{filename}.el}. If thatfile exists, it is loaded. Finally, if neither of those names isfound, @code{load} looks for a file named @var{filename} with nothingappended, and loads it if it exists. (The @code{load} function is notclever about looking at @var{filename}. In the perverse case of afile named @file{foo.el.el}, evaluation of @code{(load "foo.el")} willindeed find it.)If Auto Compression mode is enabled, as it is by default, then if@code{load} can not find a file, it searches for a compressed versionof the file before trying other file names. It decompresses and loadsit if it exists. It looks for compressed versions by appending eachof the suffixes in @code{jka-compr-load-suffixes} to the file name.The value of this variable must be a list of strings. Its standardvalue is @code{(".gz")}.If the optional argument @var{nosuffix} is non-@code{nil}, then@code{load} does not try the suffixes @samp{.elc} and @samp{.el}. Inthis case, you must specify the precise file name you want, exceptthat, if Auto Compression mode is enabled, @code{load} will still use@code{jka-compr-load-suffixes} to find compressed versions. Byspecifying the precise file name and using @code{t} for@var{nosuffix}, you can prevent perverse file names such as@file{foo.el.el} from being tried.If the optional argument @var{must-suffix} is non-@code{nil}, then@code{load} insists that the file name used must end in either@samp{.el} or @samp{.elc} (possibly extended with a compressionsuffix), unless it contains an explicit directory name.If @var{filename} is a relative file name, such as @file{foo} or@file{baz/foo.bar}, @code{load} searches for the file using the variable@code{load-path}. It appends @var{filename} to each of the 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.This command does not use @code{load-path}, and does not appendsuffixes. However, it does look for compressed versions (if AutoCompression Mode is enabled). Use this command if you wish to specifyprecisely 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-function@anchor{Definition of load-read-function}@c do not allow page break at anchor; work around Texinfo deficiency.This variable specifies an alternate expression-reading function for@code{load} and @code{eval-region} to use instead of @code{read}.The function should accept one argument, just as @code{read} does.Normally, the variable's value is @code{nil}, which means 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{Definition of eval-region,, Eval}.@end defvar For information about how @code{load} is used in building Emacs, see@ref{Building Emacs}.@node Load Suffixes@section Load SuffixesWe now describe some technical details about the exact suffixes that@code{load} tries.@defvar load-suffixesThis is a list of suffixes indicating (compiled or source) Emacs Lispfiles. It should not include the empty string. @code{load} usesthese suffixes in order when it appends Lisp suffixes to the specifiedfile name. The standard value is @code{(".elc" ".el")} which producesthe behavior described in the previous section.@end defvar@defvar load-file-rep-suffixesThis is a list of suffixes that indicate representations of the samefile. This list should normally start with the empty string.When @code{load} searches for a file it appends the suffixes in thislist, in order, to the file name, before searching for another file.Enabling Auto Compression mode appends the suffixes in@code{jka-compr-load-suffixes} to this list and disabling AutoCompression mode removes them again. The standard value of@code{load-file-rep-suffixes} if Auto Compression mode is disabled is@code{("")}. Given that the standard value of@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard valueof @code{load-file-rep-suffixes} if Auto Compression mode is enabledis @code{("" ".gz")}.@end defvar@defun get-load-suffixesThis function returns the list of all suffixes that @code{load} shouldtry, in order, when its @var{must-suffix} argument is non-@code{nil}.This takes both @code{load-suffixes} and @code{load-file-rep-suffixes}into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes}and @code{load-file-rep-suffixes} all have their standard values, thisfunction returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if AutoCompression mode is enabled and @code{(".elc" ".el")} if AutoCompression mode is disabled.@end defunTo summarize, @code{load} normally first tries the suffixes in thevalue of @code{(get-load-suffixes)} and then those in@code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil},it skips the former group, and if @var{must-suffix} is non-@code{nil},it skips the latter group.@node Library Search@section Library Search@cindex library search@cindex find library When Emacs loads a Lisp library, it searches for the 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/epaths.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@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 variable@code{load-suffixes} specifies the exact required suffixes.)The argument @var{docstring} is the documentation string for thefunction. Specifying the documentation string in the call to@code{autoload} makes it possible to look at the documentation withoutloading the function's real definition. Normally, this should beidentical to the documentation string in the function definitionitself. If it isn't, the function definition's documentation stringtakes effect when it is loaded.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@cindex magic autoload comment@cindex autoload cookie@anchor{autoload cookie} A magic autoload comment (often called an @dfn{autoload cookie})consists of @samp{;;;###autoload}, on a line by itself,just before the real definition of the function in 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 (quote doctor) "doctor" "\Switch to *doctor* buffer and start giving psychotherapy.\(fn)" t nil)@end smallexample@noindent@cindex @code{fn} in function's documentation stringThe 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}. @samp{(fn)}in the usage part of the documentation string is replaced with thefunction's name when the various help functions (@pxref{HelpFunctions}) display it. 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(push '(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) (push '(leif-mode " Leif") minor-mode-alist))@end example@noindentor this:@example(add-to-list '(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(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}. The idea of subfeatures is that you use them when apackage (which is one @var{feature}) is complex enough to make ituseful to give names to various parts or functionalities of thepackage, which might or might not be loaded, or might or might not bepresent in a given version. @xref{Network Feature Testing}, foran example.@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 @samp{.el} or @samp{.elc} suffix (possibly extended witha compression suffix); a file whose name is just @var{feature} won'tbe used. (The variable @code{load-suffixes} specifies the exactrequired Lisp suffixes.)If @var{noerror} is non-@code{nil}, that suppresses errors from actualloading of the file. In that case, @code{require} returns @code{nil}if loading the file fails. Normally, @code{require} returns@var{feature}.If loading the file succeeds but does not provide @var{feature},@code{require} signals an error, @samp{Required feature @var{feature}was not provided}.@end defun@defun featurep feature &optional 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 Where Defined@section Which File Defined a Certain Symbol@defun symbol-file symbol &optional typeThis function returns the name of the file that defined @var{symbol}.If @var{type} is @code{nil}, then any kind of definition isacceptable. If @var{type} is @code{defun} or @code{defvar}, thatspecifies function definition only or variable definition only.The value is normally an absolute file name. It can also be@code{nil}, if the definition is not associated with any file.@end defun The basis for @code{symbol-file} is the data in the variable@code{load-history}.@defvar load-historyThis variable's value is an alist connecting library file 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 absolute file name of the library, as a string. The restof the list elements have these forms:@table @code@item @var{var}The symbol @var{var} was defined as a variable.@item (defun . @var{fun})The function @var{fun} was defined.@item (t . @var{fun})The function @var{fun} was previously an autoload before this libraryredefined it as a function. The following element is always@code{(defun . @var{fun})}, which represents defining @var{fun} as afunction.@item (autoload . @var{fun})The function @var{fun} was defined as an autoload.@item (require . @var{feature})The feature @var{feature} was required.@item (provide . @var{feature})The feature @var{feature} was provided.@end 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}.@node Unloading@section Unloading@cindex unloading packages@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 unload-feature-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 loadingthe file @var{library}, each time @var{library} is loaded. If@var{library} is already loaded, it evaluates @var{form} right away.Don't forget to quote @var{form}!You don't need to give a directory or extension in the file name@var{library}---normally you just give a bare file name, like this:@example(eval-after-load "edebug" '(def-edebug-spec c-point t))@end exampleTo restrict which files can trigger the evaluation, include adirectory or an extension or both in @var{library}. Only a file whoseabsolute true name (i.e., the name with all symbolic links chased out)matches all the given name components will match. In the followingexample, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory@code{..../foo/bar} will trigger the evaluation, but not@file{my_inst.el}:@example(eval-after-load "foo/bar/my_inst.elc" @dots{})@end example@var{library} can also be a feature (i.e.@: a symbol), in which case@var{form} is evaluated when @code{(provide @var{library})} is called.An error in @var{form} does not undo the load, but does 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, an alist built by @code{eval-after-load}, holds theexpressions to evaluate when particular libraries are loaded. Eachelement looks like this:@example(@var{regexp-or-feature} @var{forms}@dots{})@end exampleThe key @var{regexp-or-feature} is either a regular expression or asymbol, and the value is a list of forms. The forms are evaluated whenthe key matches the absolute true name of the file being@code{load}ed or the symbol being @code{provide}d.@end defvar@ignore arch-tag: df731f89-0900-4389-a436-9105241b6f7a@end ignore