@c -*-texinfo-*-
@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, optionally, 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.
@end menu

@node How Programs Do Loading, Autoload, Loading, Loading
@section How Programs Do Loading

  There are several interface functions for loading.  For example, the
@code{autoload} function creates a Lisp object that loads a file when it
is evaluated (@pxref{Autoload}).  @code{require} also causes files to be
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 has
@samp{.elc} appended.  If such a file exists, it is loaded.  But if
there is no file by that name, then @code{load} looks for a file whose
name has @samp{.el} appended.  If that file exists, it is loaded.
Finally, if there is no file by either name, @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, the
file name must be specified precisely.

@vindex load-path
If @var{filename} is a relative file name, such as @file{foo.bar} or
@file{baz/foo.bar}, Emacs searches for the file using the variable
@code{load-path}.  Emacs does this by appending @var{filename} to each
of the directories listed in @code{load-path}, and loading the first
file it finds whose name matches.  The current default directory is
tried only if it is specified in @code{load-path}, where it is
represented as @code{nil}.  All three possible suffixes are tried in the
first directory in @code{load-path}, then all three in the second
directory in @code{load-path}, etc.

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

@cindex load errors
Any errors that are encountered while loading a file cause @code{load}
to abort.  If the load was done for the sake of @code{autoload}, certain
kinds of top-level forms, those which define functions, are undone.

@kindex file-error
The error @code{file-error} is signaled (with @samp{Cannot open load
file @var{filename}}) if no file is found.  No error is signaled 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 it exists; otherwise it is
set to the default specified in @file{emacs/src/paths.h} when Emacs is
built.

The syntax of @code{EMACSLOADPATH} is the same as that of @code{PATH};
fields are separated by @samp{:}, 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:

@example
setenv EMACSLOADPATH .:/user/liberte/emacs:/usr/local/lib/emacs/lisp
@end example

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

@example
export EMACSLOADPATH
EMACSLOADPATH=.:/user/liberte/emacs:/usr/local/lib/emacs/lisp
@end example

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

@example
(setq load-path
      (append
       (list nil
             "/user/liberte/emacs"
             "/usr/local/lisplib")
       load-path))
@end example

@noindent
In this example, the path searches the current working directory first,
followed by @file{/user/liberte/emacs} and @file{/usr/local/lisplib},
which are then followed by the standard directories for Lisp code.

When Emacs 18 is processing command options @samp{-l} or @samp{-load}
which specify Lisp libraries to be loaded, it temporarily adds the
current directory to the front of @code{load-path} so that files in the
current directory can be specified easily.  Emacs version 19 will 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, Repeated Loading, How Programs Do Loading, Loading
@section Autoload
@cindex autoload

  The @dfn{autoload} facility allows you to make a function or macro
available but put off loading its actual definition.  An attempt to call
a symbol whose definition is an autoload object automatically reads the
file to install the real definition and its other associated code, and
then calls the real definition.

@cindex function cell in autoload
  To prepare a function or macro for autoloading, you must call
@code{autoload}, specifying the function name and the name of
the file to be loaded.  This is usually done when Emacs is first
built, by files such as @file{emacs/lisp/loaddefs.el}.

  The following example shows how @code{doctor} is prepared for
autoloading in @file{loaddefs.el}:

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

@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 cause the documentation string to be put in the
@file{etc/DOC} file.  (@xref{Building Emacs}.)  In any other source
file, you would write just this:

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

  Calling @code{autoload} creates an autoload object containing the
name of the file and some other information, and makes this the
definition of the specified symbol.  When you later try to call that
symbol as a function or macro, the file is loaded; the loading should
redefine that symbol with its proper definition.  After the file
completes loading, the function or macro is called as if it had been
there originally.

@cindex autoload errors
  If, at the end of loading the file, the desired Lisp function or macro
has not been defined, then the error @code{error} is signaled (with data
@code{"Autoloading failed to define function @var{function-name}"}).

  The autoloaded file may, of course, contain 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 the 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 may fail to work properly for the lack of certain subroutines
defined later in the file and not loaded successfully.

@defun autoload symbol filename &optional docstring interactive macro
  This function defines the function (or macro) named @var{symbol} so as
to load automatically from @var{filename}.  The string @var{filename} is
a file name which will be passed to @code{load} when the function is
called.

  The argument @var{docstring} is the documentation string for the
function.  Normally, this is the same string that is in the function
definition itself.  This makes it possible to look at the documentation
without loading the 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.  If @var{macro} is non-@code{nil},
then the function is really a macro.

  If @var{symbol} already has a non-@code{nil} function definition that
is not an autoload object, @code{autoload} does nothing and returns
@code{nil}.  If the function cell of @var{symbol} is void, or is already
an autoload object, then it is set to an autoload object that looks like
this:

@example
(autoload @var{filename} @var{docstring} @var{interactive} @var{macro})
@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 is
the reference 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.
@end defun

@node Repeated Loading, Features, Autoload, Loading
@comment  node-name,  next,  previous,  up
@section Repeated Loading
@cindex repeated loading

  You may load a 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 in which it is
located.

  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 library, keep in mind that the library
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; you can do so as follows:

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

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

@node Features,, Repeated Loading, Loading
@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.

  The use of named features simplifies the task of determining whether
required definitions have been defined.  A feature name is a symbol that
stands for a collection of functions, variables, etc.  A program that
needs the collection may ensure that they are defined by @dfn{requiring}
the feature.  If the file that contains the feature has not yet been
loaded, then it will be loaded (or an error will be signaled if it
cannot be loaded).  The file thus loaded must @dfn{provide} the required
feature or an error will be signaled.
@cindex load error with provide

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

  Features are normally named after the files they are provided in
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:

@example
(interactive)
(require 'shell)
(switch-to-buffer (make-shell "prolog" "prolog"))
(inferior-prolog-mode))
@end example

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

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

@example
(provide 'shell)
@end example

@noindent
This adds @code{shell} to the global @code{features} list when the
@file{shell} file is loaded, so that @code{(require 'shell)} 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 if
you byte-compile that file (@pxref{Byte Compilation}).  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.

@example
(provide 'my-feature)  ; @r{Ignored by byte compiler, evaluated by @code{load}.}
(require 'my-feature)  ; @r{Evaluated by byte compiler.}
@end example

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

@example
features
     @result{} (bar bish)

(provide 'foo)
     @result{} foo
features
     @result{} (foo bar bish)
@end example

During autoloading, if the file is not completely loaded (due to an
error in the evaluation of the 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 @var{feature} is not provided after the file has been loaded,
Emacs will signal the error @code{error} (with data @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

