* 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
+ The default value of @code{load-path}, when running an Emacs which has
+been installed on the system, looks like this:
+
+@smallexample
+("/usr/local/share/emacs/@var{version}/site-lisp"
+ "/usr/local/share/emacs/site-lisp"
+ "/usr/local/share/emacs/@var{version}/lisp")
+@end smallexample
+
+ The last of these three directories is where the Lisp files of Emacs
+itself are installed; the first two are for additional Lisp packages
+installed at your site. The first directory is for locally installed
+packages that belong with a particular Emacs version; the second is for
+locally installed packages that can be used with any installed Emacs
+version.
+
+ There are several reasons why a Lisp package that works well in one
+Emacs version can cause trouble in another. Sometimes packages need
+updating for incompatible changes in Emacs; sometimes they depend on
+undocumented internal Emacs data that can change without notice;
+sometimes a newer Emacs version incorporates a version of the package,
+and should be used only with that version.
+
+ If you run Emacs from the directory where it was built---that is, an
+executable that has not been formally installed---then @code{load-path}
+normally contains two additional directories. These are the @code{lisp}
+and @code{site-lisp} subdirectories of the main build directory. (Both
+are represented as absolute file names.)
+
@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
@smallexample
(defun run-prolog ()
- "Run an inferior Prolog process, input and output via buffer *prolog*."
+ "Run an inferior Prolog process, with I/O via buffer *prolog*."
(interactive)
(require 'comint)
(switch-to-buffer (make-comint "prolog" prolog-program-name))
@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
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
@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: