annotate lispref/loading.texi @ 10225:2e5dcd5f3090

Recommend doc strings for all functions and variables.

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/loading
@node Loading, Byte Compilation, Macros, Top
@chapter Loading
@cindex loading
@cindex library
@cindex Lisp library

  Loading a file of Lisp code means bringing its contents into the Lisp
environment in the form of Lisp objects.  Emacs finds and opens the
file, reads the text, evaluates each form, and then closes the file.

  The load functions evaluate all the expressions in a file just
as the @code{eval-current-buffer} function evaluates all the
expressions in a buffer.  The difference is that the load functions
read and evaluate the text in the file as found on disk, not the text
in an Emacs buffer.

@cindex top-level form
  The loaded file must contain Lisp expressions, either as source code
or as byte-compiled code.  Each form in the file is called a
@dfn{top-level form}.  There is no special format for the forms in a
loadable file; any form in a file may equally well be typed directly
into a buffer and evaluated there.  (Indeed, most code is tested this
way.)  Most often, the forms are function definitions and variable
definitions.

  A file containing Lisp code is often called a @dfn{library}.  Thus,
the ``Rmail library'' is a file containing code for Rmail mode.
Similarly, a ``Lisp library directory'' is a directory of files
containing Lisp code.

@menu
* 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.
* 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
@section How Programs Do Loading

  Emacs Lisp has several interfaces for loading.  For example,
@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
these facilities call the @code{load} function to do the work.

@defun load filename &optional missing-ok nomessage nosuffix
This function finds and opens a file of Lisp code, evaluates all the
forms in it, and closes the file.

To find the file, @code{load} first looks for a file named
@file{@var{filename}.elc}, that is, for a file whose name is
@var{filename} with @samp{.elc} appended.  If such a file exists, it is
loaded.  If there is no file by that name, then @code{load} looks for a
file named @file{@var{filename}.el}.  If that file exists, it is loaded.
Finally, if neither of those names is found, @code{load} looks for a
file named @var{filename} with nothing appended, and loads it if it
exists.  (The @code{load} function is not clever about looking at
@var{filename}.  In the perverse case of a file named @file{foo.el.el},
evaluation of @code{(load "foo.el")} will indeed find it.)

If the optional argument @var{nosuffix} is non-@code{nil}, then the
suffixes @samp{.elc} and @samp{.el} are not tried.  In this case, you
must specify the precise file name you want.

If @var{filename} is a relative file name, such as @file{foo} or
@file{baz/foo.bar}, @code{load} searches for the file using the variable
@code{load-path}.  It appends @var{filename} to each of the directories
listed in @code{load-path}, and loads the first file it finds whose name
matches.  The current default directory is tried only if it is specified
in @code{load-path}, where @code{nil} stands for the default directory.
@code{load} tries all three possible suffixes in the first directory in
@code{load-path}, then all three suffixes in the second directory, and
so on.

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}.

Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
in the echo area during loading unless @var{nomessage} is
non-@code{nil}.

@cindex load errors
Any unhandled errors while loading a file terminate loading.  If the
load was done for the sake of @code{autoload}, any function definitions
made during the loading are undone.

@kindex file-error
If @code{load} can't find the file to load, then normally it signals the
error @code{file-error} (with @samp{Cannot open load file
@var{filename}}).  But if @var{missing-ok} is non-@code{nil}, then
@code{load} just returns @code{nil}.

@code{load} returns @code{t} if the file loads successfully.
@end defun

@ignore
@deffn Command load-file filename
This function loads the file @var{filename}.  If @var{filename} is an
absolute file name, then it is loaded.  If it is relative, then the
current default directory is assumed.  @code{load-path} is not used, and
suffixes are not appended.  Use this function if you wish to specify
the file to be loaded exactly.
@end deffn

@deffn Command load-library library
This function loads the library named @var{library}.  A library is
nothing more than a file that may be loaded as described earlier.  This
function is identical to @code{load}, save that it reads a file name
interactively with completion.
@end deffn
@end ignore

@defopt load-path
@cindex @code{EMACSLOADPATH} environment variable
The value of this variable is a list of directories to search when
loading files with @code{load}.  Each element is a string (which must be
a directory name) or @code{nil} (which stands for the current working
directory).  The value of @code{load-path} is initialized from the
environment variable @code{EMACSLOADPATH}, if that exists; otherwise its
default value is specified in @file{emacs/src/paths.h} when Emacs is
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:

@c This overfull hbox is OK.  --rjc 16mar92
@smallexample
setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
@end smallexample

Here is how to set it using @code{sh}:

@smallexample
export EMACSLOADPATH
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
@end smallexample

Here is an example of code you can place in a @file{.emacs} file to add
several directories to the front of your default @code{load-path}:

@smallexample
(setq load-path
      (append (list nil "/user/bil/emacs"
                    "/usr/local/lisplib"
                    (expand-file-name "~/emacs"))
              load-path))
