@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@node Loading, Byte Compilation, Customization, Top
+@node Loading
@chapter Loading
@cindex loading
@cindex library
character set translation just as Emacs would do when visiting the file.
@xref{Coding Systems}.
+@c This is referred to from the Macros chapter.
+@c Not sure if it should be the other way round.
+@cindex eager macro expansion
+When loading an uncompiled file, Emacs tries to expand any macros
+that the file contains (@pxref{Macros}). We refer to this as
+@dfn{eager macro expansion}. Doing this (rather than deferring
+the expansion until the relevant code runs) can significantly speed
+up the execution of uncompiled code. Sometimes, this macro expansion
+cannot be done, owing to a cyclic dependency. In the simplest
+example of this, the file you are loading refers to a macro defined
+in another file, and that file in turn requires the file you are
+loading. This is generally harmless. Emacs prints a warning
+(@samp{Eager macro-expansion skipped due to cycle@dots{}})
+giving details of the problem, but it still loads the file, just
+leaving the macro unexpanded for now. You may wish to restructure
+your code so that this does not happen. Loading a compiled file does
+not cause macroexpansion, because this should already have happened
+during compilation. @xref{Compiling Macros}.
+
Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
in the echo area during loading unless @var{nomessage} is
non-@code{nil}.
current default directory. Here is an example of how to set
@env{EMACSLOADPATH} variable from @command{sh}:
-@smallexample
+@example
export EMACSLOADPATH
EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
-@end smallexample
+@end example
@noindent
Here is how to set it from @code{csh}:
-@smallexample
+@example
setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
-@end smallexample
+@end example
+@cindex site-lisp directories
If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs
initializes @code{load-path} with the following two directories:
-@smallexample
+@example
"/usr/local/share/emacs/@var{version}/site-lisp"
-@end smallexample
+@end example
@noindent
and
-@smallexample
+@example
"/usr/local/share/emacs/site-lisp"
-@end smallexample
+@end example
@noindent
The first one is for locally installed packages for a particular Emacs
It is common to add code to one's init file (@pxref{Init File}) to
add one or more directories to @code{load-path}. For example:
-@smallexample
+@example
(push "~/.emacs.d/lisp" load-path)
-@end smallexample
+@end example
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,
For instance, suppose @code{load-path} is set to
-@smallexample
+@example
("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
-@end smallexample
+@end example
@noindent
and that both these directories contain a file named @file{foo.el}.
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 local variables section. With
+@samp{coding: raw-text} in a local variables section. 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}}.
+unibyte. This can matter when making keybindings to
+non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
@node Autoload
@section Autoload
@cindex autoload
- The @dfn{autoload} facility allows you to register the existence of
-a function or macro, but put off loading the file that defines it.
-The first call to the function automatically reads the proper file, in
+ The @dfn{autoload} facility lets you register the existence of a
+function or macro, but put off loading the file that defines it. The
+first call to the function automatically loads the proper library, in
order to install the real definition and other associated code, then
runs the real definition as if it had been loaded all along.
+Autoloading can also be triggered by looking up the documentation of
+the function or macro (@pxref{Documentation Basics}).
There are two ways to set up an autoloaded function: by calling
@code{autoload}, and by writing a special ``magic'' comment in the
specifies the file to load to get the real definition of @var{function}.
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. (The variable
+suffix @code{.el} or @code{.elc}, this function 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. (The variable
@code{load-suffixes} specifies the exact required suffixes.)
The argument @var{docstring} is the documentation string for the
symbol @var{function}.
@cindex function cell in autoload
-If @var{function} already has a non-void function definition that is not
-an autoload object, @code{autoload} does nothing and returns @code{nil}.
-If the function cell of @var{function} is void, or is already an autoload
-object, then it is defined as an autoload object like this:
+if @var{function} already has non-void function definition that is not
+an autoload object, this function does nothing and returns @code{nil}.
+Otherwise, it constructs an autoload object (@pxref{Autoload Type}),
+and stores it as the function definition for @var{function}. The
+autoload object has this form:
@example
(autoload @var{filename} @var{docstring} @var{interactive} @var{type})
not a macro or a keymap.
@end defun
+@defun autoloadp object
+This function returns non-@code{nil} if @var{object} is an autoload
+object. For example, to check if @code{run-prolog} is defined as an
+autoloaded function, evaluate
+
+@smallexample
+(autoloadp (symbol-function 'run-prolog))
+@end smallexample
+@end defun
+
@cindex autoload errors
The autoloaded file usually contains other definitions and may require
or provide one or more features. If the file is not completely loaded
The same magic comment can copy any kind of form into
@file{loaddefs.el}. The form following the magic comment is copied
verbatim, @emph{except} if it is one of the forms which the autoload
-facility handles specially (e.g.@: by conversion into an
+facility handles specially (e.g., by conversion into an
@code{autoload} call). The forms which are not copied verbatim are
the following:
@table @asis
@item Definitions for function or function-like objects:
-@code{defun} and @code{defmacro}; also @code{defun*} and
-@code{defmacro*} (@pxref{Argument Lists,,,cl,CL Manual}), and
-@code{define-overloadable-function} (see the commentary in
+@code{defun} and @code{defmacro}; also @code{cl-defun} and
+@code{cl-defmacro} (@pxref{Argument Lists,,,cl,Common Lisp Extensions}),
+and @code{define-overloadable-function} (see the commentary in
@file{mode-local.el}).
@item Definitions for major or minor modes:
-@code{define-derived-mode}, @code{define-minor-mode},
-@code{define-compilation-mode}, @code{define-generic-mode},
-@code{easy-mmode-define-global-mode}, @code{define-global-minor-mode},
-@code{define-globalized-minor-mode}, and
-@code{easy-mmode-define-minor-mode}.
+@code{define-minor-mode}, @code{define-globalized-minor-mode},
+@code{define-generic-mode}, @code{define-derived-mode},
+@code{easy-mmode-define-minor-mode},
+@code{easy-mmode-define-global-mode}, @code{define-compilation-mode},
+and @code{define-global-minor-mode}.
@item Other definition types:
@code{defcustom}, @code{defgroup}, @code{defclass}
The following example shows how @code{doctor} is prepared for
autoloading with a magic comment:
-@smallexample
+@example
;;;###autoload
(defun doctor ()
"Switch to *doctor* buffer and start giving psychotherapy."
(interactive)
(switch-to-buffer "*doctor*")
(doctor-mode))
-@end smallexample
+@end example
@noindent
Here's what that produces in @file{loaddefs.el}:
-@smallexample
+@example
(autoload (quote doctor) "doctor" "\
Switch to *doctor* buffer and start giving psychotherapy.
\(fn)" t nil)
-@end smallexample
+@end example
@noindent
@cindex @code{fn} in function's documentation string
@code{loaddefs.el}. That is not desirable. You can put the desired
@code{autoload} call into @code{loaddefs.el} instead by writing this:
-@smallexample
+@example
;;;###autoload (autoload 'foo "myfile")
(mydefunmacro foo
...)
-@end smallexample
+@end example
You can use a non-default string as the autoload cookie and have the
corresponding autoload calls written into a file whose name is
assumed to contain a trailer starting with a formfeed character.
@end defvar
+ The following function may be used to explicitly load the library
+specified by an autoload object:
+
+@defun autoload-do-load autoload &optional name macro-only
+This function performs the loading specified by @var{autoload}, which
+should be an autoload object. The optional argument @var{name}, if
+non-@code{nil}, should be a symbol whose function value is
+@var{autoload}; in that case, the return value of this function is the
+symbol's new function value. If the value of the optional argument
+@var{macro-only} is @code{macro}, this function avoids loading a
+function, only a macro.
+@end defun
+
@node Repeated Loading
@section Repeated Loading
@cindex repeated loading
For example, in @file{idlwave.el}, the definition for
@code{idlwave-complete-filename} includes the following code:
-@smallexample
+@example
(defun idlwave-complete-filename ()
"Use the comint stuff to complete a file name."
(require 'comint)
(comint-completion-addsuffix nil)
...)
(comint-dynamic-complete-filename)))
-@end smallexample
+@end example
@noindent
The expression @code{(require 'comint)} loads the file @file{comint.el}
The @file{comint.el} file contains the following top-level expression:
-@smallexample
+@example
(provide 'comint)
-@end smallexample
+@end example
@noindent
This adds @code{comint} to the global @code{features} list, so that
by including a @code{provide} followed by a @code{require} for the same
feature, as in the following example.
-@smallexample
+@example
@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
+@end example
@noindent
The compiler ignores the @code{provide}, then processes the
present in a given version. @xref{Network Feature Testing}, for
an example.
-@smallexample
+@example
features
@result{} (bar bish)
@result{} foo
features
@result{} (foo bar bish)
-@end smallexample
+@end example
When a file is loaded to satisfy an autoload, and it stops due to an
error in the evaluation of its contents, any function definitions or
@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
+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}
+(i.e., if @var{subfeature} is a member of the @code{subfeature}
property of the @var{feature} symbol.)
@end defun
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
+hooks. These hooks include variables whose names end in @samp{-hook}
+(or the deprecated suffix @samp{-hooks}), plus those listed in
@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
(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{library} can also be a feature (i.e., a symbol), in which case
@var{form} is evaluated at the end of any file where
@code{(provide @var{library})} is called.