@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 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/loading
@node Loading, Byte Compilation, Customization, Top
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}.
+(The string that serves as the autoload cookie and the name of the
+file generated by @code{update-file-autoloads} can be changed from the
+above defaults, see below.)
Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
@kbd{M-x update-directory-autoloads} is even more powerful; it updates
autoloads for all files in the current directory.
...)
@end smallexample
+ You can use a non-default string as the autoload cookie and have the
+corresponding autoload calls written into a file whose name is
+different from the default @file{loaddefs.el}. Emacs provides two
+variables to control this:
+
+@defvar generate-autoload-cookie
+The value of this variable should be a string whose syntax is a Lisp
+comment. @kbd{M-x update-file-autoloads} copies the Lisp form that
+follows the cookie into the autoload file it generates. The default
+value of this variable is @code{";;;###autoload"}.
+@end defvar
+
+@defvar generated-autoload-file
+The value of this variable names an Emacs Lisp file where the autoload
+calls should go. The default value is @file{loaddefs.el}, but you can
+override that, e.g., in the ``Local Variables'' section of a
+@file{.el} file (@pxref{File Local Variables}). The autoload file is
+assumed to contain a trailer starting with a formfeed character.
+@end defvar
+
@node Repeated Loading
@section Repeated Loading
@cindex repeated loading
@end example
@noindent
-But 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
-
-@noindent
-or this:
+But this would add multiple elements if the library is reloaded. To
+avoid the problem, use @code{add-to-list} (@pxref{List Variables}):
@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
-has been loaded before:
+already been loaded. 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 (@pxref{Named
+Features}). Alternatively, you could use something like this:
@example
(defvar foo-was-loaded nil)
@end example
@noindent
-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.
-@ifnottex
-@xref{Named Features}.
-@end ifnottex
@node Named Features
@section Features
@dfn{requiring} the feature. This loads the file of definitions if it
hasn't been loaded already.
+@cindex load error with require
To require the presence of a feature, call @code{require} with the
feature name as argument. @code{require} looks in the global variable
@code{features} to see whether the desired feature has been provided
already. If not, it loads the feature from the appropriate file. This
file 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:
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. It also avoids byte-compiler
+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}.
@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.
+If @var{type} is @code{nil}, then any kind of definition is acceptable.
+If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that
+specifies function definition, variable definition, or face 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. If @var{symbol}
+specifies an autoloaded function, the value can be a relative file name
+without extension.
@end defun
The basis for @code{symbol-file} is the data in the variable
function.
@item (autoload . @var{fun})
The function @var{fun} was defined as an autoload.
+@item (defface . @var{face})
+The face @var{face} was defined.
@item (require . @var{feature})
The feature @var{feature} was required.
@item (provide . @var{feature})
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.
+@code{unload-feature-special-hooks}, as well as
+@code{auto-mode-alist}. This is to prevent Emacs from ceasing to
+function because important hooks refer to functions that are no longer
+defined.
+
+Standard unloading activities also undoes ELP profiling of functions
+in that library, unprovides any features provided by the library, and
+cancels timers held in variables defined by the library.
-@vindex @var{feature}-unload-hook
+@vindex @var{feature}-unload-function
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.
+can define an explicit unloader named @code{@var{feature}-unload-function}.
+If that symbol is defined as a function, @code{unload-feature} calls
+it with no arguments before doing anything else. It can do whatever
+is appropriate to unload the library. If it returns @code{nil},
+@code{unload-feature} proceeds to take the normal unload actions.
+Otherwise it considers the job to be done.
Ordinarily, @code{unload-feature} refuses to unload a library on which
other loaded libraries depend. (A library @var{a} depends on library