comparison lispref/loading.texi @ 21682:90da2489c498

*** empty log message ***

21681:11eafe90b842

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

In this example, the path searches the current working directory first,
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
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}.

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

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

@deffn Command locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library @var{library}.  It
searches for the library in the same way @code{load} does, and the
argument @var{nosuffix} has the same meaning as in @code{load}: don't

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

function.  Normally, this should be 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
is not 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.

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

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

@smallexample

@node Repeated Loading
@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, you need to byte-compile the new
version; otherwise Emacs will load the older, byte-compiled file instead
of your newer, non-compiled file!  If that happens, the message
displayed when loading the file says, ``(compiled; source is newer'', to
remind you to recompile.

  When writing the forms in a Lisp library file, keep in mind that the
file might be loaded more than once.  For example, think about whether
each variable should be reinitialized when you reload the library;
@code{defvar} does not change the value if the variable is already

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

(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{Named Features}.
@end ifinfo

@node Named Features

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 ()

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

@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

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

@code{unload-feature}:

@deffn Command unload-feature feature &optional force
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.  (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
@var{b} if @var{a} contains a @code{require} for @var{b}.)  If the
optional argument @var{force} is non-@code{nil}, dependencies are

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:

21682:90da2489c498

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

When loading a source file (not compiled), @code{load} performs
character set translation just as Emacs would do when visiting the file.
@xref{Coding Systems}.

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

In this example, the path searches the current working directory first,
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.

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

Normally, the variable's value is @code{nil}, which means those
functions should use @code{read}.
@end defvar

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

@deffn Command locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library @var{library}.  It
searches for the library in the same way @code{load} does, and the
argument @var{nosuffix} has the same meaning as in @code{load}: don't

  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 are the most convenient way to make a function
autoload, for packages installed along with Emacs.  They do nothing on
their own, but 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.

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

function.  Normally, this should be 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}, that says @var{function} can be
called interactively.  This lets completion in @kbd{M-x} work without
loading its real definition.  The complete interactive specification is
not 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.

@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 @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 @kbd{M-x 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

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

  You can 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, you need to byte-compile the new
version; otherwise Emacs will load the older, byte-compiled file instead
of your newer, non-compiled file!  If that happens, the message
displayed when loading the file includes, @samp{(compiled; source is
newer)}, to remind you to recompile it.

  When writing the forms in a Lisp library file, keep in mind that the
file might be loaded more than once.  For example, think about whether
each variable should be reinitialized when you reload the library;
@code{defvar} does not change the value if the variable is already

  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 nil)

(unless 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} earlier in the file to test whether the
@code{provide} call has been executed before.
@ifinfo
@xref{Named Features}.
@end ifinfo

@node Named Features

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

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

@smallexample
(defun run-prolog ()

@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.  Features are normally named after the files that provide them,
so that @code{require} need not be given the file name.

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

@smallexample
(provide 'comint)

@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 when the file is loaded.

@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

provided}.
@end defun

@defun featurep feature
This function returns @code{t} if @var{feature} has been provided in the
current Emacs session (i.e., if @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

@code{unload-feature}:

@deffn Command unload-feature feature &optional force
This command unloads the library that provided feature @var{feature}.
It undefines all functions, macros, and variables defined in that
library with @code{defun}, @code{defalias}, @code{defsubst},
@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
It then restores 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
@var{b} if @var{a} contains a @code{require} for @var{b}.)  If the
optional argument @var{force} is non-@code{nil}, dependencies are

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 for
programs meant for wider use.

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