@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. 
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/loading.info
@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.  XEmacs 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.
* 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

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

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

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

When Emacs version 18 processes 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.  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 XEmacs 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 XEmacs, see @ref{Building XEmacs}.

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

@c Rewritten to avoid overfull hbox.  --rjc 16mar92
@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.  A file such as @file{emacs/lisp/loaddefs.el} usually does
this when XEmacs is first built.

  The following example shows how @code{doctor} is prepared for
autoloading 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 cause the documentation string to be put in the
@file{etc/DOC} file.  (@xref{Building XEmacs}.)  In any other source
file, you would write just this:

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

  Calling @code{autoload} creates an autoload object containing the name
of the file and some other information, and makes this the function
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.

  XEmacs as distributed comes with many autoloaded functions.
The calls to @code{autoload} are in the file @file{loaddefs.el}.
There is a convenient way of updating them automatically.

@findex update-file-autoloads
@findex update-directory-autoloads
  Write @samp{;;;###autoload} on a line by itself before the real
definition of the function, in its autoloadable source file; then the
command @kbd{M-x update-file-autoloads} automatically puts the
@code{autoload} call into @file{loaddefs.el}.  @kbd{M-x
update-directory-autoloads} is more powerful; it updates autoloads for
all files in the current directory.

  You can also put other kinds of forms into @file{loaddefs.el}, by
writing @samp{;;;###autoload} followed on the same line by the form.
@kbd{M-x update-file-autoloads} copies the form from that line.

  The commands for updating autoloads work by visiting and editing the
file @file{loaddefs.el}.  To make the result take effect, you must save
that file's buffer.

@defun autoload symbol filename &optional docstring interactive type
  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{type} is @code{macro},
then the function is really a macro.  If @var{type} is @code{keymap},
then the function is really a keymap.

  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{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.
@end defun

@node Repeated Loading
@section Repeated Loading
@cindex repeated loading

  You may load a file more than once in an XEmacs 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
@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:

@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 when the
@file{comint} file is loaded, 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 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.

@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

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

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
XEmacs 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, XEmacs
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 XEmacs 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 XEmacs 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 and variables defined with @code{defvar},
@code{defmacro}, @code{defconst}, @code{defsubst} and
@code{defalias} by the library which provided feature
@var{feature}.  It then restores any autoloads 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 feature association list
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, which were defined as functions or variables.
@item
Lists of the form @code{(require . @var{feature})} indicating the
features that are required.
@item
Lists of the form @code{(provide . @var{feature})} indicating the
features that are 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
