X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/81d3d428c6b88e6c99f3fad6b7cc52c12236ff56..a560da7e8e3d9d4182e94e692448a85b812f1448:/doc/lispref/loading.texi diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 9b582fe5cf..d093fde192 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -1,7 +1,7 @@ @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 @@ -501,6 +501,9 @@ 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}. +(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. @@ -567,6 +570,26 @@ ordinary magic autoload comment would copy the whole definition into ...) @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 @@ -598,24 +621,18 @@ initialized. (@xref{Defining Variables}.) @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) @@ -626,12 +643,6 @@ has been loaded before: @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 @@ -651,13 +662,13 @@ feature. Another program that uses them may ensure they are defined by @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: @@ -692,7 +703,7 @@ done. 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}. @@ -798,12 +809,15 @@ with a call to @code{provide}. The order of the elements in the @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 @@ -830,6 +844,8 @@ redefined it as a function. The following element is always 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}) @@ -862,24 +878,27 @@ library with @code{defun}, @code{defalias}, @code{defsubst}, 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