@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.
file if it isn't already loaded (@pxref{Named Features}). Ultimately,
all these facilities call the @code{load} function to do the work.
-@defun load filename &optional missing-ok nomessage nosuffix
+@defun load filename &optional missing-ok nomessage nosuffix must-suffix
This function finds and opens a file of Lisp code, evaluates all the
forms in it, and closes the file.
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.
+
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
@code{load-path}. It appends @var{filename} to each of the directories
in @code{load-path}, where @code{nil} stands for the default directory.
@code{load} tries all three possible suffixes in the first directory in
@code{load-path}, then all three suffixes in the second directory, and
-so on.
+so on. @xref{Library Search}.
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}.
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 the file to be loaded exactly.
+command if you wish to specify precisely the file name to load.
@end deffn
@deffn Command load-library library
@code{load}, except in how it reads its argument interactively.
@end deffn
+@defvar load-in-progress
+This variable is non-@code{nil} if Emacs is in the process of loading a
+file, and it is @code{nil} otherwise.
+@end defvar
+
+@defvar 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.
+
+Normally, the variable's value is @code{nil}, which means those
+functions should use @code{read}.
+
+@strong{Note:} 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}.
+@end defvar
+
+ For information about how @code{load} is used in building Emacs, see
+@ref{Building Emacs}.
+
+@node Library Search
+@section Library Search
+
+ When Emacs loads a Lisp library, it searches for the library
+in a list of directories specified by the variable @code{load-path}.
+
@defopt load-path
@cindex @code{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
-directory). 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.
+directory).
+@end defopt
-The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
+ 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.
+Then the list is expanded by adding subdirectories of the directories
+in the list.
+
+ The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
@samp{:} (or @samp{;}, according to the operating system) separates
directory names, and @samp{.} is used for the current default directory.
Here is an example of how to set your @code{EMACSLOADPATH} variable from
a @code{csh} @file{.login} file:
-@c This overfull hbox is OK. --rjc 16mar92
@smallexample
-setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
+setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
@end smallexample
-Here is how to set it using @code{sh}:
+ Here is how to set it using @code{sh}:
@smallexample
export EMACSLOADPATH
-EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
+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
+ 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}:
@smallexample
@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
+ 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
is used for execution of the dumped Emacs also.
-Therefore, if you want to change @code{load-path} temporarily for
+ Therefore, if you want to change @code{load-path} temporarily for
loading a few libraries in @file{site-init.el} or @file{site-load.el},
you should bind @code{load-path} locally with @code{let} around the
calls to @code{load}.
-@end defopt
The default value of @code{load-path}, when running an Emacs which has
-been installed on the system, looks like this:
+been installed on the system, includes two special directories (and
+their subdirectories as well):
@smallexample
-("/usr/local/share/emacs/@var{version}/site-lisp"
- "/usr/local/share/emacs/site-lisp"
- "/usr/local/share/emacs/@var{version}/lisp")
+"/usr/local/share/emacs/@var{version}/site-lisp"
@end smallexample
- The last of these three directories is where the Lisp files of Emacs
-itself are installed; the first two are for additional Lisp packages
-installed at your site. The first directory is for locally installed
-packages that belong with a particular Emacs version; the second is for
-locally installed packages that can be used with any installed Emacs
-version.
+@noindent
+and
+
+@smallexample
+"/usr/local/share/emacs/site-lisp"
+@end smallexample
+
+@noindent
+The first one is for locally installed packages for a particular Emacs
+version; the second is for locally installed packages meant for use with
+all installed Emacs versions.
There are several reasons why a Lisp package that works well in one
Emacs version can cause trouble in another. Sometimes packages need
sometimes a newer Emacs version incorporates a version of the package,
and should be used only with that version.
+ Emacs finds these directories' subdirectories and adds them to
+@code{load-path} when it starts up. Both immediate subdirectories and
+subdirectories multiple levels down are added to @code{load-path}.
+
+ 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.
+
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}
normally contains two additional directories. These are the @code{lisp}
and @code{site-lisp} subdirectories of the main build directory. (Both
are represented as absolute file names.)
-@defvar load-in-progress
-This variable is non-@code{nil} if Emacs is in the process of loading a
-file, and it is @code{nil} otherwise.
-@end defvar
-
-@defvar 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.
-
-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
tells @code{locate-library} to display the file name in the echo area.
@end deffn
+@node Loading Non-ASCII
+@section Loading Non-ASCII Characters
+
+ 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
+it is read with decoding into multibyte representation, the text of the
+Lisp program will be multibyte text, and its string constants will be
+multibyte strings. If a file containing Latin-1 characters (for
+example) is read without decoding, the text of the program will be
+unibyte text, and its string constants will be unibyte strings.
+@xref{Coding Systems}.
+
+ 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
+strings. The only exception is when a particular file specifies no
+decoding.
+
+ The reason Emacs is designed this way is so that Lisp programs give
+predictable results, regardless of how Emacs was started. In addition,
+this enables programs that depend on using multibyte text to work even
+in a unibyte Emacs. Of course, such programs should be designed to
+notice whether the user prefers unibyte or multibyte text, by checking
+@code{default-enable-multibyte-characters}, and convert representations
+appropriately.
+
+ 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{-*-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.
+
@node Autoload
@section Autoload
@cindex autoload
@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.
+any time. Magic comments are the most convenient way to make a function
+autoload, for packages installed along with Emacs. These comments 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
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.
+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 @var{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.
definitions or @code{provide} calls that occurred during the load are
undone. This is to ensure that the next attempt to call any function
autoloading from this file will try again to load the file. If not for
-this, then some of the functions in the file might appear defined, but
-they might fail to work properly for the lack of certain subroutines
-defined later in the file and not loaded successfully.
+this, then some of the functions in the file might be defined by the
+aborted load, but fail to work properly for the lack of certain
+subroutines not loaded successfully because they come later in the file.
If the autoloaded file fails to define the desired Lisp function or
macro, then an error is signaled with data @code{"Autoloading failed to
@findex update-file-autoloads
@findex update-directory-autoloads
- A magic autoload comment looks like @samp{;;;###autoload}, on a line
+ A magic autoload comment 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}.
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.
+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:
@section Repeated Loading
@cindex repeated loading
- You may load one file more than once in an Emacs session. For
+ You can load a given 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.
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.
+displayed when loading the file includes, @samp{(compiled; note, 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
(cons '(leif-mode " Leif") minor-mode-alist)))
@end example
- To add an element to a list just once, use @code{add-to-list}
+ To add an element to a list just once, you can also use @code{add-to-list}
(@pxref{Setting Variables}).
Occasionally you will want to test explicitly whether a library has
has been loaded before:
@example
-(defvar foo-was-loaded)
-
-(if (not (boundp 'foo-was-loaded))
- @var{execute-first-time-only})
+(defvar foo-was-loaded nil)
-(setq foo-was-loaded t)
+(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} to test whether the library has been loaded.
+use @code{featurep} earlier in the file to test whether the
+@code{provide} call has been executed before.
@ifinfo
@xref{Named Features}.
@end ifinfo
@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:
@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.
+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:
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.
+does nothing when the file is loaded.
@defun provide feature
This function announces that @var{feature} is now loaded, or being
@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
This function returns @code{t} if @var{feature} has been provided in the
-current Emacs session (i.e., @var{feature} is a member of
+current Emacs session (i.e., if @var{feature} is a member of
@code{features}.)
@end defun
@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.)
+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.)
+
+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.
Ordinarily, @code{unload-feature} refuses to unload a library on which
other loaded libraries depend. (A library @var{a} depends on library
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.
+rather than replacing that element. @xref{Eval}.
+
+ Preloaded libraries don't contribute to @code{load-history}.
+
+@tindex loadhist-special-hooks
+@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
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.
+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
HCoop / bpt / emacs.git / blobdiff