@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/loading
@node Loading, Byte Compilation, Customization, Top
@menu
* How Programs Do Loading:: The @code{load} function and others.
* Library Search:: Finding a library to load.
-* Loading Non-ASCII:: Non-@sc{ASCII} characters in Emacs Lisp files.
+* Loading Non-ASCII:: Non-@sc{ascii} characters in Emacs Lisp files.
* Autoload:: Setting up a function to autoload.
* Repeated Loading:: Precautions about loading a file twice.
* Named Features:: Loading a library if it isn't already loaded.
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/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}:
+ Here is an example of code you can place in your init file (@pxref{Init
+File}) to add several directories to the front of your default
+@code{load-path}:
@smallexample
@group
Not all subdirectories are included, though. Subdirectories whose
names do not start with a letter or digit are excluded. Subdirectories
-named @file{RCS} are excluded. Also, a subdirectory which contains a
-file named @file{.nosearch} is excluded. You can use these methods to
-prevent certain subdirectories of the @file{site-lisp} directories from
-being searched.
+named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which
+contains a file named @file{.nosearch} is excluded. You can use these
+methods to prevent certain subdirectories of the @file{site-lisp}
+directories from being searched.
If you run Emacs from the directory where it was built---that is, an
executable that has not been formally installed---then @code{load-path}
@end deffn
@node Loading Non-ASCII
-@section Loading Non-ASCII Characters
+@section Loading Non-@sc{ascii} Characters
- When Emacs Lisp programs contain string constants with non-@sc{ASCII}
+ When Emacs Lisp programs contain string constants with non-@sc{ascii}
characters, these can be represented within Emacs either as unibyte
strings or as multibyte strings (@pxref{Text Representations}). Which
representation is used depends on how the file is read into Emacs. If
To make the results more predictable, Emacs always performs decoding
into the multibyte representation when loading Lisp files, even if it
was started with the @samp{--unibyte} option. This means that string
-constants with non-@sc{ASCII} characters translate into multibyte
+constants with non-@sc{ascii} characters translate into multibyte
strings. The only exception is when a particular file specifies no
decoding.
@code{default-enable-multibyte-characters}, and convert representations
appropriately.
- In most Emacs Lisp programs, the fact that non-@sc{ASCII} strings are
+ In most Emacs Lisp programs, the fact that non-@sc{ascii} strings are
multibyte strings should not be noticeable, since 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{-*-coding: raw-text;-*-} in a
+interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
comment on the file's first line. With that designator, the file will
-be unconditionally be interpreted as unibyte, even in an ordinary
-multibyte Emacs session.
+unconditionally be interpreted as unibyte, even in an ordinary
+multibyte Emacs session. This can matter when making keybindings to
+non-@sc{ascii} characters written as @code{?v@var{literal}}.
@node Autoload
@section Autoload
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 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.
+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}.
+
+ 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:
Here's what that produces in @file{loaddefs.el}:
@smallexample
-(autoload 'doctor "doctor"
- "\
+(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
+convention used only in the preloaded uncompiled Lisp files such as
@file{loaddefs.el}; they tell @code{make-docfile} to put the
documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
+See also the commentary in @file{lib-src/make-docfile.c}.
@node Repeated Loading
@section Repeated Loading
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
+@ifnottex
@xref{Named Features}.
-@end ifinfo
+@end ifnottex
@node Named Features
@section Features
When @code{require} is used at top level in a file, it takes effect
when you byte-compile that file (@pxref{Byte Compilation}) as well as
when you load it. This is in case the required package contains macros
-that the byte compiler must know about.
+that the byte compiler must know about. It also avoids byte-compiler
+warnings for functions and variables defined in the file loaded with
+@code{require}.
Although top-level calls to @code{require} are evaluated during
byte compilation, @code{provide} calls are not. Therefore, you can
@xref{Autoload}.
@end defun
-@defun require feature &optional filename
+@defun require feature &optional filename noerror
This function checks whether @var{feature} is present in the current
Emacs session (using @code{(featurep @var{feature})}; see below). The
argument @var{feature} must be a symbol.
If loading the file fails to provide @var{feature}, @code{require}
signals an error, @samp{Required feature @var{feature} was not
-provided}.
+provided}, unless @var{noerror} is non-@code{nil}.
@end defun
@defun featurep feature
It then restores any autoloads formerly associated with those symbols.
(Loading saves these in the @code{autoload} property of the symbol.)
+Before restoring the previous definitions, @code{unload-feature} runs
+@code{remove-hook} to remove functions in the library from certain
+hooks. These hooks include variables whose names end in @samp{hook} or
+@samp{-hooks}, plus those listed in @code{loadhist-special-hooks}. This
+is to prevent Emacs from ceasing to function because important hooks
+refer to functions that are no longer defined.
+
+@vindex @var{feature}-unload-hook
+If these measures are not sufficient to prevent malfunction, a library
+can define an explicit unload hook. If @code{@var{feature}-unload-hook}
+is defined, it is run as a normal hook before restoring the previous
+definitions, @emph{instead of} the usual hook-removing actions. The
+unload hook ought to undo all the global state changes made by the
+library that might cease to work once the library is unloaded.
+@code{unload-feature} can cause problems with libraries that fail to do
+this, so it should be used with caution.
+
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
@item
Symbols that were defined by this library.
@item
-Lists of the form @code{(require . @var{feature})} indicating
+Cons cells of the form @code{(require . @var{feature})} indicating
features that were required.
@item
-Lists of the form @code{(provide . @var{feature})} indicating
+Cons cells of the form @code{(provide . @var{feature})} indicating
features that were provided.
@end itemize
by adding the symbols defined to the element for the file being visited,
rather than replacing that element. @xref{Eval}.
+ Preloaded libraries don't contribute initially to @code{load-history}.
+Instead, preloading writes information about preloaded libraries into a
+file, which can be loaded later on to add information to
+@code{load-history} describing the preloaded files. This file is
+installed in @code{exec-directory} and has a name of the form
+@file{fns-@var{emacsversion}.el}.
+
+@findex symbol-file
+ See the source for the function @code{symbol-file}, for an example of
+code that loads this file to find functions in preloaded libraries.
+
+@defvar loadhist-special-hooks
+This variable holds a list of hooks to be scanned before unloading a
+library, to remove functions defined in the library.
+@end defvar
+
@node Hooks for Loading
@section Hooks for Loading
@cindex loading hooks
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:
+This variable holds an alist of expressions to evaluate if and when
+particular libraries are loaded. Each element looks like this:
@example
(@var{filename} @var{forms}@dots{})