@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003,
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/loading
@node Loading, Byte Compilation, Customization, Top
file, reads the text, evaluates each form, and then closes the file.
The load functions evaluate all the expressions in a file just
-as the @code{eval-current-buffer} function evaluates all the
+as the @code{eval-buffer} function evaluates all the
expressions in a buffer. The difference is that the load functions
read and evaluate the text in the file as found on disk, not the text
in an Emacs buffer.
containing 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.
-* 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.
+* 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
file if it isn't already loaded (@pxref{Named Features}). Ultimately,
all these facilities call the @code{load} function to do the work.
-@defun load filename &optional missing-ok nomessage nosuffix
+@defun load filename &optional missing-ok nomessage nosuffix must-suffix
This function finds and opens a file of Lisp code, evaluates all the
forms in it, and closes the file.
@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 the
-suffixes @samp{.elc} and @samp{.el} are not tried. In this case, you
-must specify the precise file name you want. By specifying 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 Auto Compression mode is enabled, as it is by default, then
+if @code{load} can not find a file, it searches for a compressed
+version of the file before trying other file names. It decompresses
+and loads it if it exists. It looks for compressed versions by
+appending the suffixes in @code{jka-compr-load-suffixes} to the file
+name. The value of this variable must be a list of strings. Its
+standard value is @code{(".gz")}.
+
+If the optional argument @var{nosuffix} is non-@code{nil}, then
+@code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In
+this case, you must specify the precise file name you want, except
+that, if Auto Compression mode is enabled, @code{load} will still use
+@code{jka-compr-load-suffixes} to find compressed versions. By
+specifying the precise file name and using @code{t} for
+@var{nosuffix}, you can prevent 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 compression
+suffix), 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
in @code{load-path}, where @code{nil} stands for the default directory.
@code{load} tries all three possible suffixes in the first directory in
@code{load-path}, then all three suffixes in the second directory, and
-so on.
+so on. @xref{Library Search}.
If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
means you should consider recompiling @file{foo.el}. @xref{Byte
@deffn Command load-file filename
This command loads the file @var{filename}. If @var{filename} is a
relative file name, then the current default directory is assumed.
-@code{load-path} is not used, and suffixes are not appended. Use this
-command if you wish to specify the file to be loaded exactly.
+This command does not use @code{load-path}, and does not append
+suffixes. However, it does look for compressed versions (if Auto
+Compression Mode is enabled). Use this command if you wish to specify
+precisely the file name to load.
@end deffn
@deffn Command load-library library
@code{load}, except in how it reads its argument interactively.
@end deffn
+@defvar load-in-progress
+This variable is non-@code{nil} if Emacs is in the process of loading a
+file, and it is @code{nil} otherwise.
+@end defvar
+
+@defvar load-read-function
+This
+@anchor{Definition of load-read-function}
+@c do not allow page break at anchor; work around Texinfo deficiency.
+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 those
+functions should use @code{read}.
+
+Instead of using this variable, it is cleaner to use another, newer
+feature: to pass the function as the @var{read-function} argument to
+@code{eval-region}. @xref{Definition of eval-region,, Eval}.
+@end defvar
+
+ For information about how @code{load} is used in building Emacs, see
+@ref{Building Emacs}.
+
+@node Load Suffixes
+@section Load Suffixes
+We now describe some technical details about the exact suffixes that
+@code{load} tries.
+
+@defvar load-suffixes
+This is a list of suffixes indicating (compiled or source) Emacs Lisp
+files. It should not include the empty string. @code{load} uses
+these suffixes in order when it appends Lisp suffixes to the specified
+file name. The standard value is @code{(".elc" ".el")} which produces
+the behavior described in the previous section.
+@end defvar
+
+@defvar load-file-rep-suffixes
+This is a list of suffixes that indicate representations of the same
+file. This list should normally start with the empty string.
+When @code{load} searches for a file it appends the suffixes in this
+list, in order, to the file name, before searching for another file.
+
+Enabling Auto Compression mode appends the suffixes in
+@code{jka-compr-load-suffixes} to this list and disabling Auto
+Compression mode removes them again. The standard value of
+@code{load-file-rep-suffixes} if Auto Compression mode is disabled is
+@code{("")}. Given that the standard value of
+@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value
+of @code{load-file-rep-suffixes} if Auto Compression mode is enabled
+is @code{("" ".gz")}.
+@end defvar
+
+@defun get-load-suffixes
+This function returns the list of all suffixes that @code{load} should
+try, in order, when its @var{must-suffix} argument is non-@code{nil}.
+This takes both @code{load-suffixes} and @code{load-file-rep-suffixes}
+into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes}
+and @code{load-file-rep-suffixes} all have their standard values, this
+function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto
+Compression mode is enabled and @code{(".elc" ".el")} if Auto
+Compression mode is disabled.
+@end defun
+
+To summarize, @code{load} normally first tries the suffixes in the
+value of @code{(get-load-suffixes)} and then those in
+@code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil},
+it skips the former group, and if @var{must-suffix} is non-@code{nil},
+it skips the latter group.
+
+@node Library Search
+@section Library Search
+
+ When Emacs loads a Lisp library, it searches for the library
+in a list of directories specified by the variable @code{load-path}.
+
@defopt load-path
@cindex @code{EMACSLOADPATH} environment variable
The value of this variable is a list of directories to search when
loading files with @code{load}. Each element is a string (which must be
a directory name) or @code{nil} (which stands for the current working
-directory). The value of @code{load-path} is initialized from the
-environment variable @code{EMACSLOADPATH}, if that exists; otherwise its
-default value is specified in @file{emacs/src/paths.h} when Emacs is
-built.
+directory).
+@end defopt
+
+ The value of @code{load-path} is initialized from the environment
+variable @code{EMACSLOADPATH}, if that exists; otherwise its default
+value is specified in @file{emacs/src/epaths.h} when Emacs is built.
+Then the list is expanded by adding subdirectories of the directories
+in the list.
-The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
+ The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
@samp{:} (or @samp{;}, according to the operating system) separates
directory names, and @samp{.} is used for the current default 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
@smallexample
-setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
+setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
@end smallexample
-Here is how to set it using @code{sh}:
+ Here is how to set it using @code{sh}:
@smallexample
export EMACSLOADPATH
-EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
+EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
@end smallexample
-Here is an example of code you can place in a @file{.emacs} file to add
-several directories to the front of your default @code{load-path}:
+ Here is an example of code you can place in your init file (@pxref{Init
+File}) to add several directories to the front of your default
+@code{load-path}:
@smallexample
@group
@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
+ 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 the
same 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 value
is used for execution of the dumped Emacs also.
-Therefore, if you want to change @code{load-path} temporarily for
+ Therefore, if you want to change @code{load-path} temporarily for
loading a few libraries in @file{site-init.el} or @file{site-load.el},
you should bind @code{load-path} locally with @code{let} around the
calls to @code{load}.
-@end defopt
The default value of @code{load-path}, when running an Emacs which has
-been installed on the system, looks like this:
+been installed on the system, includes two special directories (and
+their subdirectories as well):
+
+@smallexample
+"/usr/local/share/emacs/@var{version}/site-lisp"
+@end smallexample
+
+@noindent
+and
@smallexample
-("/usr/local/share/emacs/@var{version}/site-lisp"
- "/usr/local/share/emacs/site-lisp"
- "/usr/local/share/emacs/@var{version}/lisp")
+"/usr/local/share/emacs/site-lisp"
@end smallexample
- The last of these three directories is where the Lisp files of Emacs
-itself are installed; the first two are for additional Lisp packages
-installed at your site. The first directory is for locally installed
-packages that belong with a particular Emacs version; the second is for
-locally installed packages that can be used with any installed Emacs
-version.
+@noindent
+The first one is for locally installed packages for a particular Emacs
+version; the second is for locally installed packages meant for use with
+all installed Emacs versions.
There are several reasons why a Lisp package that works well in one
Emacs version can cause trouble in another. Sometimes packages need
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 and
+subdirectories multiple levels down are added to @code{load-path}.
+
+ Not all subdirectories are included, though. Subdirectories whose
+names do not start with a letter or digit are excluded. Subdirectories
+named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which
+contains a file named @file{.nosearch} is excluded. You can use these
+methods 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, an
executable 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. (Both
are represented as absolute file names.)
-@defvar load-in-progress
-This variable is non-@code{nil} if Emacs is in the process of loading a
-file, and it is @code{nil} otherwise.
-@end defvar
-
-@defvar load-read-function
-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 those
-functions should use @code{read}.
-@end defvar
-
- For how @code{load} is used to build Emacs, see @ref{Building Emacs}.
-
@deffn Command locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library @var{library}. It
searches for the library in the same way @code{load} does, and the
tells @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 unibyte
+strings or as multibyte strings (@pxref{Text Representations}). Which
+representation is used depends on how the file is read into Emacs. If
+it is read with decoding into multibyte representation, the text of the
+Lisp program will be multibyte text, and its string constants will be
+multibyte strings. If a file containing Latin-1 characters (for
+example) is read without decoding, the text of the program will be
+unibyte text, and its string constants will be unibyte strings.
+@xref{Coding Systems}.
+
+ To make the results more predictable, Emacs always performs decoding
+into the multibyte representation when loading Lisp files, even if it
+was started with the @samp{--unibyte} option. This means that string
+constants with non-@acronym{ASCII} characters translate into multibyte
+strings. The only exception is when a particular file specifies no
+decoding.
+
+ The reason Emacs is designed this way is so that Lisp programs give
+predictable results, regardless of how Emacs was started. In addition,
+this enables programs that depend on using multibyte text to work even
+in a unibyte Emacs. Of course, such programs should be designed to
+notice whether the user prefers unibyte or multibyte text, by checking
+@code{default-enable-multibyte-characters}, and convert representations
+appropriately.
+
+ In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are
+multibyte strings should not be noticeable, since inserting them in
+unibyte buffers converts them to unibyte automatically. However, if
+this does make a difference, you can force a particular Lisp file to be
+interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
+comment on the file's first line. With that designator, the file will
+unconditionally be interpreted as unibyte, even in an ordinary
+multibyte Emacs session. This can matter when making keybindings to
+non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
+
@node Autoload
@section Autoload
@cindex autoload
source before the real definition. @code{autoload} is the low-level
primitive for autoloading; any Lisp program can call @code{autoload} at
any time. Magic comments are the most convenient way to make a function
-autoload, for packages installed along with Emacs. They do nothing on
-their own, but they serve as a guide for the command
+autoload, for packages installed along with Emacs. These comments do
+nothing 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.
If @var{filename} does not contain either a directory name, or the
suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
one of these suffixes, and it will not load from a file whose name is
-just @var{filename} with no added suffix.
+just @var{filename} with no added suffix. (The variable
+@code{load-suffixes} specifies the exact required suffixes.)
The argument @var{docstring} is the documentation string for the
-function. Normally, this should be identical to the documentation string
-in the function definition itself. Specifying the documentation string
-in the call to @code{autoload} makes it possible to look at the
-documentation without loading the function's real definition.
+function. Specifying the documentation string in the call to
+@code{autoload} makes it possible to look at the documentation without
+loading the function's real definition. Normally, this should be
+identical to the documentation string in the function definition
+itself. If it isn't, the function definition's documentation string
+takes effect when it is loaded.
If @var{interactive} is non-@code{nil}, that says @var{function} can be
called interactively. This lets completion in @kbd{M-x} work without
-loading its real definition. The complete interactive specification is
-not given here; it's not needed unless the user actually calls
-@var{function}, and when that happens, it's time to load the real
-definition.
+loading @var{function}'s real definition. The complete interactive
+specification is not given here; it's not needed unless the user
+actually calls @var{function}, and when that happens, it's time to load
+the real definition.
You can autoload macros and keymaps as well as ordinary functions.
Specify @var{type} as @code{macro} if @var{function} is really a macro.
(autoload @var{filename} @var{docstring} @var{interactive} @var{type})
@end example
-For example,
+For example,
@example
@group
definitions or @code{provide} calls that occurred during the load are
undone. This is to ensure that the next attempt to call any function
autoloading from this file will try again to load the file. If not for
-this, then some of the functions in the file might appear defined, but
-they might fail to work properly for the lack of certain subroutines
-defined later in the file and not loaded successfully.
+this, then some of the functions in the file might be defined by the
+aborted load, but fail to work properly for the lack of certain
+subroutines not loaded successfully because they come later in the file.
If the autoloaded file fails to define the desired Lisp function or
macro, then an error is signaled with data @code{"Autoloading failed to
@findex update-file-autoloads
@findex update-directory-autoloads
- A magic autoload comment looks like @samp{;;;###autoload}, on a line
-by itself, just before the real definition of the function in its
+@cindex magic autoload comment
+@cindex autoload cookie
+@anchor{autoload cookie}
+ A magic autoload comment (often called an @dfn{autoload cookie})
+consists of @samp{;;;###autoload}, on a line by itself,
+just before the real definition of the function in its
autoloadable source file. The 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}.
The same magic comment can copy any kind of form into
@file{loaddefs.el}. If the form following the magic comment is not a
-function definition, it is copied verbatim. You can also use a magic
-comment to execute a form at build time @emph{without} executing it when
-the file itself is loaded. To do this, write the form @emph{on the same
-line} as the magic comment. Since it is in a comment, it does nothing
-when you load the source file; but @kbd{M-x update-file-autoloads}
-copies it to @file{loaddefs.el}, where it is executed while building
-Emacs.
+function-defining form or a @code{defcustom} form, it is copied
+verbatim. ``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 to
+a @code{defvar} in @file{loaddefs.el}, with some additional information
+if 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 it
+is 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}, where
+it is executed while building Emacs.
The following example shows how @code{doctor} is prepared for
autoloading with a magic comment:
Here's what that produces in @file{loaddefs.el}:
@smallexample
-(autoload 'doctor "doctor"
- "\
-Switch to *doctor* buffer and start giving psychotherapy."
- t)
+(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 string
The backslash and newline immediately following the double-quote are a
-convention used only in the preloaded Lisp files such as
+convention used only in the preloaded uncompiled Lisp files such as
@file{loaddefs.el}; they tell @code{make-docfile} to put the
documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
+See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)}
+in the usage part of the documentation string is replaced with the
+function's name when the various help functions (@pxref{Help
+Functions}) display it.
+
+ If you write a function definition with an unusual macro that is not
+one of the known and recognized function definition methods, use of an
+ordinary magic autoload comment would copy the whole definition into
+@code{loaddefs.el}. That is not desirable. You can put the desired
+@code{autoload} call into @code{loaddefs.el} instead by writing this:
+
+@smallexample
+;;;###autoload (autoload 'foo "myfile")
+(mydefunmacro foo
+ ...)
+@end smallexample
@node Repeated Loading
@section Repeated Loading
@cindex repeated loading
- You can load one file more than once in an Emacs session. For
+ You can load a given file more than once in an Emacs session. For
example, after you have rewritten and reinstalled a function definition
by editing it in a buffer, you may wish to return to the original
version; you can do this by reloading the file it came from.
that you intend to save and reinstall, you need to byte-compile the new
version; otherwise Emacs will load the older, byte-compiled file instead
of your newer, non-compiled file! If that happens, the message
-displayed when loading the file includes, @samp{(compiled; source is
+displayed when loading the file includes, @samp{(compiled; note, source is
newer)}, to remind you to recompile it.
When writing the forms in a Lisp library file, keep in mind that the
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))
+(push '(leif-mode " Leif") minor-mode-alist)
@end example
@noindent
@example
(or (assq 'leif-mode minor-mode-alist)
- (setq minor-mode-alist
- (cons '(leif-mode " Leif") minor-mode-alist)))
+ (push '(leif-mode " Leif") minor-mode-alist))
@end example
- To add an element to a list just once, use @code{add-to-list}
-(@pxref{Setting Variables}).
+@noindent
+or this:
+
+@example
+(add-to-list '(leif-mode " Leif") minor-mode-alist)
+@end example
Occasionally you will want to test explicitly whether a library has
already been loaded. Here's one way to test, in a library, whether it
If the library uses @code{provide} to provide a named feature, you can
use @code{featurep} earlier in the file to test whether the
@code{provide} call has been executed before.
-@ifinfo
+@ifnottex
@xref{Named Features}.
-@end ifinfo
+@end ifnottex
@node Named Features
@section Features
@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},
+ For example, in @file{emacs/lisp/prolog.el},
the definition for @code{run-prolog} includes the following code:
@smallexample
When @code{require} is used at top level in a file, it takes effect
when you byte-compile that file (@pxref{Byte Compilation}) as well as
when you load it. This is in case the required package contains macros
-that the byte compiler must know about.
+that the byte compiler must know about. It also avoids byte-compiler
+warnings for functions and variables defined in the file loaded with
+@code{require}.
Although top-level calls to @code{require} are evaluated during
byte compilation, @code{provide} calls are not. Therefore, you can
execute the @code{provide} call, so the subsequent @code{require} call
does nothing when the file is loaded.
-@defun provide feature
+@defun provide feature &optional subfeatures
This function announces that @var{feature} is now loaded, or being
loaded, into the current Emacs session. This means that the facilities
associated with @var{feature} are or will be available for other Lisp
The argument @var{feature} must be a symbol. @code{provide} returns
@var{feature}.
+If provided, @var{subfeatures} should be a list of symbols indicating
+a set of specific subfeatures provided by this version of @var{feature}.
+You can test the presence of a subfeature using @code{featurep}.
+
@smallexample
features
@result{} (bar bish)
@end smallexample
When a file is loaded to satisfy an autoload, and it stops due to an
-error in the evaluating its contents, any function definitions or
+error in the evaluation of its contents, any function definitions or
@code{provide} calls that occurred during the load are undone.
@xref{Autoload}.
@end defun
-@defun require feature &optional filename
+@defun require feature &optional filename noerror
This function checks whether @var{feature} is present in the current
Emacs session (using @code{(featurep @var{feature})}; see below). The
argument @var{feature} must be a symbol.
with @code{load}. If @var{filename} is not supplied, then the name of
the symbol @var{feature} is used as the base file name to load.
However, in this case, @code{require} insists on finding @var{feature}
-with an added suffix; a file whose name is just @var{feature} won't be
-used.
+with an added @samp{.el} or @samp{.elc} suffix (possibly extended with
+a compression suffix); a file whose name is just @var{feature} won't
+be used. (The variable @code{load-suffixes} specifies the exact
+required Lisp suffixes.)
+
+If @var{noerror} is non-@code{nil}, that suppresses errors from actual
+loading of the file. In that case, @code{require} returns @code{nil}
+if loading the file fails. Normally, @code{require} returns
+@var{feature}.
-If loading the file fails to provide @var{feature}, @code{require}
-signals an error, @samp{Required feature @var{feature} was not
-provided}.
+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
-This function returns @code{t} if @var{feature} has been provided in the
-current Emacs session (i.e., if @var{feature} is a member of
-@code{features}.)
+@defun featurep feature &optional subfeature
+This function returns @code{t} if @var{feature} has been provided in
+the current Emacs session (i.e.@:, if @var{feature} is a member of
+@code{features}.) If @var{subfeature} is non-@code{nil}, then the
+function returns @code{t} only if that subfeature is provided as well
+(i.e.@: if @var{subfeature} is a member of the @code{subfeature}
+property of the @var{feature} symbol.)
@end defun
@defvar features
@code{features} list is not significant.
@end defvar
+@node Where Defined
+@section Which File Defined a Certain Symbol
+
+@defun symbol-file symbol &optional type
+This function returns the name of the file that defined @var{symbol}.
+If @var{type} is @code{nil}, then any kind of definition is
+acceptable. If @var{type} is @code{defun} or @code{defvar}, that
+specifies 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-history
+This variable's value is an alist connecting library file names with the
+names 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 the
+list is the absolute file name of the library, as a string. The rest
+of the list elements have these forms:
+
+@table @code
+@item @var{var}
+The symbol @var{var} was defined as a variable.
+@item (defun . @var{fun})
+The function @var{fun} was defined.
+@item (t . @var{fun})
+The function @var{fun} was previously an autoload before this library
+redefined it as a function. The following element is always
+@code{(defun . @var{fun})}, which represents defining @var{fun} as a
+function.
+@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 table
+
+The value of @code{load-history} may have one element whose @sc{car} is
+@code{nil}. This element describes definitions made with
+@code{eval-buffer} on a buffer that is not visiting a file.
+@end defvar
+
+ The command @code{eval-region} updates @code{load-history}, but does so
+by adding the symbols defined to the element for the file being visited,
+rather than replacing that element. @xref{Eval}.
+
@node Unloading
@section Unloading
@cindex unloading
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-hooks
+Before restoring the previous definitions, @code{unload-feature} runs
+@code{remove-hook} to remove functions in the library from certain
+hooks. 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 from
+ceasing to function because important hooks refer to functions that
+are no longer defined.
+
+@vindex @var{feature}-unload-hook
+If these measures are not sufficient to prevent malfunction, a library
+can define an explicit unload hook. If @code{@var{feature}-unload-hook}
+is defined, it is run as a normal hook before restoring the previous
+definitions, @emph{instead of} the usual hook-removing actions. The
+unload hook ought to undo all the global state changes made by the
+library that might cease to work once the library is unloaded.
+@code{unload-feature} can cause problems with libraries that fail to do
+this, so it should be used with caution.
+
Ordinarily, @code{unload-feature} refuses to unload a library on which
other loaded libraries depend. (A library @var{a} depends on library
@var{b} if @var{a} contains a @code{require} for @var{b}.) If the
The @code{unload-feature} function is written in Lisp; its actions are
based on the variable @code{load-history}.
-@defvar load-history
-This variable's value is an alist connecting library names with the
-names 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 the
-list is the name of the library, as a string. The rest of the list is
-composed of these kinds of objects:
-
-@itemize @bullet
-@item
-Symbols that were defined by this library.
-@item
-Lists of the form @code{(require . @var{feature})} indicating
-features that were required.
-@item
-Lists of the form @code{(provide . @var{feature})} indicating
-features that were provided.
-@end itemize
-
-The value of @code{load-history} may have one element whose @sc{car} is
-@code{nil}. This element describes definitions made with
-@code{eval-buffer} on a buffer that is not visiting a file.
+@defvar unload-feature-special-hooks
+This variable holds a list of hooks to be scanned before unloading a
+library, to remove functions defined in the library.
@end defvar
- The command @code{eval-region} updates @code{load-history}, but does so
-by adding the symbols defined to the element for the file being visited,
-rather than replacing that element.
-
@node Hooks for Loading
@section Hooks for Loading
@cindex loading hooks
library @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 is
-found by searching @code{load-path}, you should not include any
-directory names in @var{library}.
+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 an
+installed library is found by searching @code{load-path}, you should not
+include 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 prevent
execution of the rest of @var{form}.
programs meant for wider use.
@defvar after-load-alist
-An alist of expressions to evaluate if and when particular libraries are
-loaded. Each element looks like this:
+This variable holds an alist of expressions to evaluate if and when
+particular libraries are loaded. Each element looks like this:
@example
(@var{filename} @var{forms}@dots{})
@end defvar
@c Emacs 19 feature
+
+@ignore
+ arch-tag: df731f89-0900-4389-a436-9105241b6f7a
+@end ignore