@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, 2008 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/loading
@node Loading, Byte Compilation, Customization, Top
* 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.
+* 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
@code{load-path}, then all three suffixes in the second directory, and
so on. @xref{Library Search}.
+Whatever the name under which the file is eventually found, and the
+directory where Emacs found it, Emacs sets the value of the variable
+@code{load-file-name} to that file's name.
+
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
Compilation}.
@deffn Command load-library library
This command loads the library named @var{library}. It is equivalent to
-@code{load}, except in how it reads its argument interactively.
+@code{load}, except for the way it reads its argument interactively.
+@xref{Lisp Libraries,,,emacs, The GNU Emacs Manual}.
@end deffn
@defvar load-in-progress
file, and it is @code{nil} otherwise.
@end defvar
+@defvar load-file-name
+When Emacs is in the process of loading a file, this variable's value
+is the name of that file, as Emacs found it during the search
+described earlier in this section.
+@end defvar
+
@defvar load-read-function
@anchor{Definition of load-read-function}
@c do not allow page break at anchor; work around Texinfo deficiency.
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 a unibyte Emacs.
In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are
multibyte strings should not be noticeable, since inserting them in
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:
+But this would add multiple elements if the library is reloaded. To
+avoid the problem, use @code{add-to-list} (@pxref{List Variables}):
@example
-(or (assq 'leif-mode minor-mode-alist)
- (push '(leif-mode " Leif") minor-mode-alist))
-@end example
-
-@noindent
-or this:
-
-@example
-(add-to-list '(leif-mode " Leif") minor-mode-alist)
+(add-to-list 'minor-mode-alist '(leif-mode " Leif"))
@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:
associated with @var{feature} are or will be available for other Lisp
programs.
-The direct effect of calling @code{provide} is to add @var{feature} to
-the 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}.
+The direct effect of calling @code{provide} is if not already in
+@var{features} then to add @var{feature} to the front of that list and
+call any @code{eval-after-load} code waiting for it (@pxref{Hooks for
+Loading}). 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
@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
@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.
+The value of this variable is an alist that associates the names of
+loaded library files with the names of the functions and variables
+they defined, as well as the features they provided or required.
-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:
+Each element in this alist describes one loaded library (including
+libraries that are preloaded at startup). It is a list whose @sc{car}
+is the absolute file name of the library (a string). The rest of the
+list elements have these forms:
@table @code
@item @var{var}
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})
@cindex loading hooks
@cindex hooks for loading
-You can ask for code to be executed if and when a particular library is
-loaded, by calling @code{eval-after-load}.
+You can ask for code to be executed each time Emacs loads a library,
+by using the variable @code{after-load-functions}:
+
+@defvar after-load-functions
+This abnormal hook is run after loading a file. Each function in the
+hook is called with a single argument, the absolute filename of the
+file that was just loaded.
+@end defvar
+
+If you want code to be executed when a @emph{particular} library is
+loaded, use the function @code{eval-after-load}:
@defun eval-after-load library form
This function arranges to evaluate @var{form} at the end of loading
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:
+@var{library}. Normally, you just give a bare file name, like this:
@example
(eval-after-load "edebug" '(def-edebug-spec c-point t))
execution of the rest of @var{form}.
@end defun
-In 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 for
-outside use), and (2) call the library's functions. If you wish to
-do (1), you can do it immediately---there is no need to wait for when
-the library is loaded. To do (2), you must load the library (preferably
-with @code{require}).
+Normally, well-designed Lisp programs should not use
+@code{eval-after-load}. If you need to examine and set the variables
+defined in another library (those meant for outside use), you can do
+it immediately---there is no need to wait until the library is loaded.
+If you need to call functions defined by that library, you should load
+the library, preferably with @code{require} (@pxref{Named Features}).
But it is OK to use @code{eval-after-load} in your personal
-customizations if you don't feel they must meet the design standards for
-programs meant for wider use.
+customizations if you don't feel that they must meet the design
+standards for programs meant for wider use.
@defvar after-load-alist
-This variable, an alist built by @code{eval-after-load}, holds the
-expressions to evaluate when particular libraries are loaded. Each
-element looks like this:
+This variable stores an alist built by @code{eval-after-load},
+containing the expressions to evaluate when certain libraries are
+loaded. Each element looks like this:
@example
(@var{regexp-or-feature} @var{forms}@dots{})
@end example
The key @var{regexp-or-feature} is either a regular expression or a
-symbol, and the value is a list of forms. The forms are evaluated when
-the key matches the absolute true name of the file being
-@code{load}ed or the symbol being @code{provide}d.
+symbol, and the value is a list of forms. The forms are evaluated
+when the key matches the absolute true name or feature name of the
+library being loaded.
@end defvar
@ignore
HCoop / bpt / emacs.git / blobdiff