⟦f9bc4d7d6⟧

TextFile

@setfilename ../info/loading
@node Loading, Byte Compilation, Evaluation, Top
@chapter Loading
@cindex loading
@cindex Lisp reader
@cindex library evaluation

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

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

  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 in a load file are function
and variable definitions.

@menu
* Loading Libraries::		Files containing code are called libraries.
* How Programs do Loading::
* Autoload::    
* Features::    
@end menu

@node Loading Libraries, How Programs do Loading, Loading, Loading
@comment  node-name,  next,  previous,  up
@section Lisp Libraries and Loading

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

  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.

  However, when you load or re-load 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!

  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
automatic loading (@pxref{Features}).  Ultimately, all these
facilities call the @code{load} function to do the work.

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

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

@node How Programs do Loading, Autoload, Loading Libraries, Loading
@section How Programs do Loading

@defun load filename &optional missing-ok nomessage nosuffix
  This function finds and opens a file of Lisp code, executes 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 @code{.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
filename must be specified precisely.

@vindex load-path
  If @var{filename} is a relative path, 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 the relative path to
each of the directories listed in @code{load-path}, and loading the
first file it finds whose name matches.  The current working directory
is tried only if it is specified in @code{load-path}, where it is
represented as @code{nil}.

  When @var{filename} is a relative file name, all three possible
filenames 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.el ...} and @samp{Loading foo.el ...
done} are printed in the echo area while loading unless
@var{nomessage} is non-@code{nil}.

@cindex 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 working 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 is interactive.  In
particular, @code{load-library} looks for @file{@var{library}.elc},
@file{@var{library}.el}, and @file{@var{library}} in that order in each
directory in @code{load-path}.
@end deffn
@end ignore

@defopt load-path
@vindex EMACSLOADPATH
  The value of this global 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 working directory.  Here is an example of how to set
your @code{EMACSLOADPATH} variable from a @file{.login} file:

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

@pindex .emacs load-path
  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/lib/emacs/local")
       load-path))
@end example

@noindent
In this example, the current working directory is placed first,
followed by @file{/user/liberte/emacs/} and
@file{/usr/local/lib/emacs/local}.
@end defopt

@defvar load-in-progress
  This global 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{autoload} determines whether a load is in progress.
@end defvar

@node Autoload, Features, How Programs do Loading, Loading
@section Autoload

  The @dfn{autoload} feature allows you to call a function or macro
whose function definition has not yet been loaded into Emacs.  An
attempt to call the symbol while its definition is an autoload-object
will automatically install the real definition and its other
associated code, and then call the real definition.

@cindex function cell in autoload
  To prepare a function or macro for autoloading, you must call
@code{autoload} on it, 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{dired} is prepared for
autoloading in @file{loaddefs.el}:

@example
(autoload 'dired "dired"
  "\                            ; @r{(@file{loaddefs.el} uses special}
\"Edit\" directory DIRNAME.     ; @r{formatting conventions.)}
  @dots{}
  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 a Lisp function or macro is not redefined by loading the file,
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 some 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 another
@code{autoload} attempt will result from the next attempt to call the
autoloading function.

@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}.  @var{filename} is a file name
which will be passed to @code{load} when the function is called.

  @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 for you to look at the documentation
without loading the file.

  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 symbol's 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 cell that is
not an @code{autoload} definition, @code{autoload} does nothing and
returns @code{nil}.  If the function cell of @var{symbol} is void, it
is set to an @code{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, @file{prolog} is the name of the file to load, 169681 is
the reference to the documentation string in the @file{emacs/etc/DOC}
file, @samp{t} means the function is interactive, and @samp{nil} that it
is not a macro.
@end defun

@node Features,  , Autoload, Loading
@section Features
@cindex features

  @code{provide} and @code{require} are another way to load files
automatically besides @code{autoload}, by named features.  While
autoloading is tied to particular functions, features are loaded whenever
another program says they are needed, but never more than once in a
session.

  The use of named features simplifies the task of determining whether
required definitions have been defined.  A feature name 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
name of the feature.  @code{require} looks in the global variable
@code{features} to see whether the desired feature has been provided
already.  If not, it loads the associated file.  The file that
contains the feature should call @code{provide} at the top-level to
add the feature to @code{features} once it is loaded.

  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)} means that if the @file{shell}
file has not yet been loaded, it will be loaded.  This ensures that
@code{make-shell} is defined.

Also, the @file{emacs/lisp/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 know
that nothing needs to be done.  (The order of the elements in the
@code{features} list is not significant.)

@cindex byte compiling 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 required contains macros that the byte-compiler
must know about.

  Although top-level calls to @code{require} are evaluated during the
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 load}
(require 'my-feature)  ; @r{evaluated by byte compiler}
@end example

@defun provide feature
  This function announces that @var{feature} is now loaded (or will be
as soon as this load is done) in the current Emacs session.  This means
that the facilities associated with @var{feature} are available for
other Lisp programs.

  The @var{feature} is added to the front of the list @code{features} if
it is not already in the list.  @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
@end defun

@defun require feature &optional filename
  This function looks to see if @var{feature} is present in the current
Emacs session (i.e., @code{(featurep @var{feature})} is true).  If it is
not, then @code{require} loads @var{filename} with @code{load}.  If
@var{filename} is not supplied, then @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 global variable is a list of symbols which are the
features loaded in the current Emacs session.  Each symbol was put in
this list with a call to @code{provide}.
@end defvar
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦f9bc4d7d6⟧ TextFile

Derivation

TextFile