@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,
which are then followed by the standard directories for Lisp code.

The command line options @samp{-l} or @samp{-load} specify a Lisp
library to load as part of Emacs startup.  Since this file might be in
the current directory, Emacs 18 temporarily adds the current directory
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}.
@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.
@end defvar

  To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}.

@node Autoload
@section Autoload
@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
as if it had been loaded all along.

  There are two ways to set up an autoloaded function: by calling
@code{autoload}, and by writing a special ``magic'' comment in the
source before the real definition.  @code{autoload} is the low-level
primitive for autoloading; any Lisp program can call @code{autoload} at
any time.  Magic comments do nothing on their own; they serve as a guide
for the command @code{update-file-autoloads}, which constructs calls to
@code{autoload} and arranges to execute them when Emacs is built.  Magic
comments are the most convenient way to make a function autoload, but
only for packages installed along with Emacs.

@defun autoload function filename &optional docstring interactive type
This function defines the function (or macro) named @var{function} so as
to load automatically from @var{filename}.  The string @var{filename}
specifies the file to load to get the real definition of @var{function}.

The argument @var{docstring} is the documentation string for the
function.  Normally, this is the identical to the documentation string
in the function definition itself.  Specifying the documentation string
in the call to @code{autoload} makes it possible to look at the
documentation without loading the function's real definition.

If @var{interactive} is non-@code{nil}, then the function can be called
interactively.  This lets completion in @kbd{M-x} work without loading
the function's real definition.  The complete interactive specification
need not be given here; it's not needed unless the user actually calls
@var{function}, and when that happens, it's time to load the real
definition.

You can autoload macros and keymaps as well as ordinary functions.
Specify @var{type} as @code{macro} if @var{function} is really a macro.
Specify @var{type} as @code{keymap} if @var{function} is really a
keymap.  Various parts of Emacs need to know this information without
loading the real definition.

@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:

@example
(autoload @var{filename} @var{docstring} @var{interactive} @var{type})
@end example

For example, 

