Mercurial > emacs
view lispref/loading.texi @ 21810:15f5abff4d9b
[HAVE_MENUS]: Include xterm.h only if HAVE_X_WINDOWS.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Tue, 28 Apr 1998 21:21:14 +0000 |
parents | 90da2489c498 |
children | d4ac295a98b3 |
line wrap: on
line source
@c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 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 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. The load functions evaluate all the expressions in a file just as the @code{eval-current-buffer} function evaluates all the expressions in a buffer. The difference is that the load functions read and evaluate the text in the file as found on disk, not the text in an Emacs buffer. @cindex top-level form The loaded file must contain Lisp expressions, either as source code or as byte-compiled code. Each form in the file is called a @dfn{top-level form}. There is no special format for the forms in a loadable file; any form in a file may equally well be typed directly 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. * 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. @end menu @node How Programs Do Loading @section How Programs Do Loading Emacs Lisp has several interfaces for loading. For example, @code{autoload} creates a placeholder object for a function defined in a file; trying to call the autoloading function loads the file to get the function's real definition (@pxref{Autoload}). @code{require} loads a 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 This function finds and opens a file of Lisp code, evaluates all the forms in it, and closes the file. To find the file, @code{load} first looks for a file named @file{@var{filename}.elc}, that is, for a file whose name is @var{filename} with @samp{.elc} appended. If such a file exists, it is loaded. If there is no file by that name, then @code{load} looks for a file named @file{@var{filename}.el}. If that file exists, it is loaded. Finally, if neither of those names is found, @code{load} looks for a file named @var{filename} with nothing appended, and loads it if it exists. (The @code{load} function is not clever about looking at @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 @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 listed in @code{load-path}, and loads the first file it finds whose name matches. The current default directory is tried only if it is specified 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. 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}. @cindex load errors Any unhandled errors while loading a file terminate loading. If the load was done for the sake of @code{autoload}, any function definitions made during the loading are undone. @kindex file-error If @code{load} can't find the file to load, then normally it signals the error @code{file-error} (with @samp{Cannot open load file @var{filename}}). But if @var{missing-ok} is non-@code{nil}, then @code{load} just returns @code{nil}. You can use the variable @code{load-read-function} to specify a function for @code{load} to use instead of @code{read} for reading expressions. See below. @code{load} returns @code{t} if the file loads successfully. @end defun @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 the file to be loaded exactly. @end deffn @deffn Command load-library library This command loads the library named @var{library}. It is equivalent to @code{load}, except in how it reads its argument interactively. @end deffn @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. 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 @end smallexample Here is how to set it using @code{sh}: @smallexample export EMACSLOADPATH EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp @end smallexample 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 @group (setq load-path (append (list nil "/user/bil/emacs" "/usr/local/lisplib" "~/emacs") load-path)) @end group @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}. @end defopt The default value of @code{load-path}, when running an Emacs which has been installed on the system, looks like this: @smallexample ("/usr/local/share/emacs/@var{version}/site-lisp" "/usr/local/share/emacs/site-lisp" "/usr/local/share/emacs/@var{version}/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. 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. 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 For 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 argument @var{nosuffix} has the same meaning as in @code{load}: don't add suffixes @samp{.elc} or @samp{.el} to the specified name @var{library}. If the @var{path} is non-@code{nil}, that list of directories is used instead of @code{load-path}. When @code{locate-library} is called from a program, it returns the file name as a string. When the user runs @code{locate-library} 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 @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. There are two ways to set up an autoloaded function: by calling @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 are the most convenient way to make a function autoload, for packages installed along with Emacs. They 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 to load automatically from @var{filename}. The string @var{filename} specifies the file to load to get the real definition of @var{function}. 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. 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. 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 its 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. Specify @var{type} as @code{keymap} if @var{function} is really a keymap. Various parts of Emacs need to know this information without loading the real definition. An autoloaded keymap loads automatically during key lookup when a prefix key's binding is the symbol @var{function}. Autoloading does not occur for other kinds of access to the keymap. In particular, it does not happen when a Lisp program gets the keymap from the value of a variable and calls @code{define-key}; not even if the variable name is the same symbol @var{function}. @cindex function cell in autoload If @var{function} already has a non-void function definition that is not an autoload object, @code{autoload} does nothing and returns @code{nil}. If the function cell of @var{function} is void, or is already an autoload object, then it is defined as an autoload object like this: @example (autoload @var{filename} @var{docstring} @var{interactive} @var{type}) @end example For example, @example @group (symbol-function 'run-prolog) @result{} (autoload "prolog" 169681 t nil) @end group @end example @noindent In this case, @code{"prolog"} is the name of the file to load, 169681 refers to the documentation string in the @file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}), @code{t} means the function is interactive, and @code{nil} that it is not a macro or a keymap. @end defun @cindex autoload errors The autoloaded file usually contains other definitions and may require or provide one or more features. If the file is not completely loaded (due to an error in the evaluation of its contents), any function 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. If the autoloaded file fails to define the desired Lisp function or macro, then an error is signaled with data @code{"Autoloading failed to define function @var{function-name}"}. @findex update-file-autoloads @findex update-directory-autoloads A magic autoload comment looks like @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}. @kbd{M-x update-directory-autoloads} is even more powerful; it updates 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 definition, it is copied verbatim. 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, 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 @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: @smallexample ;;;###autoload (defun doctor () "Switch to *doctor* buffer and start giving psychotherapy." (interactive) (switch-to-buffer "*doctor*") (doctor-mode)) @end smallexample @noindent Here's what that produces in @file{loaddefs.el}: @smallexample (autoload 'doctor "doctor" "\ Switch to *doctor* buffer and start giving psychotherapy." t) @end smallexample @noindent The backslash and newline immediately following the double-quote are a convention used only in the preloaded 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}. @node Repeated Loading @section Repeated Loading @cindex repeated loading You can load one 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. When you load or reload files, bear in mind that the @code{load} and @code{load-library} functions automatically load a byte-compiled file rather than a non-compiled file of similar name. If you rewrite a file 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 includes, @samp{(compiled; 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 each variable should be reinitialized when you reload the library; @code{defvar} does not change the value if the variable is already initialized. (@xref{Defining Variables}.) 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)) @end example @noindent But this would add multiple elements if the library is reloaded. To avoid the problem, write this: @example (or (assq 'leif-mode minor-mode-alist) (setq minor-mode-alist (cons '(leif-mode " Leif") minor-mode-alist))) @end example To add an element to a list just once, use @code{add-to-list} (@pxref{Setting Variables}). 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 has been loaded before: @example (defvar foo-was-loaded nil) (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} earlier in the file to test whether the @code{provide} call has been executed before. @ifinfo @xref{Named Features}. @end ifinfo @node Named Features @section Features @cindex features @cindex requiring features @cindex providing features @code{provide} and @code{require} are an alternative to @code{autoload} for loading files automatically. They work in terms of named @dfn{features}. Autoloading is triggered by calling a specific function, but a feature is loaded the first time another program asks for it by name. A feature name is a symbol that stands for a collection of functions, variables, etc. The file that defines them should @dfn{provide} the feature. Another program that uses them may ensure they are defined by @dfn{requiring} the feature. This loads the file of definitions if it hasn't been loaded already. To require the presence of a feature, call @code{require} with the feature name as argument. @code{require} looks in the global variable @code{features} to see whether the desired feature has been provided 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. @cindex load error with require For example, in @file{emacs/lisp/prolog.el}, the definition for @code{run-prolog} 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 @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. The @file{comint.el} file contains the following top-level expression: @smallexample (provide 'comint) @end smallexample @noindent This adds @code{comint} to the global @code{features} list, so that @code{(require 'comint)} will henceforth know that nothing needs to be done. @cindex byte-compiling @code{require} When @code{require} is used at top level in a file, it takes effect when you byte-compile that file (@pxref{Byte Compilation}) as well as when you load it. This is in case the required package contains macros that the byte compiler must know about. Although top-level calls to @code{require} are evaluated during byte compilation, @code{provide} calls are not. Therefore, you can 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 @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 @noindent 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 when the file is loaded. @defun provide feature This function announces that @var{feature} is now loaded, or being loaded, into the current Emacs session. This means that the facilities associated with @var{feature} are or will be available for other Lisp programs. The direct effect of calling @code{provide} is to add @var{feature} to the front of the list @code{features} if it is not already in the list. The argument @var{feature} must be a symbol. @code{provide} returns @var{feature}. @smallexample features @result{} (bar bish) (provide 'foo) @result{} foo features @result{} (foo bar bish) @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 @code{provide} calls that occurred during the load are undone. @xref{Autoload}. @end defun @defun require feature &optional filename 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 the feature is not present, then @code{require} loads @var{filename} 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. If loading the file fails to provide @var{feature}, @code{require} signals an error, @samp{Required feature @var{feature} was not provided}. @end defun @defun featurep feature This function returns @code{t} if @var{feature} has been provided in the current Emacs session (i.e., if @var{feature} is a member of @code{features}.) @end defun @defvar features The value of this variable is a list of symbols that are the features loaded in the current Emacs session. Each symbol was put in this list with a call to @code{provide}. The order of the elements in the @code{features} list is not significant. @end defvar @node Unloading @section Unloading @cindex unloading @c Emacs 19 feature You can discard the functions and variables loaded by a library to reclaim memory for other Lisp objects. To do this, use the function @code{unload-feature}: @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{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.) Ordinarily, @code{unload-feature} refuses to unload a library on which other loaded libraries depend. (A library @var{a} depends on library @var{b} if @var{a} contains a @code{require} for @var{b}.) If the optional argument @var{force} is non-@code{nil}, dependencies are ignored and you can unload any library. @end deffn 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 is composed of these kinds of objects: @itemize @bullet @item Symbols that were defined by this library. @item Lists of the form @code{(require . @var{feature})} indicating features that were required. @item Lists of the form @code{(provide . @var{feature})} indicating features that were provided. @end itemize 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. @node Hooks for Loading @section Hooks for Loading @cindex loading hooks @cindex hooks for loading You can ask for code to be executed if and when a particular library is loaded, by calling @code{eval-after-load}. @defun eval-after-load library form This function arranges to evaluate @var{form} at the end of loading the library @var{library}, if and when @var{library} is loaded. If @var{library} is already loaded, it evaluates @var{form} right away. The library name @var{library} must exactly match the argument of @code{load}. To get the proper results when an installed library is found by searching @code{load-path}, you should not include any directory names in @var{library}. An error in @var{form} does not undo the load, but does prevent execution of the rest of @var{form}. @end defun In general, well-designed Lisp programs should not use this feature. The clean and modular ways to interact with a Lisp library are (1) examine and set the library's variables (those which are meant for outside use), and (2) call the library's functions. If you wish to do (1), you can do it immediately---there is no need to wait for when 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 for programs meant for wider use. @defvar after-load-alist An alist of expressions to evaluate if and when particular libraries are loaded. Each element looks like this: @example (@var{filename} @var{forms}@dots{}) @end example The function @code{load} checks @code{after-load-alist} in order to implement @code{eval-after-load}. @end defvar @c Emacs 19 feature