* 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.
-* Features:: Loading a library if it isn't already loaded.
+* 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.
@code{autoload} creates a placeholder object for a function in a file;
trying to call the autoloading function loads the file to get the
function's real definition (@pxref{Autoload}). @code{require} loads a
-file if it isn't already loaded (@pxref{Features}). Ultimately, all
+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
@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
@code{load} just returns @code{nil}.
+You can use the variable @code{load-read-function} to specify a function
+for @code{load} to use instead of @code{read} for reading expressions.
+See below.
+
@code{load} returns @code{t} if the file loads successfully.
@end defun
built.
The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
-@samp{:} 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:
+@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
several directories to the front of your default @code{load-path}:
@smallexample
+@group
(setq load-path
(append (list nil "/user/bil/emacs"
"/usr/local/lisplib"
- (expand-file-name "~/emacs"))
+ "~/emacs")
load-path))
+@end group
@end smallexample
@c Wordy to rid us of an overfull hbox. --rjc 15mar92
@noindent
In this example, the path searches the current working directory first,
-followed then by the @file{/user/bil/emacs} directory and then by
-the @file{/usr/local/lisplib} directory,
+followed then by the @file{/user/bil/emacs} directory, the
+@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
which are then followed by the standard directories for Lisp code.
The command line options @samp{-l} or @samp{-load} specify a Lisp
to the front of @code{load-path} so the file can be found there. Newer
Emacs versions also find such files in the current directory, but
without altering @code{load-path}.
+
+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
+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
@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. This is how @code{defun} and
-@code{provide} determine whether a load is in progress, so that their
-effect can be undone if the load fails.
+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
To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}.
@cindex autoload
The @dfn{autoload} facility allows you to make a function or macro
-available but put off loading its actual definition. The first call to
-the function automatically reads the proper file to install the real
-definition and other associated code, then runs the real definition
+known in Lisp, but put off loading the file that defines it. The first
+call to the function automatically reads the proper file to install the
+real definition and other associated code, then runs the real definition
as if it had been loaded all along.
There are two ways to set up an autoloaded function: by calling
keymap. Various parts of Emacs need to know this information without
loading the real definition.
+An autoloaded keymap loads automatically during key lookup when a prefix
+key's binding is the symbol @var{function}. Autoloading does not occur
+for other kinds of access to the keymap. In particular, it does not
+happen when a Lisp program gets the keymap from the value of a variable
+and calls @code{define-key}; not even if the variable name is the same
+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}.
For example,
@example
+@group
(symbol-function 'run-prolog)
@result{} (autoload "prolog" 169681 t nil)
+@end group
@end example
@noindent
@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 @dfn{on the same
+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 @code{update-file-autoloads} copies
it to @file{loaddefs.el}, where it is executed while building Emacs.
documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
@node Repeated Loading
-@comment node-name, next, previous, up
@section Repeated Loading
@cindex repeated loading
(cons '(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}).
+
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:
@example
+(defvar foo-was-loaded)
+
(if (not (boundp 'foo-was-loaded))
@var{execute-first-time-only})
If the library uses @code{provide} to provide a named feature, you can
use @code{featurep} to test whether the library has been loaded.
@ifinfo
-@xref{Features}.
+@xref{Named Features}.
@end ifinfo
-@node Features
+@node Named Features
@section Features
@cindex features
@cindex requiring features
@result{} (foo bar bish)
@end smallexample
-If the file isn't completely loaded, due to an error in the evaluating
-its contents, any function definitions or @code{provide} calls that
-occurred during the load are undone. @xref{Autoload}.
+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
+@code{provide} calls that occurred during the load are undone.
+@xref{Autoload}.
@end defun
@defun require feature &optional filename
reclaim memory for other Lisp objects. To do this, use the function
@code{unload-feature}:
-@deffn Command unload-feature feature
+@deffn Command unload-feature feature &optional force
This command unloads the library that provided feature @var{feature}.
It undefines all functions, macros, and variables defined in that
library with @code{defconst}, @code{defvar}, @code{defun},
@code{defmacro}, @code{defsubst} and @code{defalias}. It then restores
-any autoloads formerly associated with those symbols.
+any autoloads formerly associated with those symbols. (Loading
+saves these in the @code{autoload} property of the symbol.)
+
+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
+optional argument @var{force} is non-@code{nil}, dependencies are
+ignored and you can unload any library.
@end deffn
The @code{unload-feature} function is written in Lisp; its actions are
@defun eval-after-load library form
This function arranges to evaluate @var{form} at the end of loading the
-library @var{library}, if and when @var{library} is loaded.
+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
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}).
+
+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 of programs to be
+released.
+
@defvar after-load-alist
An alist of expressions to evaluate if and when particular libraries are
loaded. Each element looks like this: