@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/loading
@node Loading, Byte Compilation, Customization, Top
@chapter Loading
@cindex loading
in a list of directories specified by the variable @code{load-path}.
@defvar load-path
-@cindex @code{EMACSLOADPATH} environment variable
+@cindex @env{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
current default directory. Here is an example of how to set
@env{EMACSLOADPATH} variable from @command{sh}:
-@smallexample
+@example
export EMACSLOADPATH
EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
-@end smallexample
+@end example
@noindent
Here is how to set it from @code{csh}:
-@smallexample
+@example
setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
-@end smallexample
+@end example
If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs
initializes @code{load-path} with the following two directories:
-@smallexample
+@example
"/usr/local/share/emacs/@var{version}/site-lisp"
-@end smallexample
+@end example
@noindent
and
-@smallexample
+@example
"/usr/local/share/emacs/site-lisp"
-@end smallexample
+@end example
@noindent
The first one is for locally installed packages for a particular Emacs
It is common to add code to one's init file (@pxref{Init File}) to
add one or more directories to @code{load-path}. For example:
-@smallexample
+@example
(push "~/.emacs.d/lisp" load-path)
-@end smallexample
+@end example
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,
For instance, suppose @code{load-path} is set to
-@smallexample
+@example
("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
-@end smallexample
+@end example
@noindent
and that both these directories contain a file named @file{foo.el}.
inserting them in unibyte buffers converts them to unibyte
automatically. However, if this does make a difference, you can force
a particular Lisp file to be interpreted as unibyte by writing
-@samp{-*-unibyte: t;-*-} in a comment on the file's first line. With
+@samp{coding: raw-text} in a local variables section. With
that designator, the file will unconditionally be interpreted as
-unibyte, even in an ordinary multibyte Emacs session. This can matter
-when making keybindings to non-@acronym{ASCII} characters written as
-@code{?v@var{literal}}.
+unibyte. This can matter when making keybindings to
+non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
@node Autoload
@section Autoload
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-defining form or a @code{defcustom} form, it is copied
-verbatim. ``Function-defining forms'' include @code{define-skeleton},
-@code{define-derived-mode}, @code{define-generic-mode} and
-@code{define-minor-mode} as well as @code{defun} and
-@code{defmacro}. To save space, a @code{defcustom} form is converted to
-a @code{defvar} in @file{loaddefs.el}, with some additional information
-if it uses @code{:require}.
+@file{loaddefs.el}. The form following the magic comment is copied
+verbatim, @emph{except} if it is one of the forms which the autoload
+facility handles specially (e.g.@: by conversion into an
+@code{autoload} call). The forms which are not copied verbatim are
+the following:
+
+@table @asis
+@item Definitions for function or function-like objects:
+@code{defun} and @code{defmacro}; also @code{defun*} and
+@code{defmacro*} (@pxref{Argument Lists,,,cl,CL Manual}), and
+@code{define-overloadable-function} (see the commentary in
+@file{mode-local.el}).
+
+@item Definitions for major or minor modes:
+@code{define-minor-mode}, @code{define-globalized-minor-mode},
+@code{define-generic-mode}, @code{easy-mmode-define-minor-mode},
+@code{easy-mmode-define-global-mode}, @code{define-compilation-mode},
+@code{define-derived-mode}, and @code{define-global-minor-mode}.
+
+@item Other definition types:
+@code{defcustom}, @code{defgroup}, @code{defclass}
+(@pxref{Top,EIEIO,,eieio,EIEIO}), and @code{define-skeleton} (see the
+commentary in @file{skeleton.el}).
+@end table
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,
The following example shows how @code{doctor} is prepared for
autoloading with a magic comment:
-@smallexample
+@example
;;;###autoload
(defun doctor ()
"Switch to *doctor* buffer and start giving psychotherapy."
(interactive)
(switch-to-buffer "*doctor*")
(doctor-mode))
-@end smallexample
+@end example
@noindent
Here's what that produces in @file{loaddefs.el}:
-@smallexample
+@example
(autoload (quote doctor) "doctor" "\
Switch to *doctor* buffer and start giving psychotherapy.
\(fn)" t nil)
-@end smallexample
+@end example
@noindent
@cindex @code{fn} in function's documentation string
@code{loaddefs.el}. That is not desirable. You can put the desired
@code{autoload} call into @code{loaddefs.el} instead by writing this:
-@smallexample
+@example
;;;###autoload (autoload 'foo "myfile")
(mydefunmacro foo
...)
-@end smallexample
+@end example
You can use a non-default string as the autoload cookie and have the
corresponding autoload calls written into a file whose name is
For example, in @file{idlwave.el}, the definition for
@code{idlwave-complete-filename} includes the following code:
-@smallexample
+@example
(defun idlwave-complete-filename ()
"Use the comint stuff to complete a file name."
(require 'comint)
(comint-completion-addsuffix nil)
...)
(comint-dynamic-complete-filename)))
-@end smallexample
+@end example
@noindent
The expression @code{(require 'comint)} loads the file @file{comint.el}
The @file{comint.el} file contains the following top-level expression:
-@smallexample
+@example
(provide 'comint)
-@end smallexample
+@end example
@noindent
This adds @code{comint} to the global @code{features} list, so that
by including a @code{provide} followed by a @code{require} for the same
feature, as in the following example.
-@smallexample
+@example
@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
+@end example
@noindent
The compiler ignores the @code{provide}, then processes the
present in a given version. @xref{Network Feature Testing}, for
an example.
-@smallexample
+@example
features
@result{} (bar bish)
@result{} foo
features
@result{} (foo bar bish)
-@end smallexample
+@end example
When a file is loaded to satisfy an autoload, and it stops due to an
error in the evaluation of its contents, any function definitions or