X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/e957f9ae90f3cab1584c06877cbff075d52a6a9a..6175e34b61bb75d18a91d4774c629fb6fb28ab32:/doc/lispref/loading.texi diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index bb8c34cadd..a406d4649d 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -1,19 +1,18 @@ @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 -@node Loading, Byte Compilation, Customization, Top +@node Loading @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 @@ -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. - 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. @@ -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 -@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 @@ -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}. -@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 +@example 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" -@end smallexample +@end example @noindent and -@smallexample +@example "/usr/local/share/emacs/site-lisp" -@end smallexample +@end example @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: + +@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 @@ -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 +@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 @@ -377,37 +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}. - 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 + 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 - 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 @@ -518,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 -@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, @@ -537,24 +533,24 @@ it is executed while building Emacs. 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)) -@end smallexample +@end example @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) -@end smallexample +@end example @noindent @cindex @code{fn} in function's documentation string @@ -573,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: -@smallexample +@example ;;;###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 @@ -679,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. - 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} -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: -@smallexample +@example (provide 'comint) -@end smallexample +@end example @noindent This adds @code{comint} to the global @code{features} list, so that @@ -722,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. -@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 -@end smallexample +@end example @noindent The compiler ignores the @code{provide}, then processes the @@ -758,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. -@smallexample +@example features @result{} (bar bish) @@ -766,7 +768,7 @@ features @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 @@ -969,7 +971,8 @@ example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory @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}. @@ -982,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}). -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 @@ -1000,7 +999,3 @@ symbol, and the value is a list of forms. The forms are evaluated 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