]> code.delx.au - gnu-emacs/blobdiff - doc/lispref/loading.texi
Merge from emacs-24; up to 2012-04-24T08:35:02Z!lekktu@gmail.com
[gnu-emacs] / doc / lispref / loading.texi
index 5733df87d17b280d78e3d95beea65f3c1284763d..c585bafbdeba6d1aaaa188f23edac13fe63f4a79 100644 (file)
@@ -1,19 +1,18 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @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, 2011
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @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
 @cindex library
 @cindex Lisp library
 
 @node Loading, Byte Compilation, Customization, Top
 @chapter Loading
 @cindex 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
 
   The load functions evaluate all the expressions in a file just
 as the @code{eval-buffer} function evaluates all the
@@ -30,11 +29,6 @@ into a buffer and evaluated there.  (Indeed, most code is tested this
 way.)  Most often, the forms are function definitions and variable
 definitions.
 
 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.
 @menu
 * How Programs Do Loading:: The @code{load} function and others.
 * Load Suffixes::           Details about the suffixes that @code{load} tries.
@@ -89,8 +83,8 @@ 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
 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
 
 If the optional argument @var{must-suffix} is non-@code{nil}, then
 @code{load} insists that the file name used must end in either
@@ -239,114 +233,87 @@ it skips the latter group.
   When Emacs loads a Lisp library, it searches for the library
 in a list of directories specified by the variable @code{load-path}.
 
   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).
 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
+@example
 export EMACSLOADPATH
 export EMACSLOADPATH
-EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
-@end smallexample
+EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
+@end example
 
 
-  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
-@end smallexample
+@example
+setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
+@end example
 
 
-@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):
-
-@smallexample
+  If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs
+initializes @code{load-path} with the following two directories:
+
+@example
 "/usr/local/share/emacs/@var{version}/site-lisp"
 "/usr/local/share/emacs/@var{version}/site-lisp"
-@end smallexample
+@end example
 
 @noindent
 and
 
 
 @noindent
 and
 
-@smallexample
+@example
 "/usr/local/share/emacs/site-lisp"
 "/usr/local/share/emacs/site-lisp"
-@end smallexample
+@end example
 
 @noindent
 The first one is for locally installed packages for a particular Emacs
 
 @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
 
   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.)
 
 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:
+
+@example
+(push "~/.emacs.d/lisp" load-path)
+@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,
+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
 @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
@@ -363,6 +330,31 @@ interactively, the argument @var{interactive-call} is @code{t}, and this
 tells @code{locate-library} to display the file name in the echo area.
 @end deffn
 
 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
+
+@example
+  ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")
+@end example
+
+@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
 
 @node Loading Non-ASCII
 @section Loading Non-@acronym{ASCII} Characters
 
@@ -377,30 +369,25 @@ 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}.
 
 unibyte text, and its string constants will be unibyte strings.
 @xref{Coding Systems}.
 
-  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
+  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{coding: raw-text} in a local variables section.  With
+that designator, the file will unconditionally be interpreted as
+unibyte.  This can matter when making keybindings to
 non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
 
 @node Autoload
 @section Autoload
 @cindex autoload
 
 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
 
   There are two ways to set up an autoloaded function: by calling
 @code{autoload}, and by writing a special ``magic'' comment in the
@@ -511,14 +498,30 @@ Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
 autoloads for all files in the current directory.
 
   The same magic comment can copy any kind of form into
 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,
 
   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,
@@ -530,24 +533,24 @@ it is executed while building Emacs.
   The following example shows how @code{doctor} is prepared for
 autoloading with a magic comment:
 
   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))
 ;;;###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}:
 
 
 @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)
 (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
 
 @noindent
 @cindex @code{fn} in function's documentation string
@@ -566,11 +569,11 @@ ordinary magic autoload comment would copy the whole definition into
 @code{loaddefs.el}.  That is not desirable.  You can put the desired
 @code{autoload} call into @code{loaddefs.el} instead by writing this:
 
 @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
   ...)
 ;;;###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
 
   You can use a non-default string as the autoload cookie and have the
 corresponding autoload calls written into a file whose name is
@@ -672,29 +675,35 @@ already.  If not, it loads the feature from the appropriate file.  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.
 
 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))
-@end smallexample
+@example
+(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 example
 
 @noindent
 The expression @code{(require 'comint)} loads the file @file{comint.el}
 
 @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:
 
 
 The @file{comint.el} file contains the following top-level expression:
 
-@smallexample
+@example
 (provide 'comint)
 (provide 'comint)
-@end smallexample
+@end example
 
 @noindent
 This adds @code{comint} to the global @code{features} list, so that
 
 @noindent
 This adds @code{comint} to the global @code{features} list, so that
@@ -715,13 +724,13 @@ ensure that a file of definitions is loaded before it is byte-compiled
 by including a @code{provide} followed by a @code{require} for the same
 feature, as in the following example.
 
 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
 @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
 
 @noindent
 The compiler ignores the @code{provide}, then processes the
@@ -751,7 +760,7 @@ package, which might or might not be loaded, or might or might not be
 present in a given version.  @xref{Network Feature Testing}, for
 an example.
 
 present in a given version.  @xref{Network Feature Testing}, for
 an example.
 
-@smallexample
+@example
 features
      @result{} (bar bish)
 
 features
      @result{} (bar bish)
 
@@ -759,7 +768,7 @@ features
      @result{} foo
 features
      @result{} (foo 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
 
 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
@@ -976,10 +985,6 @@ it immediately---there is no need to wait until the library is loaded.
 If you need to call functions defined by that library, you should load
 the library, preferably with @code{require} (@pxref{Named Features}).
 
 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
 @defvar after-load-alist
 This variable stores an alist built by @code{eval-after-load},
 containing the expressions to evaluate when certain libraries are