@example
(symbol-function 'run-prolog)
     @result{} (autoload "prolog" 169681 t nil)
@end example

@noindent
In this case, @code{"prolog"} is the name of the file to load, 169681
refers to the documentation string in the @file{emacs/etc/DOC} file
(@pxref{Documentation Basics}), @code{t} means the function is
interactive, and @code{nil} that it is not a macro or a keymap.
@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
(due to an error in the evaluation of its contents), any function
definitions or @code{provide} calls that occurred during the load are
undone.  This is to ensure that the next attempt to call any function
autoloading from this file will try again to load the file.  If not for
this, then some of the functions in the file might appear defined, but
they might fail to work properly for the lack of certain subroutines
defined later in the file and not loaded successfully.

  If the autoloaded file fails to define the desired Lisp function or
macro, then an error is signaled with data @code{"Autoloading failed to
define function @var{function-name}"}.

@findex update-file-autoloads
@findex update-directory-autoloads
  A magic autoload comment looks like @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}.
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.

  The same magic comment can copy any kind of form into
@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
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.

  The following example shows how @code{doctor} is prepared for
autoloading with a magic comment:

@smallexample
;;;###autoload
(defun doctor ()
  "Switch to *doctor* buffer and start giving psychotherapy."
  (interactive)
  (switch-to-buffer "*doctor*")
  (doctor-mode))
@end smallexample

@noindent
Here's what that produces in @file{loaddefs.el}:

@smallexample
(autoload 'doctor "doctor"
  "\
Switch to *doctor* buffer and start giving psychotherapy."
  t)
@end smallexample

@noindent
The backslash and newline immediately following the double-quote are a
convention used only in the preloaded Lisp files such as
@file{loaddefs.el}; they tell @code{make-docfile} to put the
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

  You may load one file more than once in an Emacs session.  For
example, after you have rewritten and reinstalled a function definition
by editing it in a buffer, you may wish to return to the original
version; you can do this by reloading the file it came from.

  When you load or reload files, bear in mind that the @code{load} and
@code{load-library} functions automatically load a byte-compiled file
rather than a non-compiled file of similar name.  If you rewrite a file
that you intend to save and reinstall, remember to byte-compile it if
necessary; otherwise you may find yourself inadvertently reloading the
older, byte-compiled file instead of your newer, non-compiled file!

  When writing the forms in a Lisp library file, keep in mind that the
file might be loaded more than once.  For example, the choice of
@code{defvar} vs.@: @code{defconst} for defining a variable depends on
whether it is desirable to reinitialize the variable if the library is
reloaded: @code{defconst} does so, and @code{defvar} does not.
(@xref{Defining Variables}.)

  The simplest way to add an element to an alist is like this:

@example
(setq minor-mode-alist
      (cons '(leif-mode " Leif") minor-mode-alist))
@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)
    (setq minor-mode-alist
          (cons '(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:

@example
(if (not (boundp 'foo-was-loaded))
    @var{execute-first-time-only})

(setq foo-was-loaded t)
@end example

@noindent
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}.
@end ifinfo

@node Features
@section Features
@cindex features
@cindex requiring features
@cindex providing features

  @code{provide} and @code{require} are an alternative to
@code{autoload} for loading files automatically.  They work in terms of
named @dfn{features}.  Autoloading is triggered by calling a specific
function, but a feature is loaded the first time another program asks
for it by name.

  A feature name is a symbol that stands for a collection of functions,
variables, etc.  The file that defines them should @dfn{provide} the
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.

  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

  Features are normally named after the files that provide them, so that
@code{require} need not be given the file name.

  For example, in @file{emacs/lisp/prolog.el}, 
the definition for @code{run-prolog} includes the following code:

@smallexample
(defun run-prolog ()
  "Run an inferior Prolog process, input and output via buffer *prolog*."
  (interactive)
  (require 'comint)
  (switch-to-buffer (make-comint "prolog" prolog-program-name))
  (inferior-prolog-mode))
@end smallexample

@noindent
The expression @code{(require 'comint)} loads the file @file{comint.el}
if it has not yet been loaded.  This ensures that @code{make-comint} is
defined.

The @file{comint.el} file contains the following top-level expression:

@smallexample
(provide 'comint)
@end smallexample

@noindent
This adds @code{comint} to the global @code{features} list, so that
@code{(require 'comint)} will henceforth know that nothing needs to be
done.

@cindex byte-compiling @code{require}
  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.

  Although top-level calls to @code{require} are evaluated during
byte compilation, @code{provide} calls are not.  Therefore, you can
ensure that a file of definitions is loaded before it is byte-compiled
by including a @code{provide} followed by a @code{require} for the same
feature, as in the following example.

@smallexample
@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

@noindent
The compiler ignores the @code{provide}, then processes the
@code{require} by loading the file in question.  Loading the file does
execute the @code{provide} call, so the subsequent @code{require} call
does nothing while loading.

@defun provide feature
This function announces that @var{feature} is now loaded, or being
loaded, into the current Emacs session.  This means that the facilities
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}.

@smallexample
features
     @result{} (bar bish)

(provide 'foo)
     @result{} foo
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}.
@end defun

@defun require feature &optional filename
This function checks whether @var{feature} is present in the current
Emacs session (using @code{(featurep @var{feature})}; see below).  If it
is not, then @code{require} loads @var{filename} with @code{load}.  If
@var{filename} is not supplied, then the name of the symbol
@var{feature} is used as the file name to load.

If loading the file fails to provide @var{feature}, @code{require}
signals an error, @samp{Required feature @var{feature} was not
provided}.
@end defun

@defun featurep feature
This function returns @code{t} if @var{feature} has been provided in the
current Emacs session (i.e., @var{feature} is a member of
@code{features}.)
@end defun

@defvar features
The value of this variable is a list of symbols that are the features
loaded in the current Emacs session.  Each symbol was put in this list
with a call to @code{provide}.  The order of the elements in the
@code{features} list is not significant.
@end defvar

@node Unloading
@section Unloading
@cindex unloading

@c Emacs 19 feature
  You can discard the functions and variables loaded by a library to
reclaim memory for other Lisp objects.  To do this, use the function
@code{unload-feature}:

@deffn Command unload-feature feature
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.
@end deffn

  The @code{unload-feature} function is written in Lisp; its actions are
based on the variable @code{load-history}.

@defvar load-history
This variable's value is an alist connecting library names with the
names of functions and variables they define, the features they provide,
and the features they require.

Each element is a list and describes one library.  The @sc{car} of the
list is the name of the library, as a string.  The rest of the list is
composed of these kinds of objects:

@itemize @bullet
@item
Symbols that were defined by this library.
@item
Lists of the form @code{(require . @var{feature})} indicating
features that were required.
@item
Lists of the form @code{(provide . @var{feature})} indicating
features that were provided.
@end itemize

The value of @code{load-history} may have one element whose @sc{car} is
@code{nil}.  This element describes definitions made with
@code{eval-buffer} on a buffer that is not visiting a file.
@end defvar

  The command @code{eval-region} updates @code{load-history}, but does so
by adding the symbols defined to the element for the file being visited,
rather than replacing that element.

@node Hooks for Loading
@section Hooks for Loading
@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}.

@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.

The library name @var{library} must exactly match the argument of
@code{load}.  To get the proper results when an installed library is
found by searching @code{load-path}, you should not include any
directory names in @var{library}.

An error in @var{form} does not undo the load, but does prevent
execution of the rest of @var{form}.
@end defun

@defvar after-load-alist
An alist of expressions to evaluate if and when particular libraries are
loaded.  Each element looks like this:

@example
(@var{filename} @var{forms}@dots{})
@end example

The function @code{load} checks @code{after-load-alist} in order to
implement @code{eval-after-load}.
@end defvar

@c Emacs 19 feature