@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@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
@cindex library
@cindex Lisp library
- Loading a file of Lisp code means bringing its contents into the Lisp
-environment in the form of Lisp objects. Emacs finds and opens the
-file, reads the text, evaluates each form, and then closes the file.
+ Loading a file of Lisp code means bringing its contents into the
+Lisp environment in the form of Lisp objects. Emacs finds and opens
+the file, reads the text, evaluates each form, and then closes the
+file. Such a file is also called a @dfn{Lisp library}.
The load functions evaluate all the expressions in a file just
as the @code{eval-buffer} function evaluates all the
way.) Most often, the forms are function definitions and variable
definitions.
- A file containing Lisp code is often called a @dfn{library}. Thus,
-the ``Rmail library'' is a file containing code for Rmail mode.
-Similarly, a ``Lisp library directory'' is a directory of files
-containing Lisp code.
-
@menu
* How Programs Do Loading:: The @code{load} function and others.
* Load Suffixes:: Details about the suffixes that @code{load} tries.
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.
+@var{nosuffix}, you can prevent file names like @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
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
+@defvar load-path
+@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
directory).
-@end defopt
-
- 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/epaths.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:
-
-@smallexample
-setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
-@end smallexample
+@end defvar
- Here is how to set it using @code{sh}:
+ Each time Emacs starts up, it sets up the value of @code{load-path}
+in several steps. First, it initializes @code{load-path} to the
+directories specified by the environment variable @env{EMACSLOADPATH},
+if that exists. The syntax of @env{EMACSLOADPATH} is the same as used
+for @code{PATH}; directory names are separated by @samp{:} (or
+@samp{;}, on some operating systems), and @samp{.} stands for the
+current default directory. Here is an example of how to set
+@env{EMACSLOADPATH} variable from @command{sh}:
@smallexample
export EMACSLOADPATH
-EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
+EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
@end smallexample
- 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}:
+@noindent
+Here is how to set it from @code{csh}:
@smallexample
-@group
-(setq load-path
- (append (list nil "/user/bil/emacs"
- "/usr/local/lisplib"
- "~/emacs")
- load-path))
-@end group
+setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
@end smallexample
-@c Wordy to rid us of an overfull hbox. --rjc 15mar92
-@noindent
-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
-is used for execution of the dumped Emacs also.
-
- 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}.
-
- The default value of @code{load-path}, when running an Emacs which has
-been installed on the system, includes two special directories (and
-their subdirectories as well):
+ If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs
+initializes @code{load-path} with the following two directories:
@smallexample
"/usr/local/share/emacs/@var{version}/site-lisp"
@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
-updating for incompatible changes in Emacs; sometimes they depend on
-undocumented internal Emacs data that can change without notice;
-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} 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.
+version; the second is for locally installed packages meant for use
+with all installed Emacs versions.
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
+executable that has not been formally installed---Emacs puts two more
+directories in @code{load-path}. These are the @code{lisp} and
+@code{site-lisp} subdirectories of the main build directory. (Both
are represented as absolute file names.)
+ Next, Emacs ``expands'' the initial list of directories in
+@code{load-path} by adding the subdirectories of those directories.
+Both immediate subdirectories and subdirectories multiple levels down
+are added. But it excludes subdirectories whose names do not start
+with a letter or digit, and subdirectories named @file{RCS} or
+@file{CVS}, and subdirectories containing a file named
+@file{.nosearch}.
+
+ Next, Emacs adds any extra load directory that you specify using the
+@samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The
+GNU Emacs Manual}). It also adds the directories where optional
+packages are installed, if any (@pxref{Packaging Basics}).
+
+ 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
+(push "~/.emacs.d/lisp" load-path)
+@end smallexample
+
+ 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.
+
@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
+@cindex shadowed Lisp files
+@deffn Command list-load-path-shadows &optional stringp
+This command shows a list of @dfn{shadowed} Emacs Lisp files. A
+shadowed file is one that will not normally be loaded, despite being
+in a directory on @code{load-path}, due to the existence of another
+similarly-named file in a directory earlier on @code{load-path}.
+
+For instance, suppose @code{load-path} is set to
+
+@smallexample
+ ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
+@end smallexample
+
+@noindent
+and that both these directories contain a file named @file{foo.el}.
+Then @code{(require 'foo)} never loads the file in the second
+directory. Such a situation might indicate a problem in the way Emacs
+was installed.
+
+When called from Lisp, this function prints a message listing the
+shadowed files, instead of displaying them in a buffer. If the
+optional argument @code{stringp} is non-@code{nil}, it instead returns
+the shadowed files as a string.
+@end deffn
+
@node Loading Non-ASCII
@section Loading Non-@acronym{ASCII} Characters
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-@acronym{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.
-
- 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
-interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
-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-@acronym{ASCII} characters written as @code{?v@var{literal}}.
+ 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 interpreted as unibyte by writing
+@samp{unibyte: t} 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}}.
@node Autoload
@section Autoload
@cindex autoload
- The @dfn{autoload} facility allows you to make a function or macro
-known in Lisp, but put off loading the file that defines it. The first
-call to the function automatically reads the proper file to install the
-real definition and other associated code, then runs the real definition
-as if it had been loaded all along.
+ The @dfn{autoload} facility allows you to register the existence of
+a function or macro, but put off loading the file that defines it.
+The first call to the function automatically reads the proper file, in
+order to install the real definition and other associated code, then
+runs the real definition as if it had been loaded all along.
There are two ways to set up an autoloaded function: by calling
@code{autoload}, and by writing a special ``magic'' comment in the
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-derived-mode}, @code{define-minor-mode},
+@code{define-compilation-mode}, @code{define-generic-mode},
+@code{easy-mmode-define-global-mode}, @code{define-global-minor-mode},
+@code{define-globalized-minor-mode}, and
+@code{easy-mmode-define-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,
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.
- For example, in @file{emacs/lisp/prolog.el},
-the definition for @code{run-prolog} includes the following code:
+ For example, in @file{idlwave.el}, the definition for
+@code{idlwave-complete-filename} includes the following code:
@smallexample
-(defun run-prolog ()
- "Run an inferior Prolog process, with I/O via buffer *prolog*."
- (interactive)
- (require 'comint)
- (switch-to-buffer (make-comint "prolog" prolog-program-name))
- (inferior-prolog-mode))
+(defun idlwave-complete-filename ()
+ "Use the comint stuff to complete a file name."
+ (require 'comint)
+ (let* ((comint-file-name-chars "~/A-Za-z0-9+@:_.$#%=@{@}\\-")
+ (comint-completion-addsuffix nil)
+ ...)
+ (comint-dynamic-complete-filename)))
@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.
+if it has not yet been loaded, ensuring that
+@code{comint-dynamic-complete-filename} is defined. Features are
+normally named after the files that provide them, so that
+@code{require} need not be given the file name. (Note that it is
+important that the @code{require} statement be outside the body of the
+@code{let}. Loading a library while its variables are let-bound can
+have unintended consequences, namely the variables becoming unbound
+after the let exits.)
The @file{comint.el} file contains the following top-level expression:
@end example
@var{library} can also be a feature (i.e.@: a symbol), in which case
-@var{form} is evaluated when @code{(provide @var{library})} is called.
+@var{form} is evaluated at the end of any file where
+@code{(provide @var{library})} is called.
An error in @var{form} does not undo the load, but does prevent
execution of the rest of @var{form}.
If you need to call functions defined by that library, you should load
the library, preferably with @code{require} (@pxref{Named Features}).
-But it is OK to use @code{eval-after-load} in your personal
-customizations if you don't feel that they must meet the design
-standards for programs meant for wider use.
-
@defvar after-load-alist
This variable stores an alist built by @code{eval-after-load},
containing the expressions to evaluate when certain libraries are
when the key matches the absolute true name or feature name of the
library being loaded.
@end defvar
-
-@ignore
- arch-tag: df731f89-0900-4389-a436-9105241b6f7a
-@end ignore
HCoop / bpt / emacs.git / blobdiff