X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/ee6bcc944a43ff57af8297f879fbb01f4b0223e6..2d30d788ae65c10a4baeef2a3502d8f54448dbeb:/lispref/loading.texi diff --git a/lispref/loading.texi b/lispref/loading.texi index 1819d84eaf..29c2480f1f 100644 --- a/lispref/loading.texi +++ b/lispref/loading.texi @@ -37,7 +37,7 @@ containing Lisp code. * 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. -* Features:: Loading a library if it isn't already loaded. +* 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. @@ -50,7 +50,7 @@ containing Lisp code. @code{autoload} creates a placeholder object for a function 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{Features}). Ultimately, all +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 @@ -101,6 +101,10 @@ 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 @@ -132,9 +136,10 @@ 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{:} 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: +@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 @@ -152,18 +157,20 @@ 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" - (expand-file-name "~/emacs")) + "~/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 and then by -the @file{/usr/local/lisplib} directory, +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. The command line options @samp{-l} or @samp{-load} specify a Lisp @@ -172,13 +179,61 @@ the current directory, Emacs 18 temporarily adds the current directory to the front of @code{load-path} so the file can be found there. Newer Emacs versions also find such files in the current directory, but without altering @code{load-path}. + +Dumping Emacs uses a special value of @code{load-path}. If the value of +@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. This is how @code{defun} and -@code{provide} determine whether a load is in progress, so that their -effect can be undone if the load fails. +file, and it is @code{nil} otherwise. +@end defvar + +@defvar load-read-function +This variable specifies an alternate expression-reading function for +@code{load} and @code{eval-region} to use instead of @code{read}. +The function should accept one argument, just as @code{read} does. + +Normally, the variable's value is @code{nil}, which means those +functions should use @code{read}. @end defvar To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}. @@ -188,9 +243,9 @@ effect can be undone if the load fails. @cindex autoload The @dfn{autoload} facility allows you to make a function or macro -available but put off loading its actual definition. 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 +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 @@ -227,6 +282,13 @@ 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}. @@ -240,8 +302,10 @@ object, then it is defined as an autoload object like this: For example, @example +@group (symbol-function 'run-prolog) @result{} (autoload "prolog" 169681 t nil) +@end group @end example @noindent @@ -280,7 +344,7 @@ autoloads for all files in the current directory. @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 @dfn{on the same +the file itself is loaded. To do this, write the form @emph{on the same line} as the magic comment. Since it is in a comment, it does nothing when you load the source file; but @code{update-file-autoloads} copies it to @file{loaddefs.el}, where it is executed while building Emacs. @@ -314,7 +378,6 @@ convention used only in the preloaded Lisp files such as documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. @node Repeated Loading -@comment node-name, next, previous, up @section Repeated Loading @cindex repeated loading @@ -354,11 +417,16 @@ To avoid the problem, write this: (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) + (if (not (boundp 'foo-was-loaded)) @var{execute-first-time-only}) @@ -369,10 +437,10 @@ has been loaded before: If the library uses @code{provide} to provide a named feature, you can use @code{featurep} to test whether the library has been loaded. @ifinfo -@xref{Features}. +@xref{Named Features}. @end ifinfo -@node Features +@node Named Features @section Features @cindex features @cindex requiring features @@ -406,7 +474,7 @@ the definition for @code{run-prolog} includes the following code: @smallexample (defun run-prolog () - "Run an inferior Prolog process, input and output via buffer *prolog*." + "Run an inferior Prolog process, with I/O via buffer *prolog*." (interactive) (require 'comint) (switch-to-buffer (make-comint "prolog" prolog-program-name)) @@ -476,9 +544,10 @@ features @result{} (foo bar bish) @end smallexample -If the file isn't completely loaded, 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}. +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 @@ -520,7 +589,8 @@ This command unloads the library that provided feature @var{feature}. It undefines all functions, macros, and variables defined in that library with @code{defconst}, @code{defvar}, @code{defun}, @code{defmacro}, @code{defsubst} and @code{defalias}. It then restores -any autoloads formerly associated with those symbols. +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 @@ -571,7 +641,8 @@ 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. +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 @@ -582,6 +653,18 @@ 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 of programs to be +released. + @defvar after-load-alist An alist of expressions to evaluate if and when particular libraries are loaded. Each element looks like this: