@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003,
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/loading
@node Loading, Byte Compilation, Customization, Top
containing Lisp code.
@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.
-* 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.
-* Unloading:: How to ``unload'' a library that was loaded.
-* Hooks for Loading:: Providing code to be run when
- particular libraries are loaded.
+* How Programs Do Loading:: The @code{load} function and others.
+* Load Suffixes:: Details about the suffixes that @code{load} tries.
+* Library Search:: Finding a library to load.
+* Loading Non-ASCII:: Non-@acronym{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.
+* Where Defined:: Finding which file defined a certain symbol.
+* 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
@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. By specifying the precise
-file name and using @code{t} for @var{nosuffix}, you can prevent
-perverse file names such as @file{foo.el.el} from being tried.
+If Auto Compression mode is enabled, as it is by default, then
+if @code{load} can not find a file, it searches for a compressed
+version of the file before trying other file names. It decompresses
+and loads it if it exists. It looks for compressed versions by
+appending the suffixes in @code{jka-compr-load-suffixes} to the file
+name. The value of this variable must be a list of strings. Its
+standard value is @code{(".gz")}.
+
+If the optional argument @var{nosuffix} is non-@code{nil}, then
+@code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In
+this case, you must specify the precise file name you want, except
+that, if Auto Compression mode is enabled, @code{load} will still use
+@code{jka-compr-load-suffixes} to find compressed versions. By
+specifying the precise file name and using @code{t} for
+@var{nosuffix}, you can prevent perverse file names such as
+@file{foo.el.el} from being tried.
If the optional argument @var{must-suffix} is non-@code{nil}, then
@code{load} insists that the file name used must end in either
-@samp{.el} or @samp{.elc}, unless it contains an explicit directory
-name. If @var{filename} does not contain an explicit directory name,
-and does not end in a suffix, then @code{load} insists on adding one.
+@samp{.el} or @samp{.elc} (possibly extended with a compression
+suffix), unless it contains an explicit directory name.
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
@deffn Command load-file filename
This command loads the file @var{filename}. If @var{filename} is a
relative file name, then the current default directory is assumed.
-@code{load-path} is not used, and suffixes are not appended. Use this
-command if you wish to specify precisely the file name to load.
+This command does not use @code{load-path}, and does not append
+suffixes. However, it does look for compressed versions (if Auto
+Compression Mode is enabled). Use this command if you wish to specify
+precisely the file name to load.
@end deffn
@deffn Command load-library library
@end defvar
@defvar load-read-function
+@anchor{Definition of load-read-function}
This variable specifies an alternate expression-reading function for
@code{load} and @code{eval-region} to use instead of @code{read}.
The function should accept one argument, just as @code{read} does.
Instead of using this variable, it is cleaner to use another, newer
feature: to pass the function as the @var{read-function} argument to
-@code{eval-region}. @xref{Eval}.
+@code{eval-region}. @xref{Definition of eval-region,, Eval}.
@end defvar
For information about how @code{load} is used in building Emacs, see
@ref{Building Emacs}.
+@node Load Suffixes
+@section Load Suffixes
+We now describe some technical details about the exact suffixes that
+@code{load} tries.
+
+@defvar load-suffixes
+This is a list of suffixes indicating (compiled or source) Emacs Lisp
+files. It should not include the empty string. @code{load} uses
+these suffixes in order when it appends Lisp suffixes to the specified
+file name. The standard value is @code{(".elc" ".el")} which produces
+the behavior described in the previous section.
+@end defvar
+
+@defvar load-file-rep-suffixes
+This is a list of suffixes that indicate representations of the same
+file. This list should normally start with the empty string.
+When @code{load} searches for a file it appends the suffixes in this
+list, in order, to the file name, before searching for another file.
+
+Enabling Auto Compression mode appends the suffixes in
+@code{jka-compr-load-suffixes} to this list and disabling Auto
+Compression mode removes them again. The standard value of
+@code{load-file-rep-suffixes} if Auto Compression mode is disabled is
+@code{("")}. Given that the standard value of
+@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value
+of @code{load-file-rep-suffixes} if Auto Compression mode is enabled
+is @code{("" ".gz")}.
+@end defvar
+
+@defun get-load-suffixes
+This function returns the list of all suffixes that @code{load} should
+try, in order, when its @var{must-suffix} argument is non-@code{nil}.
+This takes both @code{load-suffixes} and @code{load-file-rep-suffixes}
+into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes}
+and @code{load-file-rep-suffixes} all have their standard values, this
+function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto
+Compression mode is enabled and @code{(".elc" ".el")} if Auto
+Compression mode is disabled.
+@end defun
+
+To summarize, @code{load} normally first tries the suffixes in the
+value of @code{(get-load-suffixes)} and then those in
+@code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil},
+it skips the former group, and if @var{must-suffix} is non-@code{nil},
+it skips the latter group.
+
@node Library Search
@section Library Search
The value of @code{load-path} is initialized from the environment
variable @code{EMACSLOADPATH}, if that exists; otherwise its default
-value is specified in @file{emacs/src/paths.h} when Emacs is built.
+value is specified in @file{emacs/src/epaths.h} when Emacs is built.
Then the list is expanded by adding subdirectories of the directories
in the list.
tells @code{locate-library} to display the file name in the echo area.
@end deffn
-@defvar load-suffixes
-This variable is a list of suffixes (strings) that @code{load} should
-try adding to the specified file name. The default value is
-@code{(".el" ".elc")}. There is no need to include the null suffix.
-@end defvar
-
@node Loading Non-ASCII
-@section Loading Non-@sc{ascii} Characters
+@section Loading Non-@acronym{ASCII} Characters
- When Emacs Lisp programs contain string constants with non-@sc{ascii}
+ When Emacs Lisp programs contain string constants with non-@acronym{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-@acronym{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-@acronym{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
comment on the file's first line. 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-@sc{ascii} characters written as @code{?v@var{literal}}.
+non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
@node Autoload
@section Autoload
If @var{filename} does not contain either a directory name, or the
suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
one of these suffixes, and it will not load from a file whose name is
-just @var{filename} with no added suffix.
+just @var{filename} with no added suffix. (The variable
+@code{load-suffixes} specifies the exact required suffixes.)
The argument @var{docstring} is the documentation string for the
-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.
+function. 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. Normally, this should be
+identical to the documentation string in the function definition
+itself. If it isn't, the function definition's documentation string
+takes effect when it is loaded.
If @var{interactive} is non-@code{nil}, that says @var{function} can be
called interactively. This lets completion in @kbd{M-x} work without
@findex update-file-autoloads
@findex update-directory-autoloads
- A magic autoload comment consists of @samp{;;;###autoload}, on a line
-by itself, just before the real definition of the function in its
+@cindex magic autoload comment
+@cindex autoload cookie
+@anchor{autoload cookie}
+ A magic autoload comment (often called an @dfn{autoload cookie})
+consists of @samp{;;;###autoload}, on a line by itself,
+just before the real definition of the function in its
autoloadable source file. The command @kbd{M-x update-file-autoloads}
writes a corresponding @code{autoload} call into @file{loaddefs.el}.
Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
Here's what that produces in @file{loaddefs.el}:
@smallexample
-(autoload 'doctor "doctor" "\
-Switch to *doctor* buffer and start giving psychotherapy."
- t)
+(autoload (quote doctor) "doctor" "\
+Switch to *doctor* buffer and start giving psychotherapy.
+
+\(fn)" t nil)
@end smallexample
@noindent
+@cindex @code{fn} in function's documentation string
The backslash and newline immediately following the double-quote are a
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}.
+See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)}
+in the usage part of the documentation string is replaced with the
+function's name when the various help functions (@pxref{Help
+Functions}) display it.
If you write a function definition with an unusual macro that is not
one of the known and recognized function definition methods, use of an
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))
+(push '(leif-mode " Leif") minor-mode-alist)
@end example
@noindent
@example
(or (assq 'leif-mode minor-mode-alist)
- (setq minor-mode-alist
- (cons '(leif-mode " Leif") minor-mode-alist)))
+ (push '(leif-mode " Leif") minor-mode-alist))
@end example
- To add an element to a list just once, you can also use @code{add-to-list}
-(@pxref{Setting Variables}).
+@noindent
+or this:
+
+@example
+(add-to-list '(leif-mode " Leif") minor-mode-alist)
+@end example
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
@end smallexample
When a file is loaded to satisfy an autoload, and it stops due to an
-error in the evaluating its contents, any function definitions or
+error in the evaluation of its contents, any function definitions or
@code{provide} calls that occurred during the load are undone.
@xref{Autoload}.
@end defun
with @code{load}. If @var{filename} is not supplied, then the name of
the symbol @var{feature} is used as the base file name to load.
However, in this case, @code{require} insists on finding @var{feature}
-with an added suffix; a file whose name is just @var{feature} won't be
-used.
+with an added @samp{.el} or @samp{.elc} suffix (possibly extended with
+a compression suffix); a file whose name is just @var{feature} won't
+be used. (The variable @code{load-suffixes} specifies the exact
+required Lisp suffixes.)
+
+If @var{noerror} is non-@code{nil}, that suppresses errors from actual
+loading of the file. In that case, @code{require} returns @code{nil}
+if loading the file fails. Normally, @code{require} returns
+@var{feature}.
-If loading the file fails to provide @var{feature}, @code{require}
-signals an error, @samp{Required feature @var{feature} was not
-provided}, unless @var{noerror} is non-@code{nil}.
+If loading the file succeeds but does not provide @var{feature},
+@code{require} signals an error, @samp{Required feature @var{feature}
+was not provided}.
@end defun
@defun featurep feature &optional subfeature
@code{features} list is not significant.
@end defvar
+@node Where Defined
+@section Which File Defined a Certain Symbol
+
+@defun symbol-file symbol &optional type
+This function returns the name of the file that defined @var{symbol}.
+If @var{type} is @code{nil}, then any kind of definition is
+acceptable. If @var{type} is @code{defun} or @code{defvar}, that
+specifies function definition only or variable definition only.
+
+The value is normally an absolute file name. It can also be
+@code{nil}, if the definition is not associated with any file.
+@end defun
+
+ The basis for @code{symbol-file} is the data in the variable
+@code{load-history}.
+
+@defvar load-history
+This variable's value is an alist connecting library file 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 absolute file name of the library, as a string. The rest
+of the list elements have these forms:
+
+@table @code
+@item @var{var}
+The symbol @var{var} was defined as a variable.
+@item (defun . @var{fun})
+The function @var{fun} was defined.
+@item (t . @var{fun})
+The function @var{fun} was previously an autoload before this library
+redefined it as a function. The following element is always
+@code{(defun . @var{fun})}, which represents defining @var{fun} as a
+function.
+@item (autoload . @var{fun})
+The function @var{fun} was defined as an autoload.
+@item (require . @var{feature})
+The feature @var{feature} was required.
+@item (provide . @var{feature})
+The feature @var{feature} was provided.
+@end table
+
+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. @xref{Eval}.
+
@node Unloading
@section Unloading
@cindex unloading
The @code{unload-feature} function is written in Lisp; its actions are
based on the variable @code{load-history}.
-@defvar load-history
-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
-elements have these forms:
-
-@table @code
-@item @var{fun}
-The function @var{fun} was defined by this library.
-@item (t . @var{fun})
-The function @var{fun} was previously an autoload before this library
-redefined it as a function. The following element is always the
-symbol @var{fun}, which signifies that the library defined @var{fun}
-as a function.
-@item (autoload . @var{fun})
-The function @var{fun} was defined as an autoload.
-@item (defvar . @var{var})
-The symbol @var{var} was defined as a variable.
-@item (require . @var{feature})
-The feature @var{feature} was required.
-@item (provide . @var{feature})
-The feature @var{feature} was provided.
-@end table
-
-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. @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
+@defvar unload-feature-